80 lines
2.6 KiB
Markdown
80 lines
2.6 KiB
Markdown
# 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)
|