2.6 第一个接口调试

:::tip 概述本页用「获取验证码 → 登录 → 携带 Token 请求受保护接口」走一遍完整调用链，帮助你验证环境全通、理解统一响应格式。 :::

第一步：获取图形验证码（公开接口）

curl http://127.0.0.1:8000/api/captcha

返回统一信封：

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

data.key 为验证码标识，data.captcha 为图片 dataURL（默认 TTF 渲染 PNG，字体缺失时降级 SVG）。/api/captcha 在路由声明中标记 Public: true，免登录即可访问。项目公开接口仅两处来源：RouteSpec 的 Public 标记，以及基础设施白名单（/api/health、/swagger、/api.json、/metrics）。

第二步：登录换取 Token

curl -X POST http://127.0.0.1:8000/api/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"******","key":"<上一步key>","code":"<验证码>"}'

请求字段（internal/model/dto/auth.go LoginReq）：username、password 必填；code + key 为图形验证码（key 即 captcha 接口返回的 uuid 字段值，登录必须一并提交）；tenantCode 留空按用户名全局定位。

登录成功后 data 为 OAuth2 风格令牌对（LoginRes）：

字段	说明
access_token	访问令牌（默认 2 小时），后续请求携带
refresh_token	刷新令牌（默认 7 天），过期后经 `/api/oauth2/token` 兑换新令牌
expires_in	access 有效期（秒）
token_type	令牌类型，固定 Bearer

令牌机制详见 8.7 Token 使用说明。

第三步：访问受保护接口

curl http://127.0.0.1:8000/api/index/getUser \
  -H "Authorization: Bearer <access_token>"

带合法 Token 返回当前用户信息；不带或过期返回 401 信封。

响应信封约定

所有接口（含错误）都遵循统一结构：

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

字段	说明
code	0 成功；非 0 为业务/系统错误码
ok	是否成功（布尔捷径）
msg	提示信息
data	业务数据（无数据时为 null）

完整约定见 8.1 统一响应格式。

用 Swagger 核对

api.docs=true 时可访问 http://127.0.0.1:8000/swagger 查看全部端点——它与路由元数据同源生成，包含每个接口的权限码与公开标记。

下一步

→ 2.7 Docker 快速体验

2.6 KiB Raw Blame History Unescape Escape