# 第一个接口调试 本章节介绍如何调试后端 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 `。 ### 调用案例分页接口 + 请求 ``` 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/` | `sys:example:detail` | 查询详情 | | `POST /example/add` | `sys:example:add` | 添加记录 | | `PUT /example/update` | `sys:example:update` | 更新记录 | | `DELETE /example/delete/` | `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) 章节。