372 lines
9.3 KiB
Markdown
372 lines
9.3 KiB
Markdown
# 第一个接口调试
|
||
|
||
本章节介绍如何调试后端 API 接口，通过完整的登录流程（获取验证码 → 登录 → 获取令牌 → 调用业务接口）帮助你快速理解项目的接口调用方式。
|
||
|
||
:::tip 温馨提示
|
||
开始调试前，请确保已完成以下步骤：
|
||
1. 后端服务已启动（参见 [后端启动](/zh/volume1/backend)）
|
||
2. 数据库已初始化（参见 [数据库初始化](/zh/volume1/database)）
|
||
3. Redis 服务已启动
|
||
:::
|
||
|
||
## 接口调用流程图
|
||
|
||
```
|
||
+-- -- -- --+ +-- -- -- --+ +-- -- -- --+ +-- -- -- --+
|
||
| 获取验证码 |-->| 用户登录 |-->| 配置 Token|-->| 调用业务接口|
|
||
| GET /captcha| | POST /login| | Authorization| | GET/POST |
|
||
+-- -- -- --+ +-- -- -- --+ +-- -- -- --+ +-- -- -- --+
|
||
| | |
|
||
v v v
|
||
key JWT Token 业务数据响应
|
||
captcha (20分钟有效)
|
||
```
|
||
|
||
## 第一步：获取验证码
|
||
|
||
登录前需要先获取图形验证码。验证码接口无需认证，可直接访问。
|
||
|
||
+ 请求
|
||
|
||
```
|
||
GET http://127.0.0.1:8000/login/captcha
|
||
```
|
||
|
||
+ 使用 curl 测试
|
||
|
||
```bash
|
||
curl http://127.0.0.1:8000/login/captcha
|
||
```
|
||
|
||
+ 响应示例
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": {
|
||
"captcha": "data:image/png;base64,iVBORw0KG...",
|
||
"key": 1
|
||
},
|
||
"msg": "操作成功",
|
||
"ok": true
|
||
}
|
||
```
|
||
|
||
:::tip 温馨提示
|
||
响应中的 `key` 是验证码记录的 ID，后续登录时需要使用。`captcha` 是 Base64 编码的验证码图片，可以在浏览器中直接粘贴地址查看。
|
||
:::
|
||
|
||
+ 记录关键信息
|
||
|
||
```
|
||
key: 1
|
||
验证码图片中的文字: （查看图片获取）
|
||
```
|
||
|
||
:::tip 超级验证码
|
||
开发测试时，系统内置了超级验证码 `618618`，使用该验证码可以跳过图片验证码校验，方便调试。
|
||
:::
|
||
|
||
## 第二步：登录获取 Token
|
||
|
||
使用验证码和账号信息进行登录，获取 JWT 访问令牌。
|
||
|
||
+ 请求
|
||
|
||
```
|
||
POST http://127.0.0.1:8000/login/login
|
||
Content-Type: application/json
|
||
```
|
||
|
||
+ 请求体
|
||
|
||
```json
|
||
{
|
||
"username": "admin",
|
||
"password": "123456",
|
||
"code": "618618",
|
||
"key": 1
|
||
}
|
||
```
|
||
|
||
+ 使用 curl 测试
|
||
|
||
```bash
|
||
curl -X POST "http://127.0.0.1:8000/login/login" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"username": "admin",
|
||
"password": "123456",
|
||
"code": "618618",
|
||
"key": 1
|
||
}'
|
||
```
|
||
|
||
+ 成功响应
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": {
|
||
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjEsInVzZXJuYW1lIjoiYWRtaW4iLCJyZWFsbmFtZSI6Ilx1N2JhMVx1NzQwNlx1NTQ1OCIsImV4cCI6MTc4ODYxNDk0NiwiaWF0IjoxNzg4NjEzNzQ2fQ.xxxxxxxxxxx"
|
||
},
|
||
"msg": "登录成功",
|
||
"ok": true
|
||
}
|
||
```
|
||
|
||
+ 失败响应示例
|
||
|
||
```json
|
||
{
|
||
"code": 1,
|
||
"data": null,
|
||
"msg": "验证码错误或已过期",
|
||
"ok": false
|
||
}
|
||
```
|
||
|
||
:::danger 常见登录失败原因
|
||
| 错误信息 | 原因 | 解决方式 |
|
||
|:----|:----|:----|
|
||
| 验证码错误或已过期 | 验证码输入错误或超过 5 分钟有效期 | 重新获取验证码，或使用超级验证码 `618618` |
|
||
| 用户不存在 | 用户名不正确 | 使用默认账号 `admin` |
|
||
| 密码不正确 | 密码不正确 | 使用默认密码 `123456` |
|
||
| 账号已被禁用 | 用户状态被禁用 | 联系管理员启用账号 |
|
||
:::
|
||
|
||
+ 记录 Token
|
||
|
||
```
|
||
token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
||
```
|
||
|
||
:::tip 温馨提示
|
||
Token 是后续所有认证接口的通行证，请妥善保存。默认有效期为 20 分钟。
|
||
:::
|
||
|
||
## 第三步：使用 Token 调用业务接口
|
||
|
||
Token 获取完成后，即可调用需要认证的业务接口。所有需要认证的接口都需要在请求头中携带 `Authorization: Bearer <token>`。
|
||
|
||
### 调用案例分页接口
|
||
|
||
+ 请求
|
||
|
||
```
|
||
GET http://127.0.0.1:8000/example/page?pageNo=1&pageSize=10
|
||
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
||
```
|
||
|
||
+ 使用 curl 测试
|
||
|
||
```bash
|
||
curl -X GET "http://127.0.0.1:8000/example/page?pageNo=1&pageSize=10" \
|
||
-H "Authorization: Bearer <你的token>"
|
||
```
|
||
|
||
+ 成功响应
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": {
|
||
"records": [
|
||
{
|
||
"id": 1,
|
||
"name": "示例案例",
|
||
"type": "demo",
|
||
"status": 1,
|
||
"createUser": "admin",
|
||
"createTime": "2026-01-01 00:00:00"
|
||
}
|
||
],
|
||
"total": 1,
|
||
"size": 10,
|
||
"current": 1,
|
||
"pages": 1
|
||
},
|
||
"msg": "操作成功",
|
||
"ok": true
|
||
}
|
||
```
|
||
|
||
### 调用添加案例接口
|
||
|
||
+ 请求
|
||
|
||
```
|
||
POST http://127.0.0.1:8000/example/add
|
||
Content-Type: application/json
|
||
Authorization: Bearer <你的token>
|
||
```
|
||
|
||
+ 请求体
|
||
|
||
```json
|
||
{
|
||
"name": "新增案例",
|
||
"type": "demo",
|
||
"status": 1,
|
||
"sort": 1
|
||
}
|
||
```
|
||
|
||
:::danger 演示模式限制
|
||
如果 `.env` 中的 `DJANGO_DEMO=True`，所有写操作（add/update/delete/status）将返回"演示环境，暂无操作权限"。开发调试时请设置 `DJANGO_DEMO=False`。
|
||
:::
|
||
|
||
### 调用更新案例接口
|
||
|
||
+ 请求
|
||
|
||
```
|
||
PUT http://127.0.0.1:8000/example/update
|
||
Content-Type: application/json
|
||
Authorization: Bearer <你的token>
|
||
```
|
||
|
||
+ 请求体
|
||
|
||
```json
|
||
{
|
||
"id": 1,
|
||
"name": "更新后的案例名称",
|
||
"type": "demo",
|
||
"status": 1
|
||
}
|
||
```
|
||
|
||
### 调用删除案例接口
|
||
|
||
+ 请求
|
||
|
||
```
|
||
DELETE http://127.0.0.1:8000/example/delete/1
|
||
Authorization: Bearer <你的token>
|
||
```
|
||
|
||
:::tip 批量删除
|
||
删除接口支持批量删除，多个 ID 用逗号分隔：`DELETE /example/delete/1,2,3`
|
||
:::
|
||
|
||
## API 响应格式说明
|
||
|
||
所有接口统一返回以下 JSON 格式（定义在 `utils/R.py` 中）：
|
||
|
||
```json
|
||
// 成功响应
|
||
{
|
||
"code": 0, // 状态码：0=成功，1=失败
|
||
"data": {}, // 业务数据
|
||
"msg": "操作成功", // 提示信息
|
||
"ok": true // 业务状态
|
||
}
|
||
|
||
// 失败响应
|
||
{
|
||
"code": 1,
|
||
"data": null,
|
||
"msg": "错误信息",
|
||
"ok": false
|
||
}
|
||
|
||
// 分页响应
|
||
{
|
||
"code": 0,
|
||
"data": {
|
||
"records": [], // 列表数据
|
||
"total": 100, // 总记录数
|
||
"size": 10, // 每页记录数
|
||
"current": 1, // 当前页码
|
||
"pages": 10 // 总页数
|
||
},
|
||
"msg": "操作成功",
|
||
"ok": true
|
||
}
|
||
```
|
||
|
||
:::tip HTTP 状态码
|
||
无论业务成功或失败，HTTP 状态码始终为 `200`。业务状态通过 `code` 字段区分：`0` 表示成功，`1` 表示失败。
|
||
:::
|
||
|
||
## 使用 Postman 调试
|
||
|
||
除了 curl 命令行，也可以使用 [Postman](https://www.postman.com/) 等 API 调试工具：
|
||
|
||
1. **获取验证码**：新建 GET 请求，URL 填 `http://127.0.0.1:8000/login/captcha`，发送请求后查看响应中的 `key` 值。
|
||
|
||
2. **登录**：新建 POST 请求，URL 填 `http://127.0.0.1:8000/login/login`，Body 选择 `raw` + `JSON`，填写登录参数。记录响应中的 `access_token`。
|
||
|
||
3. **调用业务接口**：新建请求，在 `Authorization` 标签页中，Type 选择 `Bearer Token`，Token 填写上一步获取的 `access_token`。然后在 `Params` 中填写查询参数，发送请求即可。
|
||
|
||
## 使用浏览器开发者工具调试
|
||
|
||
1. 打开浏览器，按 `F12` 打开开发者工具。
|
||
2. 切换到 `Network` 标签页。
|
||
3. 在前端页面进行操作（如登录、查询列表），观察 Network 中的请求。
|
||
4. 点击某个请求，查看 `Headers`（请求头）、`Payload`（请求参数）和 `Response`（响应数据）。
|
||
|
||
:::tip 温馨提示
|
||
前端所有 API 请求都通过 Vite 代理转发到后端。在 Network 中看到的请求地址是 `http://localhost:8001/api/...`，实际会被代理到 `http://127.0.0.1:8000/...`。
|
||
:::
|
||
|
||
## 权限说明
|
||
|
||
项目采用 RBAC 权限模型，每个接口对应一个权限字符串（如 `sys:example:page`）：
|
||
|
||
| 接口 | 权限标识 | 说明 |
|
||
|:----|:----|:----|
|
||
| `GET /example/page` | `sys:example:page` | 分页查询 |
|
||
| `GET /example/detail/<id>` | `sys:example:detail` | 查询详情 |
|
||
| `POST /example/add` | `sys:example:add` | 添加记录 |
|
||
| `PUT /example/update` | `sys:example:update` | 更新记录 |
|
||
| `DELETE /example/delete/<id>` | `sys:example:delete` | 删除记录 |
|
||
| `PUT /example/status` | `sys:example:status` | 更新状态 |
|
||
|
||
:::tip 温馨提示
|
||
`admin` 用户（ID=1）是超级管理员，拥有全部权限，不受权限检查限制。开发调试时建议使用 `admin` 账号。
|
||
:::
|
||
|
||
## 常见问题
|
||
|
||
+ 接口返回 401 Unauthorized
|
||
|
||
```
|
||
原因：未提供 Token 或 Token 已过期
|
||
解决：重新登录获取 Token，检查请求头中的 Authorization 格式是否正确
|
||
```
|
||
|
||
+ 接口返回权限不足
|
||
|
||
```json
|
||
{"code": 1, "data": null, "msg": "权限不足", "ok": false}
|
||
```
|
||
|
||
```
|
||
原因：当前用户无该接口的访问权限
|
||
解决：使用 admin 账号（ID=1 拥有全部权限），或检查角色权限配置
|
||
```
|
||
|
||
+ Token 过期
|
||
|
||
```
|
||
原因：Token 超过有效期（默认 20 分钟）
|
||
解决：重新登录获取新 Token
|
||
```
|
||
|
||
+ 演示环境限制
|
||
|
||
```json
|
||
{"code": 1, "data": null, "msg": "演示环境，暂无操作权限", "ok": false}
|
||
```
|
||
|
||
```
|
||
原因：.env 中 DJANGO_DEMO=True，写操作被限制
|
||
解决：将 .env 中的 DJANGO_DEMO 设置为 False
|
||
```
|
||
|
||
## 总结
|
||
|
||
本章节通过完整的登录流程演示了如何调试后端 API 接口：获取验证码 → 登录获取 Token → 配置认证信息 → 调用业务接口。通过这个流程，你已经掌握了项目接口的基本调用方式和认证机制。后续开发中，可以使用 curl、Postman 或浏览器开发者工具调试接口。如果遇到问题，请参见 [常见问题FAQ](/zh/volume1/faq) 章节。
|