wanglei/EchoChat
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(api): 同步 API 文档与实际实现一致

Browse Source 
README.md:
- 开发环境端口 8080 → 8085
- 统一响应格式添加 trace_id 字段
- 成功消息 "ok" → "success"，创建 "created"

frontend/auth.md（全面更新）:
- 注册响应：201 状态码 + message="created" + expires_in=7200
- 所有响应示例：添加 trace_id 和 time 字段
- user 对象：添加 gender 字段
- 退出登录：更新为无状态 JWT 说明（非 Redis）
- 刷新 Token：添加 user 字段到响应
- profile：添加 phone + created_at 字段
- 错误码：统一使用 HTTP 状态码说明表

代码同步:
- dto.UserInfo: 添加 Phone + CreatedAt 字段
- auth_service.buildUserInfo: 填充新字段

Made-with: Cursor
This commit is contained in:
bujinyuan
2026-02-28 16:48:17 +08:00
parent d975adaf2a
commit 5a65716d10
4 changed files with 157 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
backend/go-service/app/auth/service/auth_service.go
View File

@@ -378,13 +378,18 @@ func (s *AuthService) buildUserInfo(user *model.User, roles []string) *dto.UserI
if roles == nil { if roles == nil {
roles = []string{} roles = []string{}
} }
return &dto.UserInfo{ info := &dto.UserInfo{
ID: user.ID, ID: user.ID,
Username: user.Username, Username: user.Username,
Email: user.Email, Email: user.Email,
Nickname: user.Nickname, Nickname: user.Nickname,
Avatar: user.Avatar, Avatar: user.Avatar,
Gender: user.Gender, Gender: user.Gender,
Roles: roles, Roles: roles,
CreatedAt: user.CreatedAt.Format("2006-01-02 15:04:05"),
} }
if user.Phone != nil {
info.Phone = *user.Phone
}
return info
} }

16
backend/go-service/app/dto/auth_dto.go
View File

@@ -25,13 +25,15 @@ type LoginResponse struct {
// UserInfo 用户基本信息（用于响应返回，不含敏感字段） // UserInfo 用户基本信息（用于响应返回，不含敏感字段）
type UserInfo struct { type UserInfo struct {
ID int64 `json:"id"` // 用户 ID ID int64 `json:"id"` // 用户 ID
Username string `json:"username"` // 用户名 Username string `json:"username"` // 用户名
Email string `json:"email"` // 邮箱 Email string `json:"email"` // 邮箱
Nickname string `json:"nickname"` // 昵称 Nickname string `json:"nickname"` // 昵称
Avatar string `json:"avatar"` // 头像 URL Avatar string `json:"avatar"` // 头像 URL
Gender int `json:"gender"` // 性别：0=未知, 1=男, 2=女 Gender int `json:"gender"` // 性别：0=未知, 1=男, 2=女
Roles []string `json:"roles"` // 角色代码列表 Phone string `json:"phone,omitempty"` // 手机号（可能为空）
Roles []string `json:"roles"` // 角色代码列表
CreatedAt string `json:"created_at,omitempty"` // 注册时间（格式：yyyy-MM-dd HH:mm:ss）
} }
// RefreshTokenRequest 刷新 Token 请求参数 // RefreshTokenRequest 刷新 Token 请求参数

20
docs/api/README.md
View File

@@ -41,7 +41,7 @@
| 环境 | 地址 | | 环境 | 地址 |
|------|------| |------|------|
| 开发环境 | `http://localhost:8080` | | 开发环境 | `http://localhost:8085` |
| 生产环境 | `https://api.echochat.com`（待定） | | 生产环境 | `https://api.echochat.com`（待定） |
### 认证方式 ### 认证方式
@@ -73,8 +73,20 @@ yyyy-MM-dd HH:mm:ss
```json ```json
{ {
"code": 0, "code": 0,
"message": "ok", "message": "success",
"data": { ... }, "data": { ... },
"trace_id": "6478824e-2926-4d35-aa5f-047c8cfbb36b",
"time": "2026-02-27 18:00:00"
}
```
**创建成功响应（如注册）：**
```json
{
"code": 0,
"message": "created",
"data": { ... },
"trace_id": "6478824e-2926-4d35-aa5f-047c8cfbb36b",
"time": "2026-02-27 18:00:00" "time": "2026-02-27 18:00:00"
} }
``` ```
@@ -84,11 +96,13 @@ yyyy-MM-dd HH:mm:ss
{ {
"code": 1001, "code": 1001,
"message": "参数错误：邮箱格式不正确", "message": "参数错误：邮箱格式不正确",
"data": null, "trace_id": "66564073-c0b7-4cf6-a200-5df94e1d01f3",
"time": "2026-02-27 18:00:00" "time": "2026-02-27 18:00:00"
} }
``` ```
> **trace_id** 字段在所有响应中都返回，用于追踪同一请求在各层级日志中的关联。
### 错误码定义 ### 错误码定义
#### 通用错误码（1000-1099） #### 通用错误码（1000-1099）

148
docs/api/frontend/auth.md
View File

@@ -28,8 +28,8 @@
| 字段 | 类型 | 必填 | 规则 | 说明 | | 字段 | 类型 | 必填 | 规则 | 说明 |
|------|------|------|------|------| |------|------|------|------|------|
| username | string | 是 | 3-50 字符，字母数字下划线 | 用户名 | | username | string | 是 | 3-50 字符 | 用户名，全局唯一 |
| email | string | 是 | 合法邮箱格式 | 邮箱地址 | | email | string | 是 | 合法邮箱格式 | 邮箱地址，全局唯一 |
| password | string | 是 | 6-50 字符 | 登录密码 | | password | string | 是 | 6-50 字符 | 登录密码 |
| nickname | string | 否 | 最多 50 字符 | 昵称，默认与用户名相同 | | nickname | string | 否 | 最多 50 字符 | 昵称，默认与用户名相同 |
@@ -43,28 +43,37 @@
} }
``` ```
**成功响应：** **成功响应（201 Created）：**
```json ```json
{ {
"code": 0, "code": 0,
"message": "ok", "message": "created",
"data": { "data": {
"token": "eyJhbGciOiJIUzI1NiIs...", "token": "eyJhbGciOiJIUzI1NiIs...",
"refresh_token": "eyJhbGciOiJIUzI1NiIs...", "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
"expires_in": 604800, "expires_in": 7200,
"user": { "user": {
"id": 1, "id": 1,
"username": "zhangsan", "username": "zhangsan",
"email": "zhangsan@example.com", "email": "zhangsan@example.com",
"nickname": "张三", "nickname": "张三",
"avatar": "", "avatar": "",
"gender": 0,
"roles": ["user"] "roles": ["user"]
} }
} },
"trace_id": "6478824e-2926-4d35-aa5f-047c8cfbb36b",
"time": "2026-02-28 16:42:03"
} }
``` ```
**可能的错误码：** 1001, 2001, 2002 > `expires_in` 为 Access Token 有效期（秒），当前配置为 7200 秒（2 小时）。Refresh Token 有效期为 7 天。
**可能的错误：**
| HTTP 状态码 | 说明 |
|------------|------|
| 400 | 参数校验失败 / 用户名或邮箱已被注册 |
--- ---
@@ -78,7 +87,7 @@
| 字段 | 类型 | 必填 | 说明 | | 字段 | 类型 | 必填 | 说明 |
|------|------|------|------| |------|------|------|------|
| account | string | 是 | 用户名或邮箱（自动识别格式） | | account | string | 是 | 用户名或邮箱（自动识别） |
| password | string | 是 | 登录密码 | | password | string | 是 | 登录密码 |
**请求示例：** **请求示例：**
@@ -89,9 +98,38 @@
} }
``` ```
**成功响应：** 与注册接口返回格式一致 **成功响应（200 OK）：**
```json
{
"code": 0,
"message": "success",
"data": {
"token": "eyJhbGciOiJIUzI1NiIs...",
"refresh_token": "eyJhbGciOiJIUzI1NiIs...",
"expires_in": 7200,
"user": {
"id": 1,
"username": "zhangsan",
"email": "zhangsan@example.com",
"nickname": "张三",
"avatar": "",
"gender": 0,
"roles": ["user"]
}
},
"trace_id": "fe290a90-00af-4c6b-8af7-ba6ae1d57d20",
"time": "2026-02-28 16:42:04"
}
```
**可能的错误码：** 1001, 2003, 2004 **可能的错误：**
| HTTP 状态码 | 说明 |
|------------|------|
| 400 | 参数校验失败 |
| 401 | 账号或密码错误 |
| 403 | 账号已被禁用 / 账号已注销 |
| 404 | 用户不存在 |
--- ---
@@ -101,14 +139,16 @@
**权限：** 需认证 **权限：** 需认证
**说明：** 服务端清除 Redis 中的 Token 记录，客户端需同步清除本地存储的 Token。 **说明：** 当前采用无状态 JWT 方案，服务端不存储 Token 状态。退出登录由客户端主动删除本地存储的 Token 即可。后续可扩展为将 Token 加入 Redis 黑名单实现服务端主动失效。
**成功响应：** **成功响应：**
```json ```json
{ {
"code": 0, "code": 0,
"message": "ok", "message": "success",
"data": null "data": null,
"trace_id": "...",
"time": "2026-02-28 16:42:05"
} }
``` ```
@@ -126,20 +166,45 @@
|------|------|------|------| |------|------|------|------|
| refresh_token | string | 是 | 刷新令牌 | | refresh_token | string | 是 | 刷新令牌 |
**请求示例：**
```json
{
"refresh_token": "eyJhbGciOiJIUzI1NiIs..."
}
```
**成功响应：** **成功响应：**
```json ```json
{ {
"code": 0, "code": 0,
"message": "ok", "message": "success",
"data": { "data": {
"token": "eyJhbG...(新 Access Token)", "token": "eyJhbG...(新 Access Token)",
"refresh_token": "eyJhbG...(新 Refresh Token)", "refresh_token": "eyJhbG...(新 Refresh Token)",
"expires_in": 604800 "expires_in": 7200,
} "user": {
"id": 1,
"username": "zhangsan",
"email": "zhangsan@example.com",
"nickname": "张三",
"avatar": "",
"gender": 0,
"roles": ["user"]
}
},
"trace_id": "...",
"time": "2026-02-28 16:42:06"
} }
``` ```
**可能的错误码：** 1002 **可能的错误：**
| HTTP 状态码 | 说明 |
|------------|------|
| 400 | 参数校验失败 / 无效的 Refresh Token 类型 |
| 401 | Token 已过期或无效 |
| 403 | 账号已被禁用 / 账号已注销 |
| 404 | 用户不存在 |
--- ---
@@ -153,7 +218,7 @@
```json ```json
{ {
"code": 0, "code": 0,
"message": "ok", "message": "success",
"data": { "data": {
"id": 1, "id": 1,
"username": "zhangsan", "username": "zhangsan",
@@ -164,10 +229,14 @@
"phone": "13800138000", "phone": "13800138000",
"roles": ["user"], "roles": ["user"],
"created_at": "2026-02-27 10:00:00" "created_at": "2026-02-27 10:00:00"
} },
"trace_id": "...",
"time": "2026-02-28 16:42:07"
} }
``` ```
> profile 接口返回的 `UserInfo` 包含 `phone` 和 `created_at` 字段（相比登录响应中的用户信息更完整）。
--- ---
## 6. 更新个人信息 ## 6. 更新个人信息
@@ -178,12 +247,14 @@
**请求参数（均为可选，只传需要修改的字段）：** **请求参数（均为可选，只传需要修改的字段）：**
| 字段 | 类型 | 必填 | 说明 | | 字段 | 类型 | 必填 | 规则 | 说明 |
|------|------|------|------| |------|------|------|------|------|
| nickname | string | 否 | 新昵称 | | nickname | string | 否 | 最多 50 字符 | 新昵称 |
| avatar | string | 否 | 新头像 URL | | avatar | string | 否 | 最多 500 字符 | 新头像 URL |
| gender | int | 否 | 性别：0=未知，1=男，2=女 | | gender | int | 否 | 0/1/2 | 性别：0=未知，1=男，2=女 |
| phone | string | 否 | 手机号 | | phone | string | 否 | 最多 20 字符 | 手机号 |
**成功响应：** 返回更新后的完整用户信息（与获取个人信息接口格式一致）。
--- ---
@@ -195,9 +266,26 @@
**请求参数：** **请求参数：**
| 字段 | 类型 | 必填 | 说明 | | 字段 | 类型 | 必填 | 规则 | 说明 |
|------|------|------|------| |------|------|------|------|------|
| old_password | string | 是 | 原密码 | | old_password | string | 是 | - | 原密码 |
| new_password | string | 是 | 新密码（6-50 字符） | | new_password | string | 是 | 6-50 字符 | 新密码 |
**可能的错误码：** 1001, 2003（原密码错误） **成功响应：**
```json
{
"code": 0,
"message": "success",
"data": null,
"trace_id": "...",
"time": "2026-02-28 16:42:08"
}
```
**可能的错误：**
| HTTP 状态码 | 说明 |
|------------|------|
| 400 | 参数校验失败 |
| 401 | 原密码错误 |
| 404 | 用户不存在 |