first commit

2026-02-13 15:57:29 +08:00
commit aacda0b66a
53 changed files with 10029 additions and 0 deletions
--- a/docs/development/project-structure.md
+++ b/docs/development/project-structure.md
@@ -0,0 +1,615 @@
+# 项目结构详解
+
+本文档详细说明 Web Rust Template 的项目结构、DDD 分层架构和各层职责。
+
+## 目录
+
+- [DDD 分层架构](#ddd-分层架构)
+- [项目目录结构](#项目目录结构)
+- [各层职责说明](#各层职责说明)
+- [数据流转](#数据流转)
+- [核心组件](#核心组件)
+
+---
+
+## DDD 分层架构
+
+本系统采用**领域驱动设计（DDD）**的分层架构，将代码划分为不同的职责层次。
+
+```
+┌─────────────────────────────────────────┐
+│      Interface Layer (handlers)        │  HTTP 处理器层
+│      路由定义、请求处理、响应封装      │
+└──────────────┬───────────────────────┘
+               │
+┌──────────────▼───────────────────────┐
+│     Application Layer (services)     │  业务逻辑层
+│     业务逻辑、Token 生成、认证        │
+└──────────────┬───────────────────────┘
+               │
+       ┌───────┴────────┐
+       │                 │
+┌──────▼──────┐  ┌─────▼──────────┐
+│   Domain    │  │  Infrastructure│
+│   Layer     │  │  Layer         │
+│             │  │                │
+│ - DTO       │  │ - Middleware   │
+│ - Entities  │  │ - Redis       │
+│ - VO        │  │ - Repositories│
+└─────────────┘  └────────────────┘
+```
+
+### 分层优势
+
+| 优势 | 说明 |
+|------|------|
+| 职责清晰 | 每层只关注自己的职责，降低耦合 |
+| 易于测试 | 每层可独立测试，Mock 依赖 |
+| 易于维护 | 修改某层不影响其他层 |
+| 易于扩展 | 添加新功能只需扩展相应层 |
+
+---
+
+## 项目目录结构
+
+```
+web-rust-template/
+├── src/                          # 源代码目录
+│   ├── main.rs                   # 应用入口
+│   ├── cli.rs                   # 命令行参数解析
+│   ├── config.rs                # 配置模块导出
+│   ├── db.rs                   # 数据库连接池
+│   ├── error.rs                # 错误处理
+│   │
+│   ├── config/                  # 配置模块
+│   │   ├── app.rs             # 主配置结构
+│   │   ├── auth.rs            # 认证配置
+│   │   ├── database.rs        # 数据库配置
+│   │   ├── redis.rs          # Redis 配置
+│   │   └── server.rs         # 服务器配置
+│   │
+│   ├── domain/                  # 领域层（DDD）
+│   │   ├── dto/               # 数据传输对象（Data Transfer Object）
+│   │   │   └── auth.rs      # 认证相关 DTO
+│   │   ├── entities/          # 实体（数据库模型）
+│   │   │   └── users.rs     # 用户实体
+│   │   └── vo/               # 视图对象（View Object）
+│   │       └── auth.rs      # 认证相关 VO
+│   │
+│   ├── handlers/                # HTTP 处理器层（接口层）
+│   │   ├── auth.rs           # 认证接口
+│   │   └── health.rs        # 健康检查接口
+│   │
+│   ├── infra/                   # 基础设施层
+│   │   ├── middleware/       # 中间件
+│   │   │   ├── auth.rs     # JWT 认证中间件
+│   │   │   └── logging.rs  # 日志中间件
+│   │   └── redis/           # Redis 客户端封装
+│   │       ├── redis_client.rs
+│   │       └── redis_key.rs
+│   │
+│   ├── repositories/            # 数据访问层
+│   │   └── user_repository.rs  # 用户数据访问
+│   │
+│   ├── services/                # 业务逻辑层
+│   │   └── auth_service.rs   # 认证业务逻辑
+│   │
+│   └── utils/                   # 工具函数
+│       └── jwt.rs            # JWT 工具类
+│
+├── config/                      # 配置文件目录
+│   ├── default.toml           # 默认配置
+│   ├── development.sqlite.toml     # SQLite 开发环境配置
+│   ├── development.mysql.toml      # MySQL 开发环境配置
+│   ├── development.postgresql.toml  # PostgreSQL 开发环境配置
+│   └── production.toml       # 生产环境配置
+│
+├── sql/                         # SQL 脚本
+│   └── init.sql               # 数据库初始化脚本
+│
+├── tests/                      # 测试目录
+│   └── integration_test.rs   # 集成测试
+│
+├── docs/                       # 文档目录
+│   ├── README.md
+│   ├── api/
+│   ├── development/
+│   └── deployment/
+│
+├── .env.example               # 环境变量参考（仅用于 Docker/Kubernetes 等部署场景)
+├── .gitignore               # Git 忽略文件
+├── Cargo.toml               # 项目依赖定义
+├── README.md                # 项目说明
+└── rust-toolchain.toml      # Rust 工具链配置
+```
+
+---
+
+## 各层职责说明
+
+### 1. 接口层（handlers/）
+
+**职责**：处理 HTTP 请求和响应
+
+**位置**：`src/handlers/`
+
+**关键文件**：
+- `auth.rs`：认证相关接口（注册、登录、刷新 Token、删除账号）
+- `health.rs`：健康检查和服务器信息接口
+
+**示例**：
+```rust
+// src/handlers/auth.rs
+
+pub async fn register(
+    Extension(request_id): Extension<RequestId>,
+    State(state): State<AppState>,
+    Json(payload): Json<RegisterRequest>,
+) -> Result<Json<ApiResponse<RegisterResult>>, ErrorResponse> {
+    // 1. 记录日志
+    log_info(&request_id, "注册请求参数", &payload);
+
+    // 2. 调用服务层处理业务逻辑
+    let user_repo = UserRepository::new(state.pool.clone());
+    let service = AuthService::new(user_repo, state.redis_client.clone(), state.config.auth.clone());
+
+    // 3. 调用业务逻辑
+    match service.register(payload).await {
+        Ok((user_model, access_token, refresh_token)) => {
+            let data = RegisterResult::from((user_model, access_token, refresh_token));
+            let response = ApiResponse::success(data);
+            log_info(&request_id, "注册成功", &response);
+            Ok(Json(response))
+        }
+        Err(e) => {
+            log_info(&request_id, "注册失败", &e.to_string());
+            Err(ErrorResponse::new(e.to_string()))
+        }
+    }
+}
+```
+
+**职责边界**：
+- ✅ 接收 HTTP 请求
+- ✅ 提取请求参数
+- ✅ 调用服务层处理业务逻辑
+- ✅ 封装响应数据
+- ❌ 不包含业务逻辑
+- ❌ 不直接访问数据库
+
+### 2. 业务逻辑层（services/）
+
+**职责**：实现核心业务逻辑
+
+**位置**：`src/services/`
+
+**关键文件**：
+- `auth_service.rs`：认证业务逻辑（注册、登录、Token 刷新、密码哈希）
+
+**示例**：
+```rust
+// src/services/auth_service.rs
+
+pub struct AuthService {
+    user_repo: UserRepository,
+    redis_client: RedisClient,
+    auth_config: AuthConfig,
+}
+
+impl AuthService {
+    /// 用户注册
+    pub async fn register(&self, payload: RegisterRequest) -> Result<(Model, String, String)> {
+        // 1. 验证邮箱格式
+        if !payload.email.contains('@') {
+            return Err(anyhow!("邮箱格式错误"));
+        }
+
+        // 2. 生成唯一用户 ID
+        let user_id = self.generate_unique_user_id().await?;
+
+        // 3. 哈希密码
+        let password_hash = self.hash_password(&payload.password)?;
+
+        // 4. 创建用户实体
+        let user_model = users::Model {
+            id: user_id,
+            email: payload.email.clone(),
+            password_hash,
+            created_at: chrono::Utc::now().naive_utc(),
+            updated_at: chrono::Utc::now().naive_utc(),
+        };
+
+        // 5. 保存到数据库
+        let created_user = self.user_repo.create(user_model).await?;
+
+        // 6. 生成 Token
+        let (access_token, refresh_token) = TokenService::generate_token_pair(
+            &created_user.id,
+            self.auth_config.access_token_expiration_minutes,
+            self.auth_config.refresh_token_expiration_days,
+            &self.auth_config.jwt_secret,
+        )?;
+
+        // 7. 保存 Refresh Token 到 Redis
+        self.save_refresh_token(&created_user.id, &refresh_token, self.auth_config.refresh_token_expiration_days).await?;
+
+        Ok((created_user, access_token, refresh_token))
+    }
+}
+```
+
+**职责边界**：
+- ✅ 实现业务逻辑
+- ✅ 协调 Repository 和基础设施
+- ✅ 事务管理
+- ❌ 不处理 HTTP 请求/响应
+- ❌ 不直接访问外部资源（通过 Repository）
+
+### 3. 数据访问层（repositories/）
+
+**职责**：封装数据库访问逻辑
+
+**位置**：`src/repositories/`
+
+**关键文件**：
+- `user_repository.rs`：用户数据访问（增删改查）
+
+**示例**：
+```rust
+// src/repositories/user_repository.rs
+
+pub struct UserRepository {
+    pool: DbPool,
+}
+
+impl UserRepository {
+    pub fn new(pool: DbPool) -> Self {
+        Self { pool }
+    }
+
+    /// 创建用户
+    pub async fn create(&self, user_model: users::Model) -> Result<users::Model> {
+        let result = users::Entity::insert(user_model.into_active_model())
+            .exec(&self.pool)
+            .await
+            .map_err(|e| anyhow!("创建用户失败: {}", e))?;
+
+        Ok(users::Entity::find_by_id(result.last_insert_id))
+            .one(&self.pool)
+            .await
+            .map_err(|e| anyhow!("查询用户失败: {}", e))?
+            .ok_or_else(|| anyhow!("用户不存在"))
+    }
+
+    /// 根据邮箱查询用户
+    pub async fn find_by_email(&self, email: &str) -> Result<Option<users::Model>> {
+        Ok(users::Entity::find()
+            .filter(users::Column::Email.eq(email))
+            .one(&self.pool)
+            .await?)
+    }
+
+    /// 根据ID查询用户
+    pub async fn find_by_id(&self, id: &str) -> Result<Option<users::Model>> {
+        Ok(users::Entity::find_by_id(id.to_string())
+            .one(&self.pool)
+            .await?)
+    }
+
+    /// 统计相同ID的用户数量
+    pub async fn count_by_id(&self, id: &str) -> Result<u64> {
+        Ok(users::Entity::find_by_id(id.to_string())
+            .count(&self.pool)
+            .await?)
+    }
+}
+```
+
+**职责边界**：
+- ✅ 数据库 CRUD 操作
+- ✅ 封装 SeaORM 细节
+- ❌ 不包含业务逻辑
+- ❌ 不处理 HTTP 请求
+
+### 4. 领域层（domain/）
+
+**职责**：定义核心业务模型
+
+**位置**：`src/domain/`
+
+#### DTO（Data Transfer Object）
+
+**职责**：定义 API 请求和响应的数据结构
+
+**位置**：`src/domain/dto/`
+
+**示例**：
+```rust
+// src/domain/dto/auth.rs
+
+#[derive(Deserialize)]
+pub struct RegisterRequest {
+    pub email: String,
+    pub password: String,
+}
+
+#[derive(Deserialize)]
+pub struct LoginRequest {
+    pub email: String,
+    pub password: String,
+}
+```
+
+#### Entities（实体）
+
+**职责**：定义数据库表模型
+
+**位置**：`src/domain/entities/`
+
+**示例**：
+```rust
+// src/domain/entities/users.rs
+
+use sea_orm::entity::prelude::*;
+
+#[derive(Clone, Debug, PartialEq, DeriveEntityModel)]
+#[sea_orm(table_name = "users")]
+pub struct Model {
+    #[sea_orm(primary_key)]
+    pub id: String,
+    #[sea_orm(column_type = "Text", unique)]
+    pub email: String,
+    pub password_hash: String,
+    pub created_at: DateTime,
+    pub updated_at: DateTime,
+}
+```
+
+#### VO（View Object）
+
+**职责**：定义 API 响应的数据结构
+
+**位置**：`src/domain/vo/`
+
+**示例**：
+```rust
+// src/domain/vo/auth.rs
+
+#[derive(Debug, Serialize)]
+pub struct RegisterResult {
+    pub email: String,
+    pub created_at: String,
+    pub access_token: String,
+    pub refresh_token: String,
+}
+
+#[derive(Debug, Serialize)]
+pub struct LoginResult {
+    pub id: String,
+    pub email: String,
+    pub created_at: String,
+    pub access_token: String,
+    pub refresh_token: String,
+}
+```
+
+### 5. 基础设施层（infra/）
+
+**职责**：提供技术基础设施
+
+**位置**：`src/infra/`
+
+#### 中间件（middleware/）
+
+**职责**：请求拦截和处理
+
+**位置**：`src/infra/middleware/`
+
+**关键文件**：
+- `auth.rs`：JWT 认证中间件
+- `logging.rs`：日志中间件
+
+**示例**：
+```rust
+// src/infra/middleware/auth.rs
+
+pub async fn auth_middleware(
+    State(state): State<AppState>,
+    mut request: Request,
+    next: Next,
+) -> Result<Response, ErrorResponse> {
+    // 1. 提取 Authorization header
+    let auth_header = request
+        .headers()
+        .get("Authorization")
+        .and_then(|h| h.to_str().ok())
+        .ok_or_else(|| ErrorResponse::new("缺少 Authorization header".to_string()))?;
+
+    // 2. 验证 Bearer 格式
+    if !auth_header.starts_with("Bearer ") {
+        return Err(ErrorResponse::new("Authorization header 格式错误".to_string()));
+    }
+
+    let token = &auth_header[7..];
+
+    // 3. 验证 JWT
+    let claims = TokenService::decode_user_id(token, &state.config.auth.jwt_secret)?;
+
+    // 4. 将 user_id 添加到请求扩展
+    request.extensions_mut().insert(claims.sub);
+
+    // 5. 继续处理请求
+    Ok(next.run(request).await)
+}
+```
+
+#### Redis 客户端（redis/）
+
+**职责**：封装 Redis 操作
+
+**位置**：`src/infra/redis/`
+
+**关键文件**：
+- `redis_client.rs`：Redis 客户端封装
+- `redis_key.rs`：Redis Key 命名规范
+
+### 6. 工具层（utils/）
+
+**职责**：提供通用工具函数
+
+**位置**：`src/utils/`
+
+**关键文件**：
+- `jwt.rs`：JWT Token 生成和验证
+
+**示例**：
+```rust
+// src/utils/jwt.rs
+
+pub struct TokenService;
+
+impl TokenService {
+    /// 生成 Access Token
+    pub fn generate_access_token(
+        user_id: &str,
+        expiration_minutes: u64,
+        jwt_secret: &str,
+    ) -> Result<String> {
+        // ... 生成 JWT Token
+    }
+
+    /// 验证 Token 并提取 user_id
+    pub fn decode_user_id(token: &str, jwt_secret: &str) -> Result<String> {
+        // ... 验证并解码 JWT Token
+    }
+}
+```
+
+---
+
+## 数据流转
+
+### 用户注册流程
+
+```
+1. 客户端发起 POST /auth/register 请求
+   ↓
+2. handlers/auth.rs::register() 接收请求
+   - 提取请求参数（RegisterRequest）
+   ↓
+3. services/auth_service.rs::register() 处理业务逻辑
+   - 验证邮箱格式
+   - 生成唯一用户 ID
+   - 哈希密码
+   - 创建用户实体
+   ↓
+4. repositories/user_repository.rs::create() 保存到数据库
+   - 使用 SeaORM 插入数据
+   ↓
+5. services/auth_service.rs 生成 Token
+   - 生成 Access Token
+   - 生成 Refresh Token
+   ↓
+6. Redis 保存 Refresh Token
+   ↓
+7. handlers/auth.rs 封装响应（RegisterResult）
+   ↓
+8. 返回 JSON 响应给客户端
+```
+
+### 访问受保护接口流程
+
+```
+1. 客户端发起 POST /auth/delete 请求
+   - 携带 Authorization: Bearer <access_token>
+   ↓
+2. infra/middleware/auth.rs::auth_middleware() 拦截
+   - 验证 Token 格式
+   - 验证 JWT 签名
+   - 检查 Token 过期时间
+   - 提取 user_id 并添加到请求扩展
+   ↓
+3. handlers/auth.rs::delete_account() 接收请求
+   - 从扩展中提取 user_id
+   ↓
+4. services/auth_service.rs::delete_account() 处理业务逻辑
+   - 验证密码
+   - 调用 Repository 删除用户
+   ↓
+5. repositories/user_repository.rs::delete() 删除数据库记录
+   ↓
+6. 返回响应
+```
+
+---
+
+## 核心组件
+
+### AppState
+
+**职责**：应用全局状态
+
+**位置**：`src/main.rs`
+
+```rust
+#[derive(Clone)]
+pub struct AppState {
+    pub pool: db::DbPool,                        // 数据库连接池
+    pub config: config::app::AppConfig,          // 应用配置
+    pub redis_client: infra::redis::redis_client::RedisClient,  // Redis 客户端
+}
+```
+
+**用途**：
+- 通过 Axum State 机制注入到所有处理器
+- 提供数据库访问
+- 提供配置信息
+- 提供 Redis 访问
+
+### 路由配置
+
+**位置**：`src/main.rs`
+
+```rust
+// 公开路由
+let public_routes = Router::new()
+    .route("/health", get(handlers::health::health_check))
+    .route("/info", get(handlers::health::server_info))
+    .route("/auth/register", post(handlers::auth::register))
+    .route("/auth/login", post(handlers::auth::login))
+    .route("/auth/refresh", post(handlers::auth::refresh));
+
+// 受保护路由
+let protected_routes = Router::new()
+    .route("/auth/delete", post(handlers::auth::delete_account))
+    .route("//auth/delete-refresh-token", post(handlers::auth::delete_refresh_token))
+    .route_layer(axum::middleware::from_fn_with_state(
+        app_state.clone(),
+        infra::middleware::auth::auth_middleware,
+    ));
+
+// 合并所有路由
+let app = public_routes
+    .merge(protected_routes)
+    .layer(
+        CorsLayer::new()
+            .allow_origin(Any)
+            .allow_methods(Any)
+            .allow_headers(Any),
+    )
+    .layer(axum::middleware::from_fn(
+        infra::middleware::logging::logging_middleware,
+    ));
+```
+
+---
+
+## 相关文档
+
+- [DDD 架构规范](ddd-architecture.md) - DDD 设计原则和最佳实践
+- [代码风格规范](code-style.md) - Rust 代码风格和命名规范
+- [快速开始指南](getting-started.md) - 安装和运行项目
+
+---
+
+**提示**：遵循 DDD 分层架构可以提高代码质量和可维护性。