# 2.6 第一个接口调试

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

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

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

返回统一信封：

```json
{
  "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

```bash
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 使用说明](/zh/api-spec/token.html)。

## 第三步：访问受保护接口

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

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

## 响应信封约定

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

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

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

完整约定见 [8.1 统一响应格式](/zh/api-spec/response.html)。

## 用 Swagger 核对

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

## 下一步

→ [2.7 Docker 快速体验](/zh/quickstart/docker.html)