forked from datawhale/whale-town-end
459 lines
10 KiB
Markdown
459 lines
10 KiB
Markdown
# 用户认证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): 初始版本，包含基础的用户认证功能
|
||
## 管理员接口
|
||
|
||
**注意**：所有管理员接口都需要在 Header 中携带 ，且用户角色必须为管理员 (role=9)。
|
||
|
||
### 1. 获取用户列表
|
||
|
||
**接口地址**: `GET /admin/users`
|
||
|
||
**功能描述**: 分页获取所有注册用户列表
|
||
|
||
#### 请求参数
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| page | number | 否 | 页码，默认1 |
|
||
| limit | number | 否 | 每页数量，默认10 |
|
||
|
||
### 2. 重置用户密码
|
||
|
||
**接口地址**: `POST /admin/users/:id/reset-password`
|
||
|
||
**功能描述**: 管理员强制重置指定用户的密码
|
||
|
||
#### 请求参数
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| password | string | 是 | 新密码 |
|
||
|
||
### 3. 删除用户
|
||
|
||
**接口地址**: `DELETE /admin/users/:id`
|
||
|
||
**功能描述**: 删除指定用户
|
||
|
||
### 4. 修改用户角色
|
||
|
||
**接口地址**: `POST /admin/users/:id/role`
|
||
|
||
**功能描述**: 修改用户的角色权限
|
||
|
||
#### 请求参数
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| role | number | 是 | 角色ID (1:普通用户, 9:管理员) |
|