forked from datawhale/whale-town-end
docs: 更新API文档，反映HTTP状态码修复
文档更新内容： - 更新注册接口响应示例，区分400和409状态码 - 添加资源冲突响应示例（用户名、邮箱、手机号已存在） - 完善OpenAPI文档，添加详细的响应示例 - 更新错误码表格，明确不同错误的状态码 - 添加HTTP状态码测试场景 修复说明： - 409 Conflict：用户名/邮箱/手机号已存在 - 400 Bad Request：验证码错误/参数格式错误 - 符合RESTful API规范 测试验证： - 邮箱冲突：HTTP 409 - 用户名冲突：HTTP 409 - 验证码错误：HTTP 400 前端开发者现在可以： - 根据HTTP状态码进行精确的错误处理 - 移除临时解决方案，使用标准状态码判断 - 提供更好的用户体验和错误提示
This commit is contained in:
moyin
@@ -339,6 +339,26 @@
|
||||
|
||||
**失败响应** (400):
|
||||
|
||||
**验证码错误**:
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"message": "验证码不存在或已过期",
|
||||
"error_code": "REGISTER_FAILED"
|
||||
}
|
||||
```
|
||||
|
||||
**参数格式错误**:
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"message": "密码必须包含字母和数字，长度8-128字符",
|
||||
"error_code": "REGISTER_FAILED"
|
||||
}
|
||||
```
|
||||
|
||||
**冲突响应** (409):
|
||||
|
||||
**用户名已存在**:
|
||||
```json
|
||||
{
|
||||
@@ -366,6 +386,15 @@
|
||||
}
|
||||
```
|
||||
|
||||
**手机号已存在**:
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"message": "手机号已存在",
|
||||
"error_code": "REGISTER_FAILED"
|
||||
}
|
||||
```
|
||||
|
||||
**邮箱验证码相关错误**:
|
||||
```json
|
||||
{
|
||||
@@ -1455,7 +1484,7 @@ const cleanupTestData = async () => {
|
||||
| 错误代码 | HTTP状态码 | 说明 | 触发条件 |
|
||||
|----------|------------|------|----------|
|
||||
| LOGIN_FAILED | 401 | 登录失败 | 用户名不存在、密码错误、账户被锁定 |
|
||||
| REGISTER_FAILED | 400/409 | 注册失败 | 用户名已存在、密码强度不足、验证码错误 |
|
||||
| REGISTER_FAILED | 400/409 | 注册失败 | 验证码错误(400)、用户名已存在(409)、邮箱已存在(409) |
|
||||
| GITHUB_OAUTH_FAILED | 401 | GitHub OAuth失败 | GitHub认证信息无效 |
|
||||
| SEND_CODE_FAILED | 400 | 发送验证码失败 | 邮箱格式错误、发送服务异常 |
|
||||
| RESET_PASSWORD_FAILED | 400 | 重置密码失败 | 验证码无效、密码强度不足 |
|
||||
@@ -1929,6 +1958,9 @@ MAINTENANCE_RETRY_AFTER=1800
|
||||
- 调试接口：`POST /auth/debug-verification-code` 可获取验证码详情
|
||||
4. **用户ID**: 修改密码接口中的user_id应从JWT令牌中获取，而不是从请求体中传递
|
||||
5. **错误处理**: 建议在客户端实现适当的错误处理和用户提示
|
||||
- 409 Conflict：资源冲突（用户名、邮箱、手机号已存在）
|
||||
- 400 Bad Request：请求参数错误（验证码错误、格式错误）
|
||||
- 根据HTTP状态码进行不同的错误处理逻辑
|
||||
6. **限流**: 建议对登录、注册等接口实施限流策略
|
||||
7. **管理员权限**:
|
||||
- 管理员接口需要 role=9 的用户权限
|
||||
@@ -2060,7 +2092,67 @@ const testLoginFailures = async () => {
|
||||
};
|
||||
```
|
||||
|
||||
#### **4. 频率限制测试**
|
||||
#### **4. 注册冲突HTTP状态码测试**
|
||||
```javascript
|
||||
// 场景：测试注册冲突的正确HTTP状态码
|
||||
const testRegistrationConflicts = async () => {
|
||||
// 用户名冲突 - 应返回409
|
||||
try {
|
||||
await fetch('/auth/register', {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify({
|
||||
username: 'existinguser',
|
||||
password: 'Test123456',
|
||||
nickname: '测试用户',
|
||||
email: 'newemail@example.com',
|
||||
email_verification_code: '123456'
|
||||
})
|
||||
});
|
||||
} catch (error) {
|
||||
expect(error.status).toBe(409); // Conflict
|
||||
expect(error.message).toContain('用户名已存在');
|
||||
}
|
||||
|
||||
// 邮箱冲突 - 应返回409
|
||||
try {
|
||||
await fetch('/auth/register', {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify({
|
||||
username: 'newuser',
|
||||
password: 'Test123456',
|
||||
nickname: '测试用户',
|
||||
email: 'existing@example.com',
|
||||
email_verification_code: '123456'
|
||||
})
|
||||
});
|
||||
} catch (error) {
|
||||
expect(error.status).toBe(409); // Conflict
|
||||
expect(error.message).toContain('邮箱已存在');
|
||||
}
|
||||
|
||||
// 验证码错误 - 应返回400
|
||||
try {
|
||||
await fetch('/auth/register', {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify({
|
||||
username: 'newuser',
|
||||
password: 'Test123456',
|
||||
nickname: '测试用户',
|
||||
email: 'new@example.com',
|
||||
email_verification_code: '999999'
|
||||
})
|
||||
});
|
||||
} catch (error) {
|
||||
expect(error.status).toBe(400); // Bad Request
|
||||
expect(error.message).toContain('验证码');
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
#### **5. 频率限制测试**
|
||||
```javascript
|
||||
// 场景：验证码发送频率限制
|
||||
const testRateLimit = async () => {
|
||||
@@ -2087,7 +2179,7 @@ const testRateLimit = async () => {
|
||||
};
|
||||
```
|
||||
|
||||
#### **5. 管理员权限测试**
|
||||
#### **6. 管理员权限测试**
|
||||
```javascript
|
||||
// 场景：管理员权限验证
|
||||
const testAdminPermissions = async () => {
|
||||
@@ -2117,7 +2209,7 @@ const testAdminPermissions = async () => {
|
||||
};
|
||||
```
|
||||
|
||||
#### **6. 用户状态影响登录**
|
||||
#### **7. 用户状态影响登录**
|
||||
```javascript
|
||||
// 场景：不同用户状态的登录测试
|
||||
const testUserStatusLogin = async () => {
|
||||
@@ -2294,11 +2386,17 @@ echo "📈 性能测试完成，请查看上述结果"
|
||||
- 添加发送登录验证码接口 (POST /auth/send-login-verification-code)
|
||||
- 支持邮箱和手机号验证码登录
|
||||
- 完善验证码相关错误处理和限流机制
|
||||
- **修复HTTP状态码问题**
|
||||
- 用户注册冲突错误：400 → 409 Conflict
|
||||
- 用户名已存在：返回409状态码
|
||||
- 邮箱已存在：返回409状态码
|
||||
- 手机号已存在：返回409状态码
|
||||
- 符合RESTful API规范
|
||||
- **文档完善**
|
||||
- 更新API文档，新增验证码登录相关说明
|
||||
- 修正错误码与实际响应的一致性
|
||||
- 添加验证码登录测试场景和使用示例
|
||||
- 更新OpenAPI规范文档
|
||||
- 更新OpenAPI规范文档，完善响应示例
|
||||
- **接口数量更新**：21个 → 23个API接口
|
||||
- **用户认证接口**：11个 → 13个接口
|
||||
- **v1.0.0** (2025-12-24):
|
||||
|
||||
@@ -128,17 +128,49 @@ paths:
|
||||
schema:
|
||||
$ref: '#/components/schemas/RegisterResponse'
|
||||
'400':
|
||||
description: 请求参数错误
|
||||
description: 请求参数错误或验证码错误
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
examples:
|
||||
validation_error:
|
||||
summary: 参数验证错误
|
||||
value:
|
||||
success: false
|
||||
message: "密码必须包含字母和数字，长度8-128字符"
|
||||
error_code: "REGISTER_FAILED"
|
||||
verification_code_error:
|
||||
summary: 验证码错误
|
||||
value:
|
||||
success: false
|
||||
message: "验证码不存在或已过期"
|
||||
error_code: "REGISTER_FAILED"
|
||||
'409':
|
||||
description: 用户名或邮箱已存在
|
||||
description: 资源冲突 - 用户名、邮箱或手机号已存在
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
examples:
|
||||
username_exists:
|
||||
summary: 用户名已存在
|
||||
value:
|
||||
success: false
|
||||
message: "用户名已存在"
|
||||
error_code: "REGISTER_FAILED"
|
||||
email_exists:
|
||||
summary: 邮箱已存在
|
||||
value:
|
||||
success: false
|
||||
message: "邮箱已存在"
|
||||
error_code: "REGISTER_FAILED"
|
||||
phone_exists:
|
||||
summary: 手机号已存在
|
||||
value:
|
||||
success: false
|
||||
message: "手机号已存在"
|
||||
error_code: "REGISTER_FAILED"
|
||||
|
||||
/auth/github:
|
||||
post:
|
||||
|
||||
Reference in New Issue
Block a user