diff --git a/docs/api/api-documentation.md b/docs/api/api-documentation.md index 26c7ec1..3689658 100644 --- a/docs/api/api-documentation.md +++ b/docs/api/api-documentation.md @@ -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): diff --git a/docs/api/openapi.yaml b/docs/api/openapi.yaml index 3235acc..b482c53 100644 --- a/docs/api/openapi.yaml +++ b/docs/api/openapi.yaml @@ -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: