EchoChat/docs/conventions/frontend-backend-integration.md

# 前后端集成开发规范

> **适用范围**：EchoChat 项目全端（Go 后端 + admin 管理端 + frontend 用户端）
> **创建日期**：2026-03-02
> **最后更新**：2026-03-02

---

## 一、API 响应格式规范

### 1.1 后端统一响应结构

所有后端 API 必须使用 `pkg/utils/response.go` 中的 `Response*` 系列函数返回响应，保证结构一致：

```json
{
  "code": 0,
  "message": "success",
  "data": {},
  "trace_id": "uuid-v4",
  "time": "2026-03-02 14:00:00"
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `code` | int | 业务状态码：0=成功，非 0=HTTP 状态码 |
| `message` | string | 人类可读的描述信息，**前端直接展示给用户** |
| `data` | any | 业务数据，失败时为 null |
| `trace_id` | string | 请求追踪 ID，用于日志排查 |
| `time` | string | 服务器响应时间 |

### 1.2 后端 Response 函数对照

| 函数 | HTTP Status | code | 使用场景 |
|------|-------------|------|----------|
| `ResponseOK` | 200 | 0 | 请求成功 |
| `ResponseCreated` | 201 | 0 | 资源创建成功 |
| `ResponseBadRequest` | 400 | 400 | 参数错误、业务规则校验失败 |
| `ResponseUnauthorized` | 401 | 401 | 认证失败（密码错误、Token 无效/过期） |
| `ResponseForbidden` | 403 | 403 | 权限不足、账号被禁用 |
| `ResponseNotFound` | 404 | 404 | 资源不存在 |
| `ResponseError` | 500 | 500 | 服务器内部错误 |

### 1.3 message 字段要求

- **必须是中文**，面向最终用户
- **必须精准描述错误原因**，不能笼统（如 "操作失败"）
- **安全场景除外**：登录时"用户不存在"和"密码错误"统一为 "账号或密码错误"

---

## 二、HTTP 状态码使用规范

### 2.1 状态码语义

| 状态码 | 语义 | 后端使用场景 |
|--------|------|-------------|
| 200 | OK | 查询成功、操作成功 |
| 201 | Created | 资源创建成功（注册、新建用户） |
| 400 | Bad Request | 参数校验失败、业务规则不满足 |
| 401 | Unauthorized | 认证失败：密码错误、Token 过期/无效/已注销 |
| 403 | Forbidden | 权限不足：角色不匹配、账号被禁用/注销 |
| 404 | Not Found | 请求的资源不存在 |
| 500 | Internal Server Error | 服务器内部错误 |

### 2.2 安全约束

**登录接口的 401 响应**：

```
✅ 正确：用户不存在 → 401 "账号或密码错误"
✅ 正确：密码错误 → 401 "账号或密码错误"
❌ 错误：用户不存在 → 404 "用户不存在"（暴露用户是否注册）
```

防止用户枚举攻击，登录场景下所有认证失败统一返回相同状态码和信息。

---

## 三、前端错误处理规范

### 3.1 核心原则

1. **后端 message 优先**：所有 HTTP 错误提示必须优先使用 `data.message`
2. **禁止硬编码覆盖**：不能用前端硬编码的文案替换后端返回的错误信息
3. **Fallback 仅兜底**：`|| '默认文案'` 仅在后端无响应体或无 message 字段时触发
4. **按状态码分类处理**：不同 HTTP 状态码执行不同的副作用（跳转、清 Token 等）

### 3.2 管理端（admin/）错误处理

文件：`admin/src/utils/request.js`

```
HTTP 响应成功（2xx）:
  ├─ code === 0 → 返回数据
  └─ code !== 0 → ElMessage.error(data.message || '请求失败')

HTTP 响应错误：
  ├─ 401
  │   ├─ 在登录页 → ElMessage.error(data.message || '登录已过期')
  │   └─ 非登录页 → ElMessage.error(data.message || '登录已过期') + 清 Token + 跳转 /login
  ├─ 403 → ElMessage.error(data.message || '没有访问权限')
  ├─ 其他 → ElMessage.error(data.message || '请求错误(N)')
  └─ 网络异常 → ElMessage.error('网络异常，请检查网络连接')
```

**401 场景区分的关键**：通过 `router.currentRoute.value.path === '/login'` 判断当前是否在登录页。登录页不清 Token 不跳转，仅显示错误。

### 3.3 前台用户端（frontend/）错误处理

文件：`frontend/src/utils/request.js`

```
HTTP 响应成功（2xx）:
  ├─ code === 0 → resolve(data)
  └─ code !== 0 → showToast(data.message || '请求失败')

HTTP 响应错误：
  ├─ 401
  │   ├─ 登录/注册请求 → showToast(data.message || '登录已过期')
  │   └─ 其他请求 → showToast(data.message || '登录已过期') + removeToken() + 跳转登录页
  ├─ 403 → showToast(data.message || '没有访问权限')
  ├─ 其他 → showToast(data.message || '请求错误(N)')
  └─ 网络异常 → showToast('网络异常，请检查网络连接')
```

**401 场景区分的关键**：通过正则 `/\/auth\/(login|register)$/` 匹配请求 URL。登录/注册请求不清 Token 不跳转。

### 3.4 错误处理检查清单

新增 API 接口时，必须确认以下各项：

- [ ] 后端 Controller 使用正确的 `Response*` 函数
- [ ] 后端 Controller 的 error switch 覆盖所有已知业务错误
- [ ] 后端不使用 `_` 忽略 error，至少 log warning
- [ ] 前端调用方的 catch 不自行覆盖 message（交给拦截器统一处理）
- [ ] 前端页面级 catch 只做状态清理（如 loading = false），不重复弹提示

---

## 四、后端错误处理规范

### 4.1 Controller 层

- 使用 switch/case 或 if/else 匹配所有已知业务错误
- 每种错误映射到正确的 HTTP 状态码
- message 参数必须是用户友好的中文描述
- default 分支处理未知错误，返回 500

```go
if err := svc.DoSomething(ctx, req); err != nil {
    switch err {
    case service.ErrNotFound:
        utils.ResponseNotFound(c, "资源不存在")
    case service.ErrInvalidParam:
        utils.ResponseBadRequest(c, "参数无效")
    default:
        logs.Error(ctx, funcName, "操作失败", zap.Error(err))
        utils.ResponseError(c, "操作失败")
    }
    return
}
```

### 4.2 Service 层

- 定义明确的业务错误变量（`var ErrXxx = errors.New("...")`）
- 不在 Service 层直接返回 HTTP 状态码，由 Controller 映射
- DAO 层的 `gorm.ErrRecordNotFound` 必须转换为业务错误

### 4.3 禁止忽略错误

```go
// ❌ 错误：忽略 error
roles, _ := s.roleDAO.GetUserRoleCodes(ctx, user.ID)

// ✅ 正确：处理 error
roles, err := s.roleDAO.GetUserRoleCodes(ctx, user.ID)
if err != nil {
    logs.Warn(ctx, funcName, "获取角色失败", zap.Error(err))
    roles = []string{}
}
```

---

## 五、前后端错误码对照表

| 后端场景 | HTTP | message 示例 | 前端行为 |
|---------|------|-------------|---------|
| 登录-密码错误 | 401 | 账号或密码错误 | 显示 message |
| 登录-用户不存在 | 401 | 账号或密码错误 | 显示 message |
| 登录-账号被禁用 | 403 | 账号已被禁用 | 显示 message |
| Token 过期 | 401 | 认证已过期或无效，请重新登录 | 显示 message + 清 Token + 跳转 |
| Token 已注销 | 401 | 认证已失效，请重新登录 | 显示 message + 清 Token + 跳转 |
| 缺少认证信息 | 401 | 缺少认证信息 | 显示 message + 清 Token + 跳转 |
| 权限不足 | 403 | 权限不足，需要角色: admin 或 super_admin | 显示 message |
| 参数校验失败 | 400 | 参数校验失败: ... | 显示 message |
| 用户名已注册 | 400 | 用户名或邮箱已被注册 | 显示 message |
| 不能禁用自己 | 400 | 不能禁用自己的账号 | 显示 message |
| 用户不存在 | 404 | 用户不存在 | 显示 message |
| 服务器内部错误 | 500 | 获取用户列表失败 | 显示 message |
| 网络异常 | - | （无响应体） | 显示前端 fallback 文案 |