签入版本

2026-09-12 23:12:15 +08:00
commit 91998056ca
1841 changed files with 341325 additions and 0 deletions
@@ -0,0 +1,253 @@
+# 第一个接口调试
+
+本章节介绍如何调试后端 API 接口，通过完整的登录流程（获取验证码 → 登录 → 获取令牌 → 调用业务接口）帮助你快速理解项目的接口调用方式。
+
+:::tip 温馨提示
+开始调试前，请确保已完成以下步骤：
+1. 后端服务已启动（参见 [后端启动](/zh/volume1/backend)）
+2. 数据库已初始化（参见 [数据库初始化](/zh/volume1/database)）
+3. Redis 服务已启动
+:::
+
+## 验证后端服务
+
+后端服务启动后，在浏览器中访问以下地址验证服务是否正常运行：
+
+```
+http://127.0.0.1:8021/api/v1/captcha
+```
+
+如果返回类似以下 JSON 数据，说明后端服务已正常启动：
+
+```json
+{
+    "code": 0,
+    "data": {
+        "captcha": "data:image/png;base64,iVBORw0KG...",
+        "key": "sl1dhi-ejqV2PWH8tYDE1pVNaRiccsrQ"
+    },
+    "msg": "操作成功",
+    "ok": true
+}
+```
+
+## 第一步：获取验证码
+
+登录前需要先获取图形验证码。使用浏览器或 curl 工具访问验证码接口：
+
+```bash
+# 使用 curl 获取验证码
+curl -X GET "http://127.0.0.1:8021/api/v1/captcha"
+```
+
+ 响应示例
+
+```json
+{
+    "code": 0,
+    "data": {
+        "captcha": "data:image/png;base64,iVBORw0KG...",
+        "key": "sl1dhi-ejqV2PWH8tYDE1pVNaRiccsrQ"
+    },
+    "msg": "操作成功",
+    "ok": true
+}
+```
+
+:::tip 温馨提示
+响应中的 `key` 是验证码的唯一标识，后续登录时需要使用。`captcha` 是 Base64 编码的验证码图片，可以在浏览器中直接查看。
+:::
+
+ 记录关键信息
+
+```
+key: sl1dhi-ejqV2PWH8tYDE1pVNaRiccsrQ
+验证码图片中的文字: （查看图片获取）
+```
+
+## 第二步：登录获取 Token
+
+使用验证码和账号信息进行登录，获取 JWT 访问令牌。
+
+```bash
+# 使用 curl 登录
+curl -X POST "http://127.0.0.1:8021/api/v1/login" \
+    -H "Content-Type: application/json" \
+    -d '{
+    "username": "admin",
+    "password": "123456",
+    "captcha_code": "验证码文字",
+    "key": "第一步获取的key"
+    }'
+```
+
+ 成功响应
+
+```json
+{
+    "code": 0,
+    "data": {
+        "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjEsInVzZXJuYW1lIjoiYWRtaW4iLCJyZWFsbmFtZSI6Ilx1N2JhMVx1NzQwNlx1NTQ1OCIsImV4cCI6MTc4ODYxNDk0NiwiaWF0IjoxNzg4NjEzNzQ2fQ.xxxxxxxxxxx"
+    },
+    "msg": "登录成功",
+    "ok": true
+}
+```
+
+ 失败响应示例
+
+```json
+{
+    "code": 1,
+    "data": null,
+    "msg": "验证码错误或已过期",
+    "ok": false
+}
+```
+
+:::danger 常见登录失败原因
+| 错误信息 | 原因 | 解决方式 |
+|:----|:----|:----|
+| 验证码错误或已过期 | 验证码输入错误或超过 5 分钟有效期 | 重新获取验证码 |
+| 账号或密码错误 | 用户名或密码不正确 | 使用默认账号 `admin/123456` |
+| 账号已被锁定 | 连续登录失败超过 5 次 | 等待 5 分钟后重试 |
+| 参数校验失败 | 请求体格式错误 | 检查 JSON 格式是否正确 |
+:::
+
+ 记录 Token
+
+```
+token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+```
+
+:::tip 温馨提示
+Token 是后续所有认证接口的通行证，请妥善保存。默认有效期为 20 分钟（可通过 `.env` 中的 `JWT_EXPIRE_MINUTES` 修改）。
+:::
+
+## 第三步：使用 Token 调用业务接口
+
+Token 获取完成后，即可调用需要认证的业务接口。
+
+ 调用用户列表接口
+
+```bash
+# 使用 curl 调用用户列表接口
+curl -X GET "http://127.0.0.1:8021/api/v1/user/list?pageNo=1&pageSize=10" \
+    -H "Authorization: Bearer <你的token>"
+```
+
+ 成功响应
+
+```json
+{
+    "code": 0,
+    "data": [
+        {
+            "id": 1,
+            "username": "admin",
+            "realname": "超级管理员",
+            "status": 1,
+            "dept_id": 1,
+            "create_time": "2024-01-01 00:00:00"
+        }
+    ],
+    "count": 1,
+    "msg": "操作成功",
+    "ok": true
+}
+```
+
+:::tip 温馨提示
+响应中的 `data` 是用户列表数据，`count` 是总记录数。分页参数 `pageNo` 默认为 1，`pageSize` 默认为 10。
+:::
+
+## 接口调用流程图
+
+```
+┌─────────────┐ ┌─────────────┐ ┌─────────────┐
+│ 获取验证码 │────▶│ 用户登录 │────▶│ 调用业务接口 │
+│ GET /captcha │ │ POST /login │ │ GET/POST │
+└─────────────┘ └─────────────┘ └─────────────┘
+ │ │ │
+ ▼ ▼ ▼
+ key JWT Token 业务数据响应
+ captcha (20分钟有效)
+```
+
+## 使用 Postman 调试
+
+除了 curl，也可以使用 Postman 等 API 调试工具进行接口调试：
+
+1. **获取验证码**：GET 请求 `http://127.0.0.1:8021/api/v1/captcha`
+2. **登录获取 Token**：POST 请求 `http://127.0.0.1:8021/api/v1/login`，Body 选择 JSON 格式
+3. **配置 Token**：在请求头中添加 `Authorization: Bearer <你的token>`
+4. **调用业务接口**：GET/POST 请求对应的业务接口
+
+## API 响应格式说明
+
+所有接口统一返回以下 JSON 格式：
+
+```json
+// 成功响应
+{
+    "code": 0, // 状态码：0=成功，1=失败
+    "data": {}, // 业务数据
+    "msg": "操作成功", // 提示信息
+    "ok": true // 业务状态
+}
+
+// 失败响应
+{
+    "code": 1,
+    "data": null,
+    "msg": "错误信息",
+    "ok": false
+}
+
+// 分页响应
+{
+    "code": 0,
+    "data": [], // 列表数据
+    "count": 100, // 总记录数
+    "msg": "操作成功",
+    "ok": true
+}
+```
+
+:::tip HTTP 状态码
+无论业务成功或失败，HTTP 状态码始终为 `200`。业务状态通过 `code` 字段区分：`0` 表示成功，`1` 表示失败。
+:::
+
+## 常见问题
+
+ 接口返回 401 Unauthorized
+
+```
+原因：未提供 Token 或 Token 已过期
+解决：重新登录获取 Token，或检查请求头中的 Authorization 配置
+```
+
+ 接口返回 403 Forbidden
+
+```
+原因：当前用户无该接口的访问权限
+解决：使用 admin 账号（ID=1 拥有全部权限），或检查角色权限配置
+```
+
+ 接口返回 422 Validation Error
+
+```
+原因：请求参数校验失败
+解决：检查请求体 JSON 格式和字段是否符合接口定义
+```
+
+ Token 过期
+
+```
+原因：Token 超过有效期（默认 20 分钟）
+解决：重新登录获取新 Token
+```
+
+## 总结
+
+本章节通过完整的登录流程演示了如何调试后端 API 接口：获取验证码 → 登录获取 Token → 调用业务接口。通过这个流程，你已经掌握了项目接口的基本调用方式和认证机制。后续开发中，可以使用 curl 或 Postman 等工具调试所有接口。如果遇到问题，请参见 [常见问题FAQ](/zh/volume1/faq) 章节。