5a65716d10
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
292 lines
6.5 KiB
Markdown
292 lines
6.5 KiB
Markdown
# 认证模块 API (Auth)
|
||
|
||
> 通用规范（认证方式、响应格式、错误码）见 [README.md](../README.md)
|
||
|
||
---
|
||
|
||
## 接口列表
|
||
|
||
| 方法 | 路径 | 权限 | 说明 |
|
||
|------|------|------|------|
|
||
| POST | /api/v1/auth/register | 公开 | 用户注册 |
|
||
| POST | /api/v1/auth/login | 公开 | 用户登录 |
|
||
| POST | /api/v1/auth/logout | 需认证 | 退出登录 |
|
||
| POST | /api/v1/auth/refresh-token | 公开 | 刷新 Token |
|
||
| GET | /api/v1/auth/profile | 需认证 | 获取个人信息 |
|
||
| PUT | /api/v1/auth/profile | 需认证 | 更新个人信息 |
|
||
| PUT | /api/v1/auth/password | 需认证 | 修改密码 |
|
||
|
||
---
|
||
|
||
## 1. 用户注册
|
||
|
||
`POST /api/v1/auth/register`
|
||
|
||
**权限：** 公开
|
||
|
||
**请求参数：**
|
||
|
||
| 字段 | 类型 | 必填 | 规则 | 说明 |
|
||
|------|------|------|------|------|
|
||
| username | string | 是 | 3-50 字符 | 用户名，全局唯一 |
|
||
| email | string | 是 | 合法邮箱格式 | 邮箱地址，全局唯一 |
|
||
| password | string | 是 | 6-50 字符 | 登录密码 |
|
||
| nickname | string | 否 | 最多 50 字符 | 昵称，默认与用户名相同 |
|
||
|
||
**请求示例：**
|
||
```json
|
||
{
|
||
"username": "zhangsan",
|
||
"email": "zhangsan@example.com",
|
||
"password": "123456",
|
||
"nickname": "张三"
|
||
}
|
||
```
|
||
|
||
**成功响应（201 Created）：**
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "created",
|
||
"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": "6478824e-2926-4d35-aa5f-047c8cfbb36b",
|
||
"time": "2026-02-28 16:42:03"
|
||
}
|
||
```
|
||
|
||
> `expires_in` 为 Access Token 有效期（秒），当前配置为 7200 秒（2 小时）。Refresh Token 有效期为 7 天。
|
||
|
||
**可能的错误：**
|
||
|
||
| HTTP 状态码 | 说明 |
|
||
|------------|------|
|
||
| 400 | 参数校验失败 / 用户名或邮箱已被注册 |
|
||
|
||
---
|
||
|
||
## 2. 用户登录
|
||
|
||
`POST /api/v1/auth/login`
|
||
|
||
**权限：** 公开
|
||
|
||
**请求参数：**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| account | string | 是 | 用户名或邮箱（自动识别） |
|
||
| password | string | 是 | 登录密码 |
|
||
|
||
**请求示例：**
|
||
```json
|
||
{
|
||
"account": "zhangsan",
|
||
"password": "123456"
|
||
}
|
||
```
|
||
|
||
**成功响应（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"
|
||
}
|
||
```
|
||
|
||
**可能的错误：**
|
||
|
||
| HTTP 状态码 | 说明 |
|
||
|------------|------|
|
||
| 400 | 参数校验失败 |
|
||
| 401 | 账号或密码错误 |
|
||
| 403 | 账号已被禁用 / 账号已注销 |
|
||
| 404 | 用户不存在 |
|
||
|
||
---
|
||
|
||
## 3. 退出登录
|
||
|
||
`POST /api/v1/auth/logout`
|
||
|
||
**权限：** 需认证
|
||
|
||
**说明：** 当前采用无状态 JWT 方案，服务端不存储 Token 状态。退出登录由客户端主动删除本地存储的 Token 即可。后续可扩展为将 Token 加入 Redis 黑名单实现服务端主动失效。
|
||
|
||
**成功响应：**
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": null,
|
||
"trace_id": "...",
|
||
"time": "2026-02-28 16:42:05"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 刷新 Token
|
||
|
||
`POST /api/v1/auth/refresh-token`
|
||
|
||
**权限：** 公开（携带 refresh_token）
|
||
|
||
**请求参数：**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| refresh_token | string | 是 | 刷新令牌 |
|
||
|
||
**请求示例：**
|
||
```json
|
||
{
|
||
"refresh_token": "eyJhbGciOiJIUzI1NiIs..."
|
||
}
|
||
```
|
||
|
||
**成功响应：**
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": {
|
||
"token": "eyJhbG...(新 Access Token)",
|
||
"refresh_token": "eyJhbG...(新 Refresh Token)",
|
||
"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"
|
||
}
|
||
```
|
||
|
||
**可能的错误：**
|
||
|
||
| HTTP 状态码 | 说明 |
|
||
|------------|------|
|
||
| 400 | 参数校验失败 / 无效的 Refresh Token 类型 |
|
||
| 401 | Token 已过期或无效 |
|
||
| 403 | 账号已被禁用 / 账号已注销 |
|
||
| 404 | 用户不存在 |
|
||
|
||
---
|
||
|
||
## 5. 获取个人信息
|
||
|
||
`GET /api/v1/auth/profile`
|
||
|
||
**权限：** 需认证
|
||
|
||
**成功响应：**
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": {
|
||
"id": 1,
|
||
"username": "zhangsan",
|
||
"email": "zhangsan@example.com",
|
||
"nickname": "张三",
|
||
"avatar": "https://cdn.echochat.com/avatar/1.jpg",
|
||
"gender": 1,
|
||
"phone": "13800138000",
|
||
"roles": ["user"],
|
||
"created_at": "2026-02-27 10:00:00"
|
||
},
|
||
"trace_id": "...",
|
||
"time": "2026-02-28 16:42:07"
|
||
}
|
||
```
|
||
|
||
> profile 接口返回的 `UserInfo` 包含 `phone` 和 `created_at` 字段（相比登录响应中的用户信息更完整）。
|
||
|
||
---
|
||
|
||
## 6. 更新个人信息
|
||
|
||
`PUT /api/v1/auth/profile`
|
||
|
||
**权限：** 需认证
|
||
|
||
**请求参数（均为可选，只传需要修改的字段）：**
|
||
|
||
| 字段 | 类型 | 必填 | 规则 | 说明 |
|
||
|------|------|------|------|------|
|
||
| nickname | string | 否 | 最多 50 字符 | 新昵称 |
|
||
| avatar | string | 否 | 最多 500 字符 | 新头像 URL |
|
||
| gender | int | 否 | 0/1/2 | 性别：0=未知，1=男，2=女 |
|
||
| phone | string | 否 | 最多 20 字符 | 手机号 |
|
||
|
||
**成功响应：** 返回更新后的完整用户信息（与获取个人信息接口格式一致）。
|
||
|
||
---
|
||
|
||
## 7. 修改密码
|
||
|
||
`PUT /api/v1/auth/password`
|
||
|
||
**权限：** 需认证
|
||
|
||
**请求参数：**
|
||
|
||
| 字段 | 类型 | 必填 | 规则 | 说明 |
|
||
|------|------|------|------|------|
|
||
| old_password | string | 是 | - | 原密码 |
|
||
| new_password | string | 是 | 6-50 字符 | 新密码 |
|
||
|
||
**成功响应：**
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": null,
|
||
"trace_id": "...",
|
||
"time": "2026-02-28 16:42:08"
|
||
}
|
||
```
|
||
|
||
**可能的错误：**
|
||
|
||
| HTTP 状态码 | 说明 |
|
||
|------------|------|
|
||
| 400 | 参数校验失败 |
|
||
| 401 | 原密码错误 |
|
||
| 404 | 用户不存在 |
|