# 用户注册

<cite>
**本文引用的文件**
- [auth_handler.go](file://internal/handler/auth_handler.go)
- [routes.go](file://internal/handler/routes.go)
- [common.go](file://internal/types/common.go)
- [response.go](file://internal/model/response.go)
- [user_service.go](file://internal/service/user_service.go)
- [verification_service.go](file://internal/service/verification_service.go)
- [password.go](file://pkg/auth/password.go)
- [user.go](file://internal/model/user.go)
- [auth_handler_test.go](file://internal/handler/auth_handler_test.go)
- [common_test.go](file://internal/types/common_test.go)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能与扩展性](#性能与扩展性)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本文件面向“用户注册”API，围绕 /api/v1/auth/register 端点进行完整说明。内容覆盖：
- HTTP 方法与路由
- 请求体字段与校验规则
- 响应格式与错误码
- 验证码机制与防暴力注册策略
- 密码加密存储流程
- 安全建议（密码强度、邮箱格式、防暴力注册）

## 项目结构
该功能由 Handler 层接收请求、Service 层执行业务逻辑、Model 层承载数据模型，并通过 JWT 生成登录令牌；验证码由 Redis 缓存并在邮件服务中发送。

```mermaid
graph TB
Client["客户端"] --> Routes["路由: /api/v1/auth/register"]
Routes --> Handler["处理器: Register"]
Handler --> VerifyCode["验证码校验: VerifyCode"]
Handler --> UserService["服务: RegisterUser"]
UserService --> Password["密码加密: HashPassword"]
UserService --> ModelUser["用户模型: User"]
UserService --> JWT["JWT 服务: GenerateToken"]
Handler --> Response["统一响应: Response/ErrorResponse"]
```

图表来源
- [routes.go](file://internal/handler/routes.go#L16-L26)
- [auth_handler.go](file://internal/handler/auth_handler.go#L17-L84)
- [verification_service.go](file://internal/service/verification_service.go#L79-L98)
- [user_service.go](file://internal/service/user_service.go#L12-L68)
- [password.go](file://pkg/auth/password.go#L7-L21)
- [user.go](file://internal/model/user.go#L7-L21)
- [response.go](file://internal/model/response.go#L20-L73)

章节来源
- [routes.go](file://internal/handler/routes.go#L16-L26)

## 核心组件
- 路由与入口
  - 路由位于 v1 组下的 /auth/register，无需 JWT 即可访问。
- 请求体与校验
  - 请求体字段：username、email、password、avatar、verification_code。
  - 校验规则：必填、长度/格式约束、验证码长度固定为6。
- 业务处理
  - 验证码校验通过后，检查用户名/邮箱唯一性，加密密码，创建用户并生成 JWT。
- 响应与错误
  - 成功返回包含 token 与用户信息的结构化响应；常见错误包括参数错误、验证码错误、用户名/邮箱已存在等。

章节来源
- [auth_handler.go](file://internal/handler/auth_handler.go#L17-L84)
- [common.go](file://internal/types/common.go#L33-L40)
- [response.go](file://internal/model/response.go#L20-L73)
- [user_service.go](file://internal/service/user_service.go#L12-L68)
- [verification_service.go](file://internal/service/verification_service.go#L79-L98)

## 架构总览
注册流程的端到端调用序列如下：

```mermaid
sequenceDiagram
participant C as "客户端"
participant R as "路由"
participant H as "处理器 : Register"
participant VS as "验证码服务 : VerifyCode"
participant US as "用户服务 : RegisterUser"
participant PS as "密码服务 : HashPassword"
participant M as "用户模型 : User"
participant JS as "JWT服务 : GenerateToken"
participant RESP as "响应"
C->>R : POST /api/v1/auth/register
R->>H : 转发请求
H->>H : 解析并绑定请求体
H->>VS : 校验邮箱验证码
VS-->>H : 验证通过/失败
alt 验证失败
H-->>RESP : 返回400错误
else 验证通过
H->>US : 调用注册流程
US->>US : 检查用户名/邮箱唯一性
US->>PS : 加密密码
PS-->>US : 密文
US->>M : 创建用户记录
US->>JS : 生成JWT
JS-->>US : token
US-->>H : 返回用户与token
H-->>RESP : 返回200成功响应
end
```

图表来源
- [auth_handler.go](file://internal/handler/auth_handler.go#L27-L84)
- [verification_service.go](file://internal/service/verification_service.go#L79-L98)
- [user_service.go](file://internal/service/user_service.go#L12-L68)
- [password.go](file://pkg/auth/password.go#L7-L21)
- [user.go](file://internal/model/user.go#L7-L21)
- [response.go](file://internal/model/response.go#L20-L73)

## 详细组件分析

### 接口定义与请求体
- 端点：POST /api/v1/auth/register
- 请求体字段
  - username：必填，长度3~50
  - email：必填，邮箱格式
  - password：必填，长度6~128
  - avatar：可选，URL格式
  - verification_code：必填，长度6
- 响应
  - 成功：返回包含 token 与用户信息的结构化响应
  - 失败：返回统一错误响应，包含业务码与消息

章节来源
- [auth_handler.go](file://internal/handler/auth_handler.go#L17-L84)
- [common.go](file://internal/types/common.go#L33-L40)
- [response.go](file://internal/model/response.go#L20-L73)

### 验证码机制与防暴力注册
- 验证码生成与存储
  - 生成6位数字验证码，有效期10分钟，发送频率限制1分钟。
  - 存储于 Redis，键命名包含类型与邮箱。
- 验证流程
  - 校验验证码是否存在且一致，一致即删除该验证码。
- 防暴力注册
  - 发送频率限制键存在即拒绝重复发送，降低刷验证码风险。
  - 注册接口对用户名/邮箱唯一性检查，避免重复注册。

```mermaid
flowchart TD
Start(["开始"]) --> Gen["生成6位验证码"]
Gen --> Store["写入Redis: 验证码键(10分钟)"]
Store --> RateLimit["写入Redis: 发送频率限制键(1分钟)"]
RateLimit --> Email["发送邮件"]
Email --> Verify["校验验证码"]
Verify --> Match{"是否匹配?"}
Match --> |否| Expired["返回错误: 验证码错误/过期"]
Match --> |是| Del["删除验证码键"]
Del --> Done(["结束"])
```

图表来源
- [verification_service.go](file://internal/service/verification_service.go#L26-L98)

章节来源
- [verification_service.go](file://internal/service/verification_service.go#L14-L24)
- [verification_service.go](file://internal/service/verification_service.go#L40-L77)
- [verification_service.go](file://internal/service/verification_service.go#L79-L98)

### 密码加密与存储
- 加密方式：bcrypt，默认成本
- 存储：用户密码以密文形式保存，不返回明文
- 登录校验：使用 bcrypt 对比哈希

```mermaid
flowchart TD
In(["输入明文密码"]) --> Hash["bcrypt加密"]
Hash --> Out(["返回密文"])
Out --> Store["持久化存储"]
Store --> Login["登录时对比哈希"]
Login --> Ok["匹配成功"]
Login --> Fail["匹配失败"]
```

图表来源
- [password.go](file://pkg/auth/password.go#L7-L21)
- [user_service.go](file://internal/service/user_service.go#L32-L36)
- [user.go](file://internal/model/user.go#L7-L21)

章节来源
- [password.go](file://pkg/auth/password.go#L7-L21)
- [user_service.go](file://internal/service/user_service.go#L32-L36)
- [user.go](file://internal/model/user.go#L7-L21)

### 用户模型与唯一性约束
- 用户模型包含：id、username、password、email、avatar、points、role、status、属性、登录时间、创建/更新时间等
- 唯一性约束：username 与 email 在数据库层面唯一索引
- 注册时：若用户名或邮箱已存在，返回错误

```mermaid
erDiagram
USER {
bigint id PK
varchar username UK
varchar password
varchar email UK
varchar avatar
integer points
varchar role
smallint status
jsonb properties
timestamp last_login_at
timestamp created_at
timestamp updated_at
}
```

图表来源
- [user.go](file://internal/model/user.go#L7-L21)

章节来源
- [user.go](file://internal/model/user.go#L7-L21)
- [user_service.go](file://internal/service/user_service.go#L14-L31)

### 错误码与响应格式
- 成功：200，返回结构化响应，包含 token 与用户信息
- 参数错误：400，请求体绑定失败或字段校验失败
- 验证码错误：400，验证码不存在/过期/不匹配
- 资源冲突：409，用户名或邮箱已存在
- 服务器错误：500，内部异常

章节来源
- [auth_handler.go](file://internal/handler/auth_handler.go#L27-L84)
- [response.go](file://internal/model/response.go#L20-L73)
- [user_service.go](file://internal/service/user_service.go#L14-L31)

### 安全考虑与最佳实践
- 密码强度
  - 至少6位，建议结合复杂度策略（字母、数字、特殊字符）
  - 使用 bcrypt 存储，避免明文或弱加密
- 邮箱格式验证
  - 使用框架内置邮箱格式校验
- 防暴力注册
  - 验证码发送频率限制（1分钟）
  - 验证码有效期（10分钟），过期自动失效
  - 唯一性检查防止重复注册
- 传输安全
  - 建议启用 HTTPS，避免明文传输
- 日志与审计
  - 记录注册失败与异常行为，便于追踪

章节来源
- [verification_service.go](file://internal/service/verification_service.go#L14-L24)
- [verification_service.go](file://internal/service/verification_service.go#L40-L77)
- [verification_service.go](file://internal/service/verification_service.go#L79-L98)
- [user_service.go](file://internal/service/user_service.go#L14-L31)
- [password.go](file://pkg/auth/password.go#L7-L21)

## 依赖关系分析
- 处理器依赖
  - 验证码服务：用于校验注册验证码
  - 用户服务：执行注册流程（唯一性检查、密码加密、创建用户、生成JWT）
  - JWT 服务：生成登录令牌
- 服务依赖
  - 密码服务：bcrypt 加密与校验
  - 数据模型：用户实体
- 工具与中间件
  - 路由：定义 /api/v1/auth/register
  - 统一响应：封装业务码与消息

```mermaid
graph LR
Handler["处理器: Register"] --> VS["验证码服务: VerifyCode"]
Handler --> US["用户服务: RegisterUser"]
US --> PS["密码服务: HashPassword"]
US --> Model["用户模型: User"]
US --> JWT["JWT服务: GenerateToken"]
Handler --> Resp["统一响应: Response/ErrorResponse"]
Route["路由: /api/v1/auth/register"] --> Handler
```

图表来源
- [auth_handler.go](file://internal/handler/auth_handler.go#L27-L84)
- [verification_service.go](file://internal/service/verification_service.go#L79-L98)
- [user_service.go](file://internal/service/user_service.go#L12-L68)
- [password.go](file://pkg/auth/password.go#L7-L21)
- [user.go](file://internal/model/user.go#L7-L21)
- [response.go](file://internal/model/response.go#L20-L73)
- [routes.go](file://internal/handler/routes.go#L16-L26)

章节来源
- [auth_handler.go](file://internal/handler/auth_handler.go#L27-L84)
- [user_service.go](file://internal/service/user_service.go#L12-L68)
- [verification_service.go](file://internal/service/verification_service.go#L79-L98)
- [password.go](file://pkg/auth/password.go#L7-L21)
- [user.go](file://internal/model/user.go#L7-L21)
- [response.go](file://internal/model/response.go#L20-L73)
- [routes.go](file://internal/handler/routes.go#L16-L26)

## 性能与扩展性
- 验证码缓存
  - Redis 存储验证码与频率限制，具备高并发与低延迟特性
- 密码加密
  - bcrypt 默认成本在安全性与性能间平衡，可根据硬件能力调整
- 扩展建议
  - 引入速率限制中间件，对 /api/v1/auth/register 进一步限流
  - 增加 IP/设备维度的风控策略
  - 对高频失败场景增加验证码挑战或人机验证

[本节为通用建议，不直接分析具体文件]

## 故障排查指南
- 常见错误与定位
  - 参数错误：检查请求体字段是否满足长度/格式要求
  - 验证码错误：确认验证码是否过期、是否与发送邮箱一致
  - 用户名/邮箱已存在：检查数据库唯一性约束
- 单元测试参考
  - 注册请求体校验、错误处理与响应格式可通过测试用例验证

章节来源
- [auth_handler_test.go](file://internal/handler/auth_handler_test.go#L74-L116)
- [common_test.go](file://internal/types/common_test.go#L215-L287)

## 结论
用户注册 API 通过严格的请求体校验、验证码机制与 bcrypt 密码加密，提供了基础的安全保障。配合唯一性检查与频率限制，能够有效降低重复注册与暴力注册的风险。建议在生产环境中进一步完善风控策略与监控告警体系。

[本节为总结性内容，不直接分析具体文件]

## 附录

### 请求与响应示例（路径引用）
- 请求体字段与校验规则
  - 字段定义与校验规则参见：[请求体定义](file://internal/types/common.go#L33-L40)
- 成功响应结构
  - 成功响应结构参见：[统一响应](file://internal/model/response.go#L20-L73)
  - 登录响应结构参见：[登录响应](file://internal/types/common.go#L107-L126)
- 错误响应结构
  - 错误响应结构参见：[错误响应](file://internal/model/response.go#L20-L73)
- 路由与端点
  - 注册路由参见：[路由定义](file://internal/handler/routes.go#L16-L26)
- 处理器与业务流程
  - 注册处理器参见：[注册处理器](file://internal/handler/auth_handler.go#L27-L84)
  - 注册业务流程参见：[注册服务](file://internal/service/user_service.go#L12-L68)
- 验证码与防暴力
  - 验证码生成与校验参见：[验证码服务](file://internal/service/verification_service.go#L26-L98)
- 密码加密
  - 密码加密与校验参见：[密码服务](file://pkg/auth/password.go#L7-L21)