第一个接口调试

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

温馨提示

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

1. 后端服务已启动（参见 后端启动）
2. 数据库已初始化（参见 数据库初始化）
3. Redis 服务已启动

接口调试工具

本项目后端基于 Tornado 框架，不提供内置的 Swagger 文档。推荐使用以下工具进行接口调试：

工具	说明
curl	命令行 HTTP 客户端，适合快速测试
Postman	图形化 API 调试工具，支持集合管理和环境变量
浏览器开发者工具	适合调试 GET 请求

第一步：获取验证码

登录前需要先获取图形验证码：

curl http://127.0.0.1:8041/api/v1/captcha

• 响应示例

{
    "code": 0,
    "data": {
        "captcha": "data:image/png;base64,iVBORw0KG...",
        "key": "sl1dhi-ejqV2PWH8tYDE1pVNaRiccsrQ"
    },
    "msg": "操作成功",
    "ok": true
}

温馨提示

响应中的 key 是验证码的唯一标识，后续登录时需要使用。captcha 是 Base64 编码的验证码图片，可以在浏览器中直接查看。

• 记录关键信息

key: sl1dhi-ejqV2PWH8tYDE1pVNaRiccsrQ
验证码图片中的文字: （查看图片获取）

第二步：登录获取 Token

使用验证码和账号信息进行登录，获取 JWT 访问令牌：

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"
    }'

• 成功响应

{
    "code": 0,
    "data": {
        "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    },
    "msg": "登录成功",
    "ok": true
}

• 失败响应示例

{
    "code": 1,
    "data": null,
    "msg": "验证码错误或已过期",
    "ok": false
}

常见登录失败原因

错误信息	原因	解决方式
验证码错误或已过期	验证码输入错误或超过 5 分钟有效期	重新获取验证码
账号或密码错误	用户名或密码不正确	使用默认账号 admin/123456
账号已被锁定	连续登录失败超过 5 次	等待 5 分钟后重试
登录失败次数过多	同一 IP+用户名连续失败	等待锁定时间后重试

• 记录 Token

token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

温馨提示

Token 是后续所有认证接口的通行证，请妥善保存。默认有效期为 20 分钟（可通过 .env 中的 JWT_EXPIRE_MINUTES 修改）。

第三步：使用 Token 调用业务接口

Token 获取后，在后续请求的 Authorization 头中携带即可调用需要认证的接口：

# 获取用户列表
curl -X GET "http://127.0.0.1:8041/api/v1/user/page?page=1&limit=10" \
    -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

• 成功响应

{
    "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分钟有效)

更多接口示例

# 获取验证码
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 格式：

// 成功响应
{
    "code": 0,
    "data": {},
    "msg": "操作成功",
    "ok": true
}

// 失败响应
{
    "code": 1,
    "data": null,
    "msg": "错误信息",
    "ok": false
}

// 分页响应
{
    "code": 0,
    "data": {
        "list": [],
        "total": 100
    },
    "msg": "操作成功",
    "ok": true
}

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