签入版本

2026-09-29 10:14:04 +08:00
parent 3e5fc01124
commit d6b552103d
1664 changed files with 298944 additions and 0 deletions
@@ -0,0 +1,208 @@
+# 2.6 第一个接口调试
+
+:::tip 概述
+本章通过实际操作，带您完成第一个 API 接口的调试，从登录获取 Token 到调用业务接口。
+:::
+
+## 调试工具
+
+推荐使用以下工具进行 API 调试：
+
+- **ApiFox**：图形化 API 调试工具（https://apifox.com/）
+- **curl**：命令行工具（系统自带）
+- **浏览器开发者工具**：F12 → Network 面板
+
+## 步骤一：获取验证码
+
+```bash
+# GET 请求获取验证码（返回 Base64 编码的图片 + 验证码 key）
+curl http://localhost:8000/api/captcha
+```
+
+响应示例：
+
+```json
+{
+  "code": 0,
+  "ok": true,
+  "msg": "操作成功",
+  "data": {
+    "key": "a1b2c3d4e5f6...",
+    "image": "data:image/png;base64,iVBOR..."
+  }
+}
+```
+
+将 `key` 保存备用，`image` 是 Base64 编码的验证码图片。
+
+## 步骤二：登录获取 Token
+
+```bash
+# -----------------------------------------------------------------------------
+# 登录接口（POST + JSON）
+# -----------------------------------------------------------------------------
+# -X POST                → 使用 POST 方法
+# -H "Content-Type: ..." → 告诉服务器请求体是 JSON 格式
+# -d '{...}'             → 发送 JSON 请求体
+#   username   → 用户名
+#   password   → 密码
+#   captchaKey → 步骤一返回的验证码 key
+#   captchaCode → 验证码图片上显示的字符
+curl -X POST http://localhost:8000/api/login \
+  -H "Content-Type: application/json" \
+  -d '{
+    "username": "admin",
+    "password": "123456",
+    "captchaKey": "a1b2c3d4e5f6...",
+    "captchaCode": "1234"
+  }'
+```
+
+响应示例：
+
+```json
+{
+  "code": 0,
+  "ok": true,
+  "msg": "登录成功",
+  "data": {
+    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
+    "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
+    "token_type": "Bearer",
+    "expires_in": 7200,
+    "user": {
+      "id": 1,
+      "username": "admin",
+      "realname": "管理员",
+      "avatar": ""
+    }
+  }
+}
+```
+
+将 `access_token` 保存备用。
+
+## 步骤三：调用业务接口
+
+使用 Token 调用需要认证的接口：
+
+```bash
+# -----------------------------------------------------------------------------
+# 获取用户分页列表（GET + Authorization 头）
+# -----------------------------------------------------------------------------
+# pageNo=1\&pageSize=10 → 分页参数（\& 是 bash 转义，防止 & 被解释为后台运行符）
+# -H "Authorization: Bearer <token>" → 在请求头中携带 JWT Token
+curl http://localhost:8000/api/user/page?pageNo=1\&pageSize=10 \
+  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
+```
+
+响应示例：
+
+```json
+{
+  "code": 0,
+  "ok": true,
+  "msg": "操作成功",
+  "data": {
+    "records": [
+      {
+        "id": 1,
+        "username": "admin",
+        "realname": "管理员",
+        "status": 1,
+        "statusText": "启用",
+        "createTime": "2026-01-01 00:00:00"
+      }
+    ],
+    "total": 1,
+    "size": 10,
+    "current": 1,
+    "pages": 1
+  }
+}
+```
+
+## 步骤四：测试其他接口
+
+```bash
+# -----------------------------------------------------------------------------
+# 获取当前登录用户信息
+# -----------------------------------------------------------------------------
+curl http://localhost:8000/api/index/getUser \
+  -H "Authorization: Bearer <your_token>"
+
+# -----------------------------------------------------------------------------
+# 获取当前用户的菜单列表（用于前端动态路由）
+# -----------------------------------------------------------------------------
+curl http://localhost:8000/api/index/getMenus \
+  -H "Authorization: Bearer <your_token>"
+
+# -----------------------------------------------------------------------------
+# 获取字典项（gender = 性别字典的编码）
+# -----------------------------------------------------------------------------
+curl http://localhost:8000/api/dict/item/getDictItemList/gender \
+  -H "Authorization: Bearer <your_token>"
+
+# -----------------------------------------------------------------------------
+# 刷新 Token（access_token 过期后，用 refresh_token 换取新的）
+# -----------------------------------------------------------------------------
+curl -X POST http://localhost:8000/api/oauth2/token \
+  -H "Content-Type: application/json" \
+  -d '{"grant_type": "refresh_token", "refresh_token": "<your_refresh_token>"}'
+```
+
+## 错误响应示例
+
+### 401 未授权（Token 缺失或无效）
+
+```json
+{
+  "code": 401,
+  "ok": false,
+  "msg": "未提供认证令牌",
+  "data": null
+}
+```
+
+### 403 禁止访问（权限不足）
+
+```json
+{
+  "code": 403,
+  "ok": false,
+  "msg": "无访问权限：用户列表",
+  "data": null
+}
+```
+
+### 422 参数验证失败
+
+```json
+{
+  "code": 1,
+  "ok": false,
+  "msg": "参数验证失败",
+  "data": {
+    "username": "用户名不能为空"
+  }
+}
+```
+
+## ApiFox 配置建议
+
+1. 创建环境，设置变量：
+   - `base_url` = `http://localhost:8000`
+   - `token` = 登录后填入 access_token
+
+2. 在请求头中使用变量：
+   - `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);
+   }
+   ```