easygoadmin/easygoadmin-wiki
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

签入版本

Browse Source
This commit is contained in:
小蚂蚁云
2026-10-25 17:24:27 +08:00
parent 48911cc08f
commit fdbeae092a
1010 changed files with 30682 additions and 95274 deletions
Download Patch File Download Diff File Expand all files Collapse all files
EasyGoAdmin_Gin_NaiveVue/zh/quickstart/first-api.md
+38 -167
View File
@@ -1,208 +1,79 @@
# 2.6 第一个接口调试
:::tip 概述
本章通过实际操作，带您完成第一个 API 接口的调试，从登录获取 Token 到调用业务接口。
本页用「获取验证码 → 登录 → 携带 Token 请求受保护接口」走一遍完整调用链，帮助你验证环境全通、理解统一响应格式。
:::
## 调试工具
推荐使用以下工具进行 API 调试：
- **ApiFox**：图形化 API 调试工具（https://apifox.com/）
- **curl**：命令行工具（系统自带）
- **浏览器开发者工具**：F12 → Network 面板
## 步骤一：获取验证码
## 第一步：获取图形验证码（公开接口）
```bash
# GET 请求获取验证码（返回 Base64 编码的图片 + 验证码 key）
curl http://localhost:8000/api/captcha
curl http://127.0.0.1:8000/api/captcha
```
响应示例：
返回统一信封：
```json
{
"code": 0,
"ok": true,
"msg": "操作成功",
"data": {
"key": "a1b2c3d4e5f6...",
"image": "data:image/png;base64,iVBOR..."
}
"data": { "key": "...", "captcha": "data:image/png;base64,..." }
}
```
将 `key` 保存备用，`image` 是 Base64 编码的验证码图片。
`data.key` 为验证码标识，`data.captcha` 为图片 dataURL（默认 TTF 渲染 PNG，字体缺失时降级 SVG）。`/api/captcha` 在路由声明中标记 `Public: true`，免登录即可访问。项目公开接口仅两处来源：RouteSpec 的 Public 标记，以及基础设施白名单（`/api/health`、`/swagger`、`/api.json`、`/metrics`）。
## 步骤二：登录获取 Token
## 第二步：登录换取 Token
```bash
# -----------------------------------------------------------------------------
# 登录接口（POST + JSON）
# -----------------------------------------------------------------------------
# -X POST → 使用 POST 方法
# -H "Content-Type: ..." → 告诉服务器请求体是 JSON 格式
# -d '{...}' → 发送 JSON 请求体
# username → 用户名
# password → 密码
# captchaKey → 步骤一返回的验证码 key
# captchaCode → 验证码图片上显示的字符
curl -X POST http://localhost:8000/api/login \
curl -X POST http://127.0.0.1:8000/api/login \
-H "Content-Type: application/json" \
-d '{
"username": "admin",
"password": "123456",
"captchaKey": "a1b2c3d4e5f6...",
"captchaCode": "1234"
}'
-d '{"username":"admin","password":"******","key":"<上一步key>","code":"<验证码>"}'
```
响应示例：
请求字段（`internal/model/dto/auth.go` LoginReq）：`username`、`password` 必填；`code` + `key` 为图形验证码（key 即 captcha 接口返回的 uuid 字段值，登录必须一并提交）；`tenantCode` 留空按用户名全局定位。
```json
{
"code": 0,
"ok": true,
"msg": "登录成功",
"data": {
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
"refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
"token_type": "Bearer",
"expires_in": 7200,
"user": {
"id": 1,
"username": "admin",
"realname": "管理员",
"avatar": ""
}
}
}
```
登录成功后 `data` 为 OAuth2 风格令牌对（LoginRes）：
将 `access_token` 保存备用。
| 字段 | 说明 |
|---|---|
| access_token | 访问令牌（默认 2 小时），后续请求携带 |
| refresh_token | 刷新令牌（默认 7 天），过期后经 `/api/oauth2/token` 兑换新令牌 |
| expires_in | access 有效期（秒） |
| token_type | 令牌类型，固定 Bearer |
## 步骤三：调用业务接口
令牌机制详见 [8.7 Token 使用说明](/zh/api-spec/token.html)。
使用 Token 调用需要认证的接口：
## 第三步：访问受保护接口
```bash
# -----------------------------------------------------------------------------
# 获取用户分页列表（GET + Authorization 头）
# -----------------------------------------------------------------------------
# pageNo=1\&pageSize=10 → 分页参数（\& 是 bash 转义，防止 & 被解释为后台运行符）
# -H "Authorization: Bearer <token>" → 在请求头中携带 JWT Token
curl http://localhost:8000/api/user/page?pageNo=1\&pageSize=10 \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
curl http://127.0.0.1:8000/api/index/getUser \
-H "Authorization: Bearer <access_token>"
```
响应示例：
带合法 Token 返回当前用户信息；不带或过期返回 401 信封。
## 响应信封约定
所有接口（含错误）都遵循统一结构：
```json
{
"code": 0,
"ok": true,
"msg": "操作成功",
"data": {
"records": [
{
"id": 1,
"username": "admin",
"realname": "管理员",
"status": 1,
"statusText": "启用",
"createTime": "2026-01-01 00:00:00"
}
],
"total": 1,
"size": 10,
"current": 1,
"pages": 1
}
}
{ "code": 0, "ok": true, "msg": "操作成功", "data": {} }
```
## 步骤四：测试其他接口
| 字段 | 说明 |
|---|---|
| code | 0 成功；非 0 为业务/系统错误码 |
| ok | 是否成功（布尔捷径） |
| msg | 提示信息 |
| data | 业务数据（无数据时为 null） |
```bash
# -----------------------------------------------------------------------------
# 获取当前登录用户信息
# -----------------------------------------------------------------------------
curl http://localhost:8000/api/index/getUser \
-H "Authorization: Bearer <your_token>"
完整约定见 [8.1 统一响应格式](/zh/api-spec/response.html)。
# -----------------------------------------------------------------------------
# 获取当前用户的菜单列表（用于前端动态路由）
# -----------------------------------------------------------------------------
curl http://localhost:8000/api/index/getMenus \
-H "Authorization: Bearer <your_token>"
## 用 Swagger 核对
# -----------------------------------------------------------------------------
# 获取字典项（gender = 性别字典的编码）
# -----------------------------------------------------------------------------
curl http://localhost:8000/api/dict/item/getDictItemList/gender \
-H "Authorization: Bearer <your_token>"
`api.docs=true` 时可访问 `http://127.0.0.1:8000/swagger` 查看全部端点——它与路由元数据同源生成，包含每个接口的权限码与公开标记。
# -----------------------------------------------------------------------------
# 刷新 Token（access_token 过期后，用 refresh_token 换取新的）
# -----------------------------------------------------------------------------
curl -X POST http://localhost:8000/api/oauth2/token \
-H "Content-Type: application/json" \
-d '{"grant_type": "refresh_token", "refresh_token": "<your_refresh_token>"}'
```
## 下一步
## 错误响应示例
### 401 未授权（Token 缺失或无效）
```json
{
"code": 401,
"ok": false,
"msg": "未提供认证令牌",
"data": null
}
```
### 403 禁止访问（权限不足）
```json
{
"code": 403,
"ok": false,
"msg": "无访问权限：用户列表",
"data": null
}
```
### 422 参数验证失败
```json
{
"code": 1,
"ok": false,
"msg": "参数验证失败",
"data": {
"username": "用户名不能为空"
}
}
```
## ApiFox 配置建议
1. 创建环境，设置变量：
- `base_url` = `http://localhost:8000`
- `token` = 登录后填入 access_token
2. 在请求头中使用变量：
- `Authorization` = `Bearer {{token}}`
3. 登录请求的「后置操作」中添加脚本自动保存 Token：
```javascript
// 解析响应 JSON
var response = pm.response.json();
// 登录成功时自动将 access_token 保存到环境变量
if (response.code === 0) {
pm.environment.set("token", response.data.access_token);
}
```
→ [2.7 Docker 快速体验](/zh/quickstart/docker.html)