383 lines
6.9 KiB
Markdown
383 lines
6.9 KiB
Markdown
# 用户认证 API 文档
|
||
|
||
## 📋 概述
|
||
|
||
本文档描述云酒馆项目前台用户认证系统的所有 API 接口。
|
||
|
||
## 🔗 基础信息
|
||
|
||
- **Base URL**: `http://localhost:8888/app`（开发环境）
|
||
- **认证方式**: JWT Bearer Token
|
||
- **Content-Type**: `application/json`
|
||
|
||
## 📌 API 接口列表
|
||
|
||
### 1. 用户注册
|
||
|
||
**接口**: `POST /app/auth/register`
|
||
|
||
**描述**: 新用户注册
|
||
|
||
**请求头**: 无需认证
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"username": "testuser",
|
||
"password": "123456",
|
||
"nickName": "测试用户",
|
||
"email": "test@example.com",
|
||
"phone": "13800138000"
|
||
}
|
||
```
|
||
|
||
**字段说明**:
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| username | string | 是 | 用户名，3-32字符 |
|
||
| password | string | 是 | 密码，6-32字符 |
|
||
| nickName | string | 否 | 昵称，最多50字符 |
|
||
| email | string | 否 | 邮箱地址 |
|
||
| phone | string | 否 | 手机号 |
|
||
|
||
**成功响应**:
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "注册成功"
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
```json
|
||
{
|
||
"code": 7,
|
||
"msg": "用户名已存在"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 2. 用户登录
|
||
|
||
**接口**: `POST /app/auth/login`
|
||
|
||
**描述**: 用户登录获取 Token
|
||
|
||
**请求头**: 无需认证
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"username": "testuser",
|
||
"password": "123456"
|
||
}
|
||
```
|
||
|
||
**成功响应**:
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": {
|
||
"user": {
|
||
"id": 1,
|
||
"uuid": "550e8400-e29b-41d4-a716-446655440000",
|
||
"username": "testuser",
|
||
"nickName": "测试用户",
|
||
"email": "test@example.com",
|
||
"phone": "13800138000",
|
||
"avatar": "",
|
||
"status": "active",
|
||
"enable": true,
|
||
"lastLoginAt": "2026-02-10T09:00:00Z",
|
||
"chatCount": 0,
|
||
"messageCount": 0,
|
||
"aiSettings": null,
|
||
"preferences": null,
|
||
"createdAt": "2026-02-10T08:00:00Z"
|
||
},
|
||
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||
"refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||
"expiresAt": 1707552000
|
||
},
|
||
"msg": "登录成功"
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
```json
|
||
{
|
||
"code": 7,
|
||
"msg": "用户名或密码错误"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 3. 刷新 Token
|
||
|
||
**接口**: `POST /app/auth/refresh`
|
||
|
||
**描述**: 使用 RefreshToken 获取新的 Token
|
||
|
||
**请求头**: 无需认证
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
|
||
}
|
||
```
|
||
|
||
**成功响应**: 同登录接口
|
||
|
||
---
|
||
|
||
### 4. 用户登出
|
||
|
||
**接口**: `POST /app/auth/logout`
|
||
|
||
**描述**: 用户登出（清除会话）
|
||
|
||
**请求头**:
|
||
```
|
||
x-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
||
```
|
||
或
|
||
```
|
||
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
||
```
|
||
|
||
**请求体**: 无
|
||
|
||
**成功响应**:
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "登出成功"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 5. 获取用户信息
|
||
|
||
**接口**: `GET /app/auth/userinfo`
|
||
|
||
**描述**: 获取当前登录用户信息
|
||
|
||
**请求头**: 需要认证（JWT Token）
|
||
|
||
**成功响应**:
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": {
|
||
"id": 1,
|
||
"uuid": "550e8400-e29b-41d4-a716-446655440000",
|
||
"username": "testuser",
|
||
"nickName": "测试用户",
|
||
"email": "test@example.com",
|
||
"phone": "13800138000",
|
||
"avatar": "",
|
||
"status": "active",
|
||
"enable": true,
|
||
"lastLoginAt": "2026-02-10T09:00:00Z",
|
||
"chatCount": 5,
|
||
"messageCount": 120,
|
||
"aiSettings": {},
|
||
"preferences": {},
|
||
"createdAt": "2026-02-10T08:00:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 6. 更新用户信息
|
||
|
||
**接口**: `PUT /app/user/profile`
|
||
|
||
**描述**: 更新当前用户的个人信息
|
||
|
||
**请求头**: 需要认证（JWT Token）
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"nickName": "新昵称",
|
||
"email": "newemail@example.com",
|
||
"phone": "13900139000",
|
||
"avatar": "https://example.com/avatar.jpg",
|
||
"preferences": "{\"theme\":\"dark\"}",
|
||
"aiSettings": "{\"defaultModel\":\"gpt-4\"}"
|
||
}
|
||
```
|
||
|
||
**字段说明**: 所有字段均为可选
|
||
|
||
**成功响应**:
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "更新成功"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 7. 修改密码
|
||
|
||
**接口**: `POST /app/user/change-password`
|
||
|
||
**描述**: 修改当前用户密码
|
||
|
||
**请求头**: 需要认证（JWT Token）
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"oldPassword": "123456",
|
||
"newPassword": "new123456"
|
||
}
|
||
```
|
||
|
||
**成功响应**:
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "修改成功"
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
```json
|
||
{
|
||
"code": 7,
|
||
"msg": "原密码错误"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🔐 认证说明
|
||
|
||
### Token 使用方式
|
||
|
||
认证接口需要在请求头中携带 Token，支持两种方式：
|
||
|
||
**方式 1**: `x-token` 头
|
||
```http
|
||
x-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
||
```
|
||
|
||
**方式 2**: `Authorization` 头（Bearer Token）
|
||
```http
|
||
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
||
```
|
||
|
||
**方式 3**: Query 参数（不推荐，仅用于特殊场景）
|
||
```http
|
||
GET /app/auth/userinfo?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
||
```
|
||
|
||
### Token 有效期
|
||
|
||
- **Access Token**: 配置文件中的 `jwt.expiresTime` 设置（默认 7200 秒 = 2 小时）
|
||
- **Refresh Token**: 固定 7 天
|
||
|
||
### Token 刷新流程
|
||
|
||
1. Access Token 过期后，使用 Refresh Token 调用 `/app/auth/refresh` 接口
|
||
2. 获取新的 Access Token 和 Refresh Token
|
||
3. 使用新的 Token 继续访问 API
|
||
|
||
---
|
||
|
||
## 🧪 测试用例
|
||
|
||
### 使用 curl 测试
|
||
|
||
**1. 注册新用户**:
|
||
```bash
|
||
curl -X POST http://localhost:8888/app/auth/register \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"username": "testuser",
|
||
"password": "123456",
|
||
"nickName": "测试用户"
|
||
}'
|
||
```
|
||
|
||
**2. 登录**:
|
||
```bash
|
||
curl -X POST http://localhost:8888/app/auth/login \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"username": "testuser",
|
||
"password": "123456"
|
||
}'
|
||
```
|
||
|
||
**3. 获取用户信息**（需替换 TOKEN）:
|
||
```bash
|
||
TOKEN="your_token_here"
|
||
curl -X GET http://localhost:8888/app/auth/userinfo \
|
||
-H "x-token: $TOKEN"
|
||
```
|
||
|
||
**4. 更新用户信息**:
|
||
```bash
|
||
curl -X PUT http://localhost:8888/app/user/profile \
|
||
-H "x-token: $TOKEN" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"nickName": "新昵称",
|
||
"avatar": "https://example.com/avatar.jpg"
|
||
}'
|
||
```
|
||
|
||
**5. 修改密码**:
|
||
```bash
|
||
curl -X POST http://localhost:8888/app/user/change-password \
|
||
-H "x-token: $TOKEN" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"oldPassword": "123456",
|
||
"newPassword": "new123456"
|
||
}'
|
||
```
|
||
|
||
---
|
||
|
||
## ❗ 常见错误码
|
||
|
||
| 错误码 | 说明 |
|
||
|-------|------|
|
||
| 0 | 成功 |
|
||
| 7 | 业务错误（如用户名已存在、密码错误等） |
|
||
| 401 | 未认证或 Token 无效 |
|
||
| 403 | 账户被禁用或状态异常 |
|
||
| 500 | 服务器内部错误 |
|
||
|
||
---
|
||
|
||
## 📝 注意事项
|
||
|
||
1. **密码安全**: 所有密码均使用 bcrypt 加密存储，不可逆
|
||
2. **用户状态**: 只有 `status=active` 且 `enable=true` 的用户才能登录
|
||
3. **用户名唯一性**: 用户名和邮箱必须唯一
|
||
4. **会话管理**: 登出后会删除对应的会话记录，但 Token 在过期前仍然有效
|
||
5. **跨域配置**: 如需前端调用，请在 `initialize/router.go` 中启用 CORS 中间件
|
||
|
||
---
|
||
|
||
## 🔄 下一步开发
|
||
|
||
- [ ] 邮箱验证
|
||
- [ ] 手机号验证
|
||
- [ ] 找回密码
|
||
- [ ] 第三方登录（OAuth）
|
||
- [ ] 多设备登录管理
|
||
- [ ] 用户在线状态
|