forked from datawhale/whale-town-end
docs：创建完整的API接口文档
- 创建详细的API接口说明文档 - 提供OpenAPI 3.0规范文件 - 创建Postman测试集合 - 添加API文档使用指南
This commit is contained in:
moyin
412
docs/api/api-documentation.md
Normal file
412
docs/api/api-documentation.md
Normal file
@@ -0,0 +1,412 @@
|
||||
# 用户认证API接口文档
|
||||
|
||||
## 概述
|
||||
|
||||
本文档描述了像素游戏服务器的用户认证相关API接口，包括登录、注册、密码找回等功能。
|
||||
|
||||
**基础URL**: `http://localhost:3000`
|
||||
**API文档地址**: `http://localhost:3000/api-docs`
|
||||
|
||||
## 通用响应格式
|
||||
|
||||
所有API接口都遵循统一的响应格式：
|
||||
|
||||
```json
|
||||
{
|
||||
"success": boolean,
|
||||
"data": object | null,
|
||||
"message": string,
|
||||
"error_code": string | null
|
||||
}
|
||||
```
|
||||
|
||||
### 字段说明
|
||||
|
||||
- `success`: 请求是否成功
|
||||
- `data`: 响应数据（成功时返回）
|
||||
- `message`: 响应消息
|
||||
- `error_code`: 错误代码（失败时返回）
|
||||
|
||||
## 接口列表
|
||||
|
||||
### 1. 用户登录
|
||||
|
||||
**接口地址**: `POST /auth/login`
|
||||
|
||||
**功能描述**: 用户登录，支持用户名、邮箱或手机号登录
|
||||
|
||||
#### 请求参数
|
||||
|
||||
```json
|
||||
{
|
||||
"identifier": "testuser",
|
||||
"password": "password123"
|
||||
}
|
||||
```
|
||||
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| identifier | string | 是 | 登录标识符，支持用户名、邮箱或手机号 |
|
||||
| password | string | 是 | 用户密码 |
|
||||
|
||||
#### 响应示例
|
||||
|
||||
**成功响应** (200):
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"user": {
|
||||
"id": "1",
|
||||
"username": "testuser",
|
||||
"nickname": "测试用户",
|
||||
"email": "test@example.com",
|
||||
"phone": "+8613800138000",
|
||||
"avatar_url": "https://example.com/avatar.jpg",
|
||||
"role": 1,
|
||||
"created_at": "2025-12-17T10:00:00.000Z"
|
||||
},
|
||||
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||||
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||||
"is_new_user": false,
|
||||
"message": "登录成功"
|
||||
},
|
||||
"message": "登录成功"
|
||||
}
|
||||
```
|
||||
|
||||
**失败响应** (401):
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"message": "用户名或密码错误",
|
||||
"error_code": "LOGIN_FAILED"
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 用户注册
|
||||
|
||||
**接口地址**: `POST /auth/register`
|
||||
|
||||
**功能描述**: 创建新用户账户
|
||||
|
||||
#### 请求参数
|
||||
|
||||
```json
|
||||
{
|
||||
"username": "testuser",
|
||||
"password": "password123",
|
||||
"nickname": "测试用户",
|
||||
"email": "test@example.com",
|
||||
"phone": "+8613800138000"
|
||||
}
|
||||
```
|
||||
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| username | string | 是 | 用户名，只能包含字母、数字和下划线，长度1-50字符 |
|
||||
| password | string | 是 | 密码，必须包含字母和数字，长度8-128字符 |
|
||||
| nickname | string | 是 | 用户昵称，长度1-50字符 |
|
||||
| email | string | 否 | 邮箱地址 |
|
||||
| phone | string | 否 | 手机号码 |
|
||||
|
||||
#### 响应示例
|
||||
|
||||
**成功响应** (201):
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"user": {
|
||||
"id": "2",
|
||||
"username": "testuser",
|
||||
"nickname": "测试用户",
|
||||
"email": "test@example.com",
|
||||
"phone": "+8613800138000",
|
||||
"avatar_url": null,
|
||||
"role": 1,
|
||||
"created_at": "2025-12-17T10:00:00.000Z"
|
||||
},
|
||||
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||||
"is_new_user": true,
|
||||
"message": "注册成功"
|
||||
},
|
||||
"message": "注册成功"
|
||||
}
|
||||
```
|
||||
|
||||
**失败响应** (409):
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"message": "用户名已存在",
|
||||
"error_code": "REGISTER_FAILED"
|
||||
}
|
||||
```
|
||||
|
||||
### 3. GitHub OAuth登录
|
||||
|
||||
**接口地址**: `POST /auth/github`
|
||||
|
||||
**功能描述**: 使用GitHub账户登录或注册
|
||||
|
||||
#### 请求参数
|
||||
|
||||
```json
|
||||
{
|
||||
"github_id": "12345678",
|
||||
"username": "octocat",
|
||||
"nickname": "The Octocat",
|
||||
"email": "octocat@github.com",
|
||||
"avatar_url": "https://github.com/images/error/octocat_happy.gif"
|
||||
}
|
||||
```
|
||||
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| github_id | string | 是 | GitHub用户ID |
|
||||
| username | string | 是 | GitHub用户名 |
|
||||
| nickname | string | 是 | GitHub显示名称 |
|
||||
| email | string | 否 | GitHub邮箱地址 |
|
||||
| avatar_url | string | 否 | GitHub头像URL |
|
||||
|
||||
#### 响应示例
|
||||
|
||||
**成功响应** (200):
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"user": {
|
||||
"id": "3",
|
||||
"username": "octocat",
|
||||
"nickname": "The Octocat",
|
||||
"email": "octocat@github.com",
|
||||
"phone": null,
|
||||
"avatar_url": "https://github.com/images/error/octocat_happy.gif",
|
||||
"role": 1,
|
||||
"created_at": "2025-12-17T10:00:00.000Z"
|
||||
},
|
||||
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||||
"is_new_user": true,
|
||||
"message": "GitHub账户绑定成功"
|
||||
},
|
||||
"message": "GitHub账户绑定成功"
|
||||
}
|
||||
```
|
||||
|
||||
### 4. 发送密码重置验证码
|
||||
|
||||
**接口地址**: `POST /auth/forgot-password`
|
||||
|
||||
**功能描述**: 向用户邮箱或手机发送密码重置验证码
|
||||
|
||||
#### 请求参数
|
||||
|
||||
```json
|
||||
{
|
||||
"identifier": "test@example.com"
|
||||
}
|
||||
```
|
||||
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| identifier | string | 是 | 邮箱或手机号 |
|
||||
|
||||
#### 响应示例
|
||||
|
||||
**成功响应** (200):
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"verification_code": "123456"
|
||||
},
|
||||
"message": "验证码已发送，请查收"
|
||||
}
|
||||
```
|
||||
|
||||
**注意**: 实际应用中不应返回验证码，这里仅用于演示。
|
||||
|
||||
### 5. 重置密码
|
||||
|
||||
**接口地址**: `POST /auth/reset-password`
|
||||
|
||||
**功能描述**: 使用验证码重置用户密码
|
||||
|
||||
#### 请求参数
|
||||
|
||||
```json
|
||||
{
|
||||
"identifier": "test@example.com",
|
||||
"verification_code": "123456",
|
||||
"new_password": "newpassword123"
|
||||
}
|
||||
```
|
||||
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| identifier | string | 是 | 邮箱或手机号 |
|
||||
| verification_code | string | 是 | 6位数字验证码 |
|
||||
| new_password | string | 是 | 新密码，必须包含字母和数字，长度8-128字符 |
|
||||
|
||||
#### 响应示例
|
||||
|
||||
**成功响应** (200):
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "密码重置成功"
|
||||
}
|
||||
```
|
||||
|
||||
### 6. 修改密码
|
||||
|
||||
**接口地址**: `PUT /auth/change-password`
|
||||
|
||||
**功能描述**: 用户修改自己的密码（需要提供旧密码）
|
||||
|
||||
#### 请求参数
|
||||
|
||||
```json
|
||||
{
|
||||
"user_id": "1",
|
||||
"old_password": "oldpassword123",
|
||||
"new_password": "newpassword123"
|
||||
}
|
||||
```
|
||||
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| user_id | string | 是 | 用户ID（实际应用中应从JWT令牌中获取） |
|
||||
| old_password | string | 是 | 当前密码 |
|
||||
| new_password | string | 是 | 新密码，必须包含字母和数字，长度8-128字符 |
|
||||
|
||||
#### 响应示例
|
||||
|
||||
**成功响应** (200):
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "密码修改成功"
|
||||
}
|
||||
```
|
||||
|
||||
## 错误代码说明
|
||||
|
||||
| 错误代码 | 说明 |
|
||||
|----------|------|
|
||||
| LOGIN_FAILED | 登录失败 |
|
||||
| REGISTER_FAILED | 注册失败 |
|
||||
| GITHUB_OAUTH_FAILED | GitHub OAuth失败 |
|
||||
| SEND_CODE_FAILED | 发送验证码失败 |
|
||||
| RESET_PASSWORD_FAILED | 重置密码失败 |
|
||||
| CHANGE_PASSWORD_FAILED | 修改密码失败 |
|
||||
|
||||
## 数据验证规则
|
||||
|
||||
### 用户名规则
|
||||
- 长度：1-50字符
|
||||
- 格式：只能包含字母、数字和下划线
|
||||
- 正则表达式：`^[a-zA-Z0-9_]+$`
|
||||
|
||||
### 密码规则
|
||||
- 长度：8-128字符
|
||||
- 格式：必须包含字母和数字
|
||||
- 正则表达式：`^(?=.*[a-zA-Z])(?=.*\d)`
|
||||
|
||||
### 验证码规则
|
||||
- 长度：6位数字
|
||||
- 正则表达式：`^\d{6}$`
|
||||
|
||||
## 使用示例
|
||||
|
||||
### JavaScript/TypeScript 示例
|
||||
|
||||
```typescript
|
||||
// 用户登录
|
||||
const loginResponse = await fetch('http://localhost:3000/auth/login', {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Content-Type': 'application/json',
|
||||
},
|
||||
body: JSON.stringify({
|
||||
identifier: 'testuser',
|
||||
password: 'password123'
|
||||
})
|
||||
});
|
||||
|
||||
const loginData = await loginResponse.json();
|
||||
if (loginData.success) {
|
||||
const token = loginData.data.access_token;
|
||||
// 保存token用于后续请求
|
||||
localStorage.setItem('token', token);
|
||||
}
|
||||
|
||||
// 用户注册
|
||||
const registerResponse = await fetch('http://localhost:3000/auth/register', {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Content-Type': 'application/json',
|
||||
},
|
||||
body: JSON.stringify({
|
||||
username: 'newuser',
|
||||
password: 'password123',
|
||||
nickname: '新用户',
|
||||
email: 'newuser@example.com'
|
||||
})
|
||||
});
|
||||
|
||||
const registerData = await registerResponse.json();
|
||||
```
|
||||
|
||||
### cURL 示例
|
||||
|
||||
```bash
|
||||
# 用户登录
|
||||
curl -X POST http://localhost:3000/auth/login \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"identifier": "testuser",
|
||||
"password": "password123"
|
||||
}'
|
||||
|
||||
# 用户注册
|
||||
curl -X POST http://localhost:3000/auth/register \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"username": "newuser",
|
||||
"password": "password123",
|
||||
"nickname": "新用户",
|
||||
"email": "newuser@example.com"
|
||||
}'
|
||||
|
||||
# 发送密码重置验证码
|
||||
curl -X POST http://localhost:3000/auth/forgot-password \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"identifier": "test@example.com"
|
||||
}'
|
||||
|
||||
# 重置密码
|
||||
curl -X POST http://localhost:3000/auth/reset-password \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"identifier": "test@example.com",
|
||||
"verification_code": "123456",
|
||||
"new_password": "newpassword123"
|
||||
}'
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **安全性**: 实际应用中应使用HTTPS协议
|
||||
2. **令牌**: 示例中的access_token是简单的Base64编码，实际应用中应使用JWT
|
||||
3. **验证码**: 实际应用中不应在响应中返回验证码
|
||||
4. **用户ID**: 修改密码接口中的user_id应从JWT令牌中获取，而不是从请求体中传递
|
||||
5. **错误处理**: 建议在客户端实现适当的错误处理和用户提示
|
||||
6. **限流**: 建议对登录、注册等接口实施限流策略
|
||||
|
||||
## 更新日志
|
||||
|
||||
- **v1.0.0** (2025-12-17): 初始版本，包含基础的用户认证功能
|
||||
Reference in New Issue
Block a user