签入版本

2026-10-08 17:50:29 +08:00
parent 809750b47e
commit e213a9b31d
444 changed files with 39366 additions and 37533 deletions
@@ -1,7 +1,7 @@
-# 2.6 第一个接口调试
+# 2.7 第一个接口调试

 :::tip 概述
-本章通过实际操作，带您完成第一个 API 接口的调试，从登录获取 Token 到调用业务接口。
+本章通过实际操作，带您完成第一个 API 接口的调试，从登录获取 Token 到调用业务接口。所有请求参数与响应字段均以本项目实际接口为准。
 :::

 ## 调试工具
@@ -27,13 +27,17 @@ curl http://localhost:8000/api/captcha
  "ok": true,
  "msg": "操作成功",
  "data": {
-    "key": "a1b2c3d4e5f6...",
-    "image": "data:image/png;base64,iVBOR..."
+    "key": "5c62cae9-3bdb-4356-bc4a-c4c61b7c3bea",
+    "captcha": "data:image/png;base64,iVBORw0KGgoAAAANSUh..."
  }
 }
 ```

-将 `key` 保存备用，`image` 是 Base64 编码的验证码图片。
+将 `key` 保存备用，`captcha` 是 Base64 编码的验证码图片（肉眼读取图片上的字符）。
+
+:::tip
+验证码存储在 Redis 中，有效期 `CAPTCHA_EXPIRE`（默认 300 秒），超过有效期需重新获取。接口同时验证了 PHP → Redis 链路，此步失败优先排查 Redis（见 [2.9 常见问题 FAQ](/zh/quickstart/faq.html)）。
+:::

 ## 步骤二：登录获取 Token

@@ -44,17 +48,17 @@ curl http://localhost:8000/api/captcha
 # -X POST                → 使用 POST 方法
 # -H "Content-Type: ..." → 告诉服务器请求体是 JSON 格式
 # -d '{...}'             → 发送 JSON 请求体
-#   username   → 用户名
-#   password   → 密码
-#   captchaKey → 步骤一返回的验证码 key
-#   captchaCode → 验证码图片上显示的字符
+#   username → 用户名
+#   password → 密码
+#   key      → 步骤一返回的验证码 key（与 captcha 响应字段命名一致）
+#   code     → 验证码图片上显示的字符
 curl -X POST http://localhost:8000/api/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "123456",
-    "captchaKey": "a1b2c3d4e5f6...",
-    "captchaCode": "1234"
+    "key": "5c62cae9-3bdb-4356-bc4a-c4c61b7c3bea",
+    "code": "1234"
  }'
 ```

@@ -80,7 +84,11 @@ curl -X POST http://localhost:8000/api/login \
 }
 ```

-将 `access_token` 保存备用。
+将 `access_token` 保存备用。登录同时会写入登录日志（IP、归属地、浏览器信息），可在「系统管理 → 日志管理 → 登录日志」查看。
+
+:::warning
+验证码参数名为 `key` / `code`（与 `/api/captcha` 响应字段命名保持一致），**不是** `captchaKey` / `captchaCode`。验证码错误时返回 `{"code":1,"msg":"验证码错误"}`。
+:::

 ## 步骤三：调用业务接口

@@ -92,11 +100,11 @@ curl -X POST http://localhost:8000/api/login \
 # -----------------------------------------------------------------------------
 # pageNo=1\&pageSize=10 → 分页参数（\& 是 bash 转义，防止 & 被解释为后台运行符）
 # -H "Authorization: Bearer <token>" → 在请求头中携带 JWT Token
-curl http://localhost:8000/api/user/page?pageNo=1\&pageSize=10 \
+curl "http://localhost:8000/api/user/page?pageNo=1&pageSize=10" \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
 ```

-响应示例：
+响应示例（分页字段固定为 `records / total / current / size / pages`，键名已自动转驼峰）：

 ```json
 {
@@ -115,8 +123,8 @@ curl http://localhost:8000/api/user/page?pageNo=1\&pageSize=10 \
      }
    ],
    "total": 1,
-    "size": 10,
    "current": 1,
+    "size": 10,
    "pages": 1
  }
 }
@@ -144,11 +152,18 @@ curl http://localhost:8000/api/dict/item/getDictItemList/gender \
  -H "Authorization: Bearer <your_token>"

 # -----------------------------------------------------------------------------
-# 刷新 Token（access_token 过期后，用 refresh_token 换取新的）
+# 刷新 Token（access_token 过期后，用 refresh_token 换取新的令牌对）
 # -----------------------------------------------------------------------------
-curl -X POST http://localhost:8000/api/oauth2/token \
+# refresh 为公开接口（无需 access_token）
+curl -X POST http://localhost:8000/api/refresh \
  -H "Content-Type: application/json" \
-  -d '{"grant_type": "refresh_token", "refresh_token": "<your_refresh_token>"}'
+  -d '{"refresh_token": "<your_refresh_token>"}'
+
+# -----------------------------------------------------------------------------
+# 登出（令牌即时失效，需携带 access_token）
+# -----------------------------------------------------------------------------
+curl -X POST http://localhost:8000/api/logout \
+  -H "Authorization: Bearer <your_token>"
 ```

 ## 错误响应示例
@@ -159,23 +174,25 @@ curl -X POST http://localhost:8000/api/oauth2/token \
 {
  "code": 401,
  "ok": false,
-  "msg": "未提供认证令牌",
+  "msg": "未授权，请先登录",
  "data": null
 }
 ```

+HTTP 状态码为 200，前端据 body `code=401` 触发跳转登录。
+
 ### 403 禁止访问（权限不足）

 ```json
 {
  "code": 403,
  "ok": false,
-  "msg": "无访问权限：用户列表",
+  "msg": "无访问权限",
  "data": null
 }
 ```

-### 422 参数验证失败
+### 参数验证失败（FormRequest，code=1）

 ```json
 {
@@ -183,11 +200,27 @@ curl -X POST http://localhost:8000/api/oauth2/token \
  "ok": false,
  "msg": "参数验证失败",
  "data": {
-    "username": "用户名不能为空"
+    "username": ["用户名不能为空"],
+    "password": ["密码不能为空"]
  }
 }
 ```

+### 业务失败（BizException，code=1）
+
+```json
+{
+  "code": 1,
+  "ok": false,
+  "msg": "验证码错误",
+  "data": null
+}
+```
+
+:::tip 统一约定
+所有接口 HTTP 状态码默认 200（403 例外），以响应体 `code` 判断结果：`0` 成功，其余为失败。详见 [8.1 统一响应格式](/zh/api-spec/response.html) 与 [5.16 统一响应与异常抛出](/zh/core/exception.html)。
+:::
+
 ## ApiFox 配置建议

 1. 创建环境，设置变量：
@@ -198,11 +231,12 @@ curl -X POST http://localhost:8000/api/oauth2/token \
   - `Authorization` = `Bearer {{token}}`

 3. 登录请求的「后置操作」中添加脚本自动保存 Token：
-   ```javascript
-   // 解析响应 JSON
-   var response = pm.response.json();
-   // 登录成功时自动将 access_token 保存到环境变量
-   if (response.code === 0) {
-       pm.environment.set("token", response.data.access_token);
-   }
-   ```
+
+```javascript
+// 解析响应 JSON
+var response = pm.response.json();
+// 登录成功时自动将 access_token 保存到环境变量
+if (response.code === 0) {
+    pm.environment.set("token", response.data.access_token);
+}
+```