签入版本
This commit is contained in:
@@ -0,0 +1,256 @@
|
||||
# 第一个接口调试
|
||||
|
||||
本章节介绍如何使用 `curl` 或 `Postman` 等工具调试后端 API 接口，通过完整的登录流程（获取验证码 → 登录 → 获取令牌 → 调用业务接口）帮助你快速理解项目的接口调用方式。
|
||||
|
||||
:::tip 温馨提示
|
||||
开始调试前，请确保已完成以下步骤：
|
||||
1. 后端服务已启动（参见 [后端启动](/zh/volume1/backend)）
|
||||
2. 数据库已初始化（参见 [数据库初始化](/zh/volume1/database)）
|
||||
3. Redis 服务已启动
|
||||
:::
|
||||
|
||||
## 接口调试工具
|
||||
|
||||
本项目后端基于 Tornado 框架，不提供内置的 Swagger 文档。推荐使用以下工具进行接口调试：
|
||||
|
||||
| 工具 | 说明 |
|
||||
|:-----|:-----|
|
||||
| `curl` | 命令行 HTTP 客户端，适合快速测试 |
|
||||
| `Postman` | 图形化 API 调试工具，支持集合管理和环境变量 |
|
||||
| 浏览器开发者工具 | 适合调试 GET 请求 |
|
||||
|
||||
## 第一步：获取验证码
|
||||
|
||||
登录前需要先获取图形验证码：
|
||||
|
||||
```bash
|
||||
curl http://127.0.0.1:8041/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 -X POST "http://127.0.0.1:8041/api/v1/login" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"username": "admin",
|
||||
"password": "123456",
|
||||
"code": "图片中的验证码文字",
|
||||
"key": "第一步获取的key"
|
||||
}'
|
||||
```
|
||||
|
||||
+ 成功响应
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"data": {
|
||||
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
|
||||
},
|
||||
"msg": "登录成功",
|
||||
"ok": true
|
||||
}
|
||||
```
|
||||
|
||||
+ 失败响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 1,
|
||||
"data": null,
|
||||
"msg": "验证码错误或已过期",
|
||||
"ok": false
|
||||
}
|
||||
```
|
||||
|
||||
:::danger 常见登录失败原因
|
||||
| 错误信息 | 原因 | 解决方式 |
|
||||
|:----|:----|:----|
|
||||
| 验证码错误或已过期 | 验证码输入错误或超过 5 分钟有效期 | 重新获取验证码 |
|
||||
| 账号或密码错误 | 用户名或密码不正确 | 使用默认账号 `admin/123456` |
|
||||
| 账号已被锁定 | 连续登录失败超过 5 次 | 等待 5 分钟后重试 |
|
||||
| 登录失败次数过多 | 同一 IP+用户名连续失败 | 等待锁定时间后重试 |
|
||||
:::
|
||||
|
||||
+ 记录 Token
|
||||
|
||||
```
|
||||
token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
||||
```
|
||||
|
||||
:::tip 温馨提示
|
||||
Token 是后续所有认证接口的通行证，请妥善保存。默认有效期为 20 分钟（可通过 `.env` 中的 `JWT_EXPIRE_MINUTES` 修改）。
|
||||
:::
|
||||
|
||||
## 第三步：使用 Token 调用业务接口
|
||||
|
||||
Token 获取后，在后续请求的 `Authorization` 头中携带即可调用需要认证的接口：
|
||||
|
||||
```bash
|
||||
# 获取用户列表
|
||||
curl -X GET "http://127.0.0.1:8041/api/v1/user/page?page=1&limit=10" \
|
||||
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
|
||||
```
|
||||
|
||||
+ 成功响应
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"data": {
|
||||
"list": [
|
||||
{
|
||||
"id": 1,
|
||||
"username": "admin",
|
||||
"realname": "超级管理员",
|
||||
"status": 0,
|
||||
"dept_id": 1,
|
||||
"create_time": "2024-01-01 00:00:00"
|
||||
}
|
||||
],
|
||||
"total": 1
|
||||
},
|
||||
"msg": "操作成功",
|
||||
"ok": true
|
||||
}
|
||||
```
|
||||
|
||||
## 接口调用流程图
|
||||
|
||||
```
|
||||
┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ ┌──────────────┐
|
||||
│ 获取验证码 │───▶│ 用户登录 │───▶│ 携带 Token 请求 │───▶│ 业务数据响应 │
|
||||
│ GET /captcha │ │ POST /login │ │ Authorization: │ │ GET/POST │
|
||||
└──────────────┘ └──────────────┘ │ Bearer <token> │ └──────────────┘
|
||||
└──────────────────┘
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
key JWT Token 业务数据
|
||||
captcha (20分钟有效)
|
||||
```
|
||||
|
||||
## 更多接口示例
|
||||
|
||||
```bash
|
||||
# 获取验证码
|
||||
curl http://127.0.0.1:8041/api/v1/captcha
|
||||
|
||||
# 登录
|
||||
curl -X POST "http://127.0.0.1:8041/api/v1/login" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"username":"admin","password":"123456","code":"验证码","key":"key值"}'
|
||||
|
||||
# 健康检查（无需认证）
|
||||
curl http://127.0.0.1:8041/api/v1/health
|
||||
|
||||
# 获取用户列表（需要认证）
|
||||
curl -X GET "http://127.0.0.1:8041/api/v1/user/page?page=1&limit=10" \
|
||||
-H "Authorization: Bearer <token>"
|
||||
|
||||
# 刷新 Token
|
||||
curl -X POST "http://127.0.0.1:8041/api/v1/token/refresh" \
|
||||
-H "Authorization: Bearer <token>"
|
||||
|
||||
# 获取字典下拉数据（需要认证）
|
||||
curl -X GET "http://127.0.0.1:8041/api/v1/dict/data/link_type" \
|
||||
-H "Authorization: Bearer <token>"
|
||||
```
|
||||
|
||||
## API 响应格式说明
|
||||
|
||||
所有接口统一返回以下 JSON 格式：
|
||||
|
||||
```json
|
||||
// 成功响应
|
||||
{
|
||||
"code": 0,
|
||||
"data": {},
|
||||
"msg": "操作成功",
|
||||
"ok": true
|
||||
}
|
||||
|
||||
// 失败响应
|
||||
{
|
||||
"code": 1,
|
||||
"data": null,
|
||||
"msg": "错误信息",
|
||||
"ok": false
|
||||
}
|
||||
|
||||
// 分页响应
|
||||
{
|
||||
"code": 0,
|
||||
"data": {
|
||||
"list": [],
|
||||
"total": 100
|
||||
},
|
||||
"msg": "操作成功",
|
||||
"ok": true
|
||||
}
|
||||
```
|
||||
|
||||
:::tip HTTP 状态码
|
||||
业务成功时 HTTP 状态码为 `200`，通过 `code` 字段区分业务状态：`0` 表示成功，非 `0` 表示失败。认证失败（401）、权限不足（403）等会返回对应的 HTTP 状态码。
|
||||
:::
|
||||
|
||||
## 常见问题
|
||||
|
||||
+ 接口返回 401 Unauthorized
|
||||
|
||||
```
|
||||
原因：未提供 Token 或 Token 已过期
|
||||
解决：重新登录获取 Token，检查 Authorization 头格式是否正确（Bearer <token>）
|
||||
```
|
||||
|
||||
+ 接口返回 403 Forbidden
|
||||
|
||||
```
|
||||
原因：当前用户无该接口的访问权限
|
||||
解决：使用 admin 账号（ID=1 拥有全部权限），或检查角色权限配置
|
||||
```
|
||||
|
||||
+ Token 过期
|
||||
|
||||
```
|
||||
原因：Token 超过有效期（默认 20 分钟）
|
||||
解决：重新登录获取新 Token，或调用 POST /api/v1/token/refresh 刷新
|
||||
```
|
||||
|
||||
+ 接口返回演示模式限制
|
||||
|
||||
```
|
||||
原因：.env 中 TORNADO_DEMO=True，写操作被禁止
|
||||
解决：开发环境设置 TORNADO_DEMO=False
|
||||
```
|
||||
|
||||
## 总结
|
||||
|
||||
本章节通过完整的登录流程演示了如何调试后端 API 接口：获取验证码 → 登录获取 Token → 携带 Token 调用业务接口。通过这个流程，你已经掌握了项目接口的基本调用方式和认证机制。如果遇到问题，请参见 [常见问题FAQ](/zh/volume1/faq) 章节。
|
||||
Reference in New Issue
Block a user