# 2.7 第一个接口调试

:::tip 概述
本章通过实际操作，带您完成第一个 API 接口的调试，从登录获取 Token 到调用业务接口。所有请求参数与响应字段均以本项目实际接口为准。
:::

## 调试工具

推荐使用以下工具进行 API 调试：

- **ApiFox**：图形化 API 调试工具（https://apifox.com/）
- **curl**：命令行工具（系统自带）
- **浏览器开发者工具**：F12 → Network 面板

## 步骤一：获取验证码

```bash
# GET 请求获取验证码（返回 Base64 编码的图片 + 验证码 key）
curl http://localhost:8000/api/captcha
```

响应示例：

```json
{
  "code": 0,
  "ok": true,
  "msg": "操作成功",
  "data": {
    "key": "5c62cae9-3bdb-4356-bc4a-c4c61b7c3bea",
    "captcha": "data:image/png;base64,iVBORw0KGgoAAAANSUh..."
  }
}
```

将 `key` 保存备用，`captcha` 是 Base64 编码的验证码图片（肉眼读取图片上的字符）。

:::tip
验证码存储在 Redis 中，有效期 `CAPTCHA_EXPIRE`（默认 300 秒），超过有效期需重新获取。接口同时验证了 PHP → Redis 链路，此步失败优先排查 Redis（见 [2.9 常见问题 FAQ](/zh/quickstart/faq.html)）。
:::

## 步骤二：登录获取 Token

```bash
# -----------------------------------------------------------------------------
# 登录接口（POST + JSON）
# -----------------------------------------------------------------------------
# -X POST                → 使用 POST 方法
# -H "Content-Type: ..." → 告诉服务器请求体是 JSON 格式
# -d '{...}'             → 发送 JSON 请求体
#   username → 用户名
#   password → 密码
#   key      → 步骤一返回的验证码 key（与 captcha 响应字段命名一致）
#   code     → 验证码图片上显示的字符
curl -X POST http://localhost:8000/api/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "123456",
    "key": "5c62cae9-3bdb-4356-bc4a-c4c61b7c3bea",
    "code": "1234"
  }'
```

响应示例：

```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": ""
    }
  }
}
```

将 `access_token` 保存备用。登录同时会写入登录日志（IP、归属地、浏览器信息），可在「系统管理 → 日志管理 → 登录日志」查看。

:::warning
验证码参数名为 `key` / `code`（与 `/api/captcha` 响应字段命名保持一致），**不是** `captchaKey` / `captchaCode`。验证码错误时返回 `{"code":1,"msg":"验证码错误"}`。
:::

## 步骤三：调用业务接口

使用 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..."
```

响应示例（分页字段固定为 `records / total / current / size / pages`，键名已自动转驼峰）：

```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,
    "current": 1,
    "size": 10,
    "pages": 1
  }
}
```

## 步骤四：测试其他接口

```bash
# -----------------------------------------------------------------------------
# 获取当前登录用户信息
# -----------------------------------------------------------------------------
curl http://localhost:8000/api/index/getUser \
  -H "Authorization: Bearer <your_token>"

# -----------------------------------------------------------------------------
# 获取当前用户的菜单列表（用于前端动态路由）
# -----------------------------------------------------------------------------
curl http://localhost:8000/api/index/getMenus \
  -H "Authorization: Bearer <your_token>"

# -----------------------------------------------------------------------------
# 获取字典项（gender = 性别字典的编码）
# -----------------------------------------------------------------------------
curl http://localhost:8000/api/dict/item/getDictItemList/gender \
  -H "Authorization: Bearer <your_token>"

# -----------------------------------------------------------------------------
# 刷新 Token（access_token 过期后，用 refresh_token 换取新的令牌对）
# -----------------------------------------------------------------------------
# refresh 为公开接口（无需 access_token）
curl -X POST http://localhost:8000/api/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "<your_refresh_token>"}'

# -----------------------------------------------------------------------------
# 登出（令牌即时失效，需携带 access_token）
# -----------------------------------------------------------------------------
curl -X POST http://localhost:8000/api/logout \
  -H "Authorization: Bearer <your_token>"
```

## 错误响应示例

### 401 未授权（Token 缺失或无效）

```json
{
  "code": 401,
  "ok": false,
  "msg": "未授权，请先登录",
  "data": null
}
```

HTTP 状态码为 200，前端据 body `code=401` 触发跳转登录。

### 403 禁止访问（权限不足）

```json
{
  "code": 403,
  "ok": false,
  "msg": "无访问权限",
  "data": null
}
```

### 参数验证失败（FormRequest，code=1）

```json
{
  "code": 1,
  "ok": false,
  "msg": "参数验证失败",
  "data": {
    "username": ["用户名不能为空"],
    "password": ["密码不能为空"]
  }
}
```

### 业务失败（BizException，code=1）

```json
{
  "code": 1,
  "ok": false,
  "msg": "验证码错误",
  "data": null
}
```

:::tip 统一约定
所有接口 HTTP 状态码默认 200（403 例外），以响应体 `code` 判断结果：`0` 成功，其余为失败。详见 [8.1 统一响应格式](/zh/api-spec/response.html) 与 [5.16 统一响应与异常抛出](/zh/core/exception.html)。
:::

## 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);
}
```