2.6 第一个接口调试

概述

本节通过三个最基础的接口（健康检查 → 登录 → 带令牌调用业务接口）带你完成第一次接口调试。项目内置 OpenAPI 文档（/api.json）与本地 Redoc 页面（/swagger），可在线查看全部接口并调试。

接口调试三步走

第一步：健康检查（免登录）

curl http://127.0.0.1:8000/api/health

{"code":0,"ok":true,"msg":"操作成功","data":{"status":"up"}}

第二步：获取验证码 + 登录

# 1. 获取图形验证码（公开接口）
curl http://127.0.0.1:8000/api/captcha
# 返回 {"key":"uuid...","captcha":"data:image/png;base64,..."}

# 2. 登录（公开接口；开发环境可携带万能验证码 bypassCode 免校验）
curl -X POST http://127.0.0.1:8000/api/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"123456","code":"618618","key":"上一步返回的key"}'

登录成功返回（OAuth2 惯例下划线命名）：

{
  "code": 0, "ok": true, "msg": "操作成功",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs…",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs…",
    "expires_in": 7200,
    "token_type": "Bearer"
  }
}

第三步：带令牌调用业务接口

curl http://127.0.0.1:8000/api/user/page?pageNo=1&pageSize=3 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs…"

分页响应（统一信封 + PageData）：

{
  "code": 0, "ok": true, "msg": "操作成功",
  "data": {
    "records": [ { "id": 1, "username": "admin", … } ],
    "total": 1, "size": 3, "current": 1, "pages": 1
  }
}

在线文档调试

浏览器打开：

地址	内容
http://127.0.0.1:8000/swagger	本地托管 Redoc UI（免登录）
http://127.0.0.1:8000/api.json	原生 OpenAPI JSON（gmeta 补注册生成）

gmeta 注解（method/path/summary/permission）会完整体现在文档中，接口与文档天然同步。

响应信封约定

字段	说明
code	0=成功；1=通用失败；401=未认证（HTTP 401）；403=无权限；429=限流；其余业务码见 8.2 错误码对照表
ok	布尔，与 code==0 等价
msg	提示信息，失败时前端弹出
data	业务数据，失败时为空对象 {}

认证方式速记

1. access_token 放 Header：Authorization: Bearer <token>
2. access_token 过期（401）→ POST /api/oauth2/token
     {"grant_type":"refresh_token","refresh_token":"<refresh_token>"}
   → 拿到新令牌对（旧 refresh 拉黑防重放）
3. 登出：GET /api/logout（当前 jti 拉黑）

调试技巧

• 开发环境把 captcha.bypassCode（默认 618618）作为 code 值可跳过验证码校验。
• 令牌接口返回字段是 access_token（下划线），业务接口出入参是驼峰，这是唯一的命名例外。
• 每次登录签发新令牌对，旧 access 仍有效直到过期或被拉黑；强退会双令牌一并拉黑。