小蚂蚁云

Appearance

Become a sponsor
企业级中台解决方案
企业级中台解决方案

第一个接口调试 ​

本章节介绍如何调试后端 API 接口，通过完整的登录流程（获取验证码 → 登录 → 获取令牌 → 调用业务接口）帮助你快速理解项目的接口调用方式。

温馨提示

开始调试前，请确保已完成以下步骤：

  1. 后端服务已启动（参见 后端启动）
  2. 数据库已初始化（参见 数据库初始化）
  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
}

温馨提示

响应中的 key 是验证码记录的 ID，后续登录时需要使用。captcha 是 Base64 编码的验证码图片，可以在浏览器中直接粘贴地址查看。

  • 记录关键信息
key: 1
验证码图片中的文字: （查看图片获取）

超级验证码

开发测试时，系统内置了超级验证码 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
}

常见登录失败原因

错误信息原因解决方式
验证码错误或已过期验证码输入错误或超过 5 分钟有效期重新获取验证码，或使用超级验证码 618618
用户不存在用户名不正确使用默认账号 admin
密码不正确密码不正确使用默认密码 123456
账号已被禁用用户状态被禁用联系管理员启用账号
  • 记录 Token
token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

温馨提示

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
}

演示模式限制

如果 .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>

批量删除

删除接口支持批量删除，多个 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
}

HTTP 状态码

无论业务成功或失败，HTTP 状态码始终为 200。业务状态通过 code 字段区分：0 表示成功，1 表示失败。

使用 Postman 调试 ​

除了 curl 命令行，也可以使用 Postman 等 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（响应数据）。

温馨提示

前端所有 API 请求都通过 Vite 代理转发到后端。在 Network 中看到的请求地址是 http://localhost:8001/api/...，实际会被代理到 http://127.0.0.1:8000/...。

权限说明 ​

项目采用 RBAC 权限模型，每个接口对应一个权限字符串（如 sys:example:page）：

接口权限标识说明
GET /example/pagesys:example:page分页查询
GET /example/detail/<id>sys:example:detail查询详情
POST /example/addsys:example:add添加记录
PUT /example/updatesys:example:update更新记录
DELETE /example/delete/<id>sys:example:delete删除记录
PUT /example/statussys:example:status更新状态

温馨提示

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 章节。

小蚂蚁云团队 · 提供技术支持

Copyright © 2021~2026 www.djangoadmin.cn. All rights reserved.