616 lines
17 KiB
Markdown
616 lines
17 KiB
Markdown
# 项目结构详解
|
||
|
||
本文档详细说明 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 分层架构可以提高代码质量和可维护性。
|