100 lines
3.0 KiB
Markdown
100 lines
3.0 KiB
Markdown
# 2.6 第一个接口调试
|
||
|
||
:::tip 概述
|
||
本节通过三个最基础的接口（健康检查 → 登录 → 带令牌调用业务接口）带你完成第一次接口调试。项目内置 OpenAPI 文档（/api.json）与本地 Redoc 页面（/swagger），可在线查看全部接口并调试。
|
||
:::
|
||
|
||
## 接口调试三步走
|
||
|
||
### 第一步：健康检查（免登录）
|
||
|
||
```sh
|
||
curl http://127.0.0.1:8000/api/health
|
||
```
|
||
|
||
```json
|
||
{"code":0,"ok":true,"msg":"操作成功","data":{"status":"up"}}
|
||
```
|
||
|
||
### 第二步：获取验证码 + 登录
|
||
|
||
```sh
|
||
# 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 惯例下划线命名**）：
|
||
|
||
```json
|
||
{
|
||
"code": 0, "ok": true, "msg": "操作成功",
|
||
"data": {
|
||
"access_token": "eyJhbGciOiJIUzI1NiIs…",
|
||
"refresh_token": "eyJhbGciOiJIUzI1NiIs…",
|
||
"expires_in": 7200,
|
||
"token_type": "Bearer"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 第三步：带令牌调用业务接口
|
||
|
||
```sh
|
||
curl http://127.0.0.1:8000/api/user/page?pageNo=1&pageSize=3 \
|
||
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs…"
|
||
```
|
||
|
||
分页响应（统一信封 + PageData）：
|
||
|
||
```json
|
||
{
|
||
"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 错误码对照表](../api-spec/error-code) |
|
||
| `ok` | 布尔，与 code==0 等价 |
|
||
| `msg` | 提示信息，失败时前端弹出 |
|
||
| `data` | 业务数据，失败时为空对象 `{}` |
|
||
|
||
## 认证方式速记
|
||
|
||
```text
|
||
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 拉黑）
|
||
```
|
||
|
||
::: tip 调试技巧
|
||
+ 开发环境把 `captcha.bypassCode`（默认 618618）作为 code 值可跳过验证码校验。
|
||
+ 令牌接口返回字段是 `access_token`（下划线），业务接口出入参是驼峰，这是唯一的命名例外。
|
||
+ 每次登录签发新令牌对，旧 access 仍有效直到过期或被拉黑；强退会双令牌一并拉黑。
|
||
:::
|