用户服务 4 个 crate 合并为单一 user-service，按 DDD 限界上下文聚合

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-04-26 16:36:04 +08:00
parent 4e004f5a85
commit b5cb9daad7
28 changed files with 489 additions and 1038 deletions
--- a/backend/CLAUDE.md
+++ b/backend/CLAUDE.md
@@ -4,7 +4,7 @@

 ## 项目概述

-这是一个基于 **Rust** 的微服务后端项目，采用 **Axum + Tokio** 技术栈，使用 **Nginx** 作为 API 网关，**PostgreSQL** 作为数据库，**Redis** 作为缓存。服务以 Docker 容器形式部署，每个核心功能拆分为独立的微服务二进制文件。
+这是一个基于 **Rust** 的微服务后端项目，采用 **Axum + Tokio** 技术栈，使用 **Nginx** 作为 API 网关，**PostgreSQL** 作为数据库，**Redis** 作为缓存。服务以 Docker 容器形式部署，按 **DDD 限界上下文（Bounded Context）** 划分服务边界——一个领域对外是一个微服务，内部由 Rust 模块组织。

 ## 技术栈

@@ -23,13 +23,24 @@
 ```
 backend/
 ├── services/                  # 微服务目录
-│   └── user-service/          # 用户服务（当前唯一实现的服务域）
-│       ├── user-login-account/     # 账号登录服务 (port 8001)
-│       ├── user-register-account/  # 账号注册服务 (port 8002)
-│       ├── user-login-email/       # 邮箱登录服务 (port 8003)
-│       ├── user-register-email/    # 邮箱注册服务 (port 8004)
-│       ├── migrations/             # 数据库初始化 SQL
-│       └── Dockerfile              # 通用/遗留构建文件
+│   └── user-service/          # 用户服务（DDD 用户限界上下文，单一服务对外）
+│       ├── Cargo.toml         # 单 crate
+│       ├── Dockerfile         # 单镜像
+│       ├── migrations/        # 数据库初始化 SQL
+│       │   └── 001_init.sql
+│       └── src/
+│           ├── main.rs        # 装配 Router、连接池、AppState
+│           ├── state.rs       # AppState { db, jwt_secret }
+│           ├── api.rs         # 通用 ApiRequest<T> / ApiResponse<T>
+│           ├── jwt.rs         # JWT Claims + generate_token
+│           ├── auth/          # 认证模块
+│           │   ├── mod.rs
+│           │   ├── login_account.rs
+│           │   └── login_email.rs
+│           └── register/      # 注册模块
+│               ├── mod.rs
+│               ├── account.rs
+│               └── email.rs
 ├── gateway/                   # API 网关
 │   ├── Dockerfile
 │   └── nginx/
@@ -51,13 +62,21 @@ backend/

 ### 服务拆分原则

-每个用户功能（登录/注册）按**认证方式**拆分为独立服务：
- `user-login-account`: 账号密码登录，签发 JWT
- `user-login-email`: 邮箱密码登录，签发 JWT
- `user-register-account`: 账号注册，写入 `user_main` / `user_login_account` / `user_login_password`
- `user-register-email`: 邮箱注册，写入 `user_main` / `user_login_email` / `user_login_password`
+按 **DDD 限界上下文（Bounded Context）** 划分：每个独立的业务域对外暴露为单一微服务，内部细分通过 Rust 模块和 axum Router 组合实现，**不再按操作粒度（登录/注册）拆 crate**。

-每个服务都是独立的 Rust Crate，拥有独立的 `Cargo.toml`、`src/main.rs` 和 `Dockerfile`。
+**user-service**（用户域，单一服务）对外提供：
+
+| 方法 | 网关路径 | 下游路径 | 用途 |
+|------|---------|---------|------|
+| POST | `/api/v1/auth/login/account`     | `/auth/login/account`     | 账号密码登录，签发 JWT |
+| POST | `/api/v1/auth/login/email`       | `/auth/login/email`       | 邮箱密码登录，签发 JWT |
+| POST | `/api/v1/users/register/account` | `/users/register/account` | 账号注册（写 user_main / user_login_account / user_login_password） |
+| POST | `/api/v1/users/register/email`   | `/users/register/email`   | 邮箱注册（写 user_main / user_login_email / user_login_password） |
+| GET  | `/health`                        | `/health`                 | 健康检查 |
+
+> 网关 nginx 通过 `rewrite ^/api/v1(/.*)$ $1 break;` 统一去除 `/api/v1` 前缀。
+
+服务内部模块化布局见 [项目结构](#项目结构)：`auth/` 子模块负责登录认证，`register/` 子模块负责账号注册，共享 `state.rs` / `api.rs` / `jwt.rs`。

 ### 数据库模型

@@ -157,7 +176,7 @@ OK
 - 使用 **Rust 2024 Edition**。
 - 注释使用**中文**。
 - 服务状态通过 `Arc<AppState>` 注入到 Axum Handler 中。
- 注册类服务统一使用包装请求/响应格式：
+- 注册类接口统一使用包装请求/响应格式：
  ```rust
  struct ApiRequest<T> { device: i32, language: i32, data: T }
  struct ApiResponse<T> { success: bool, message: String, data: Option<T> }
@@ -220,8 +239,8 @@ docker compose up -d --build                              # 正式
 如需仅启动后端栈（不含前端）做联调：

 ```bash
-docker compose -f docker-compose.dev.yml up -d --build user-db user-redis \
-  user-login-account user-register-account user-login-email user-register-email gateway
+docker compose -f docker-compose.dev.yml up -d --build \
+  user-db user-redis user-service gateway
 ```

 ### 网关管理
@@ -239,25 +258,37 @@ docker compose -f docker-compose.dev.yml up -d --build user-db user-redis \
 ./scripts/gateway.sh reload
 ```

-### 本地编译单个服务
+### 本地编译运行 user-service
 ```bash
-cd services/user-service/user-login-account
+cd services/user-service
 cargo run
 ```

 ## 扩展指南

-### 新增微服务
+### 在已有领域内新增功能（推荐）

-1. 在 `services/<service-domain>/` 下创建新目录，如 `services/order-service/order-create/`。
-2. 编写独立的 `Cargo.toml`、`src/main.rs`、`Dockerfile`。
-3. 在 `gateway/nginx/conf.d/services/` 添加路由配置。
-4. 在 `gateway/nginx/nginx.conf` 添加 `upstream`。
-5. 如需新数据库表，在对应服务域的 `migrations/` 目录添加 SQL 文件。
+属于同一限界上下文（如新增"用户资料修改"接口）时，**不要**新建 crate 或服务，而是在现有 `user-service` 下新增模块：
+
+1. 在 `services/user-service/src/` 下新增模块文件，或扩展现有 `auth/` / `register/` 子模块。
+2. 在子模块的 `mod.rs` 中通过 `Router::new().route(...)` 注册新路由。
+3. 在 `gateway/nginx/conf.d/services/user-service.conf` 中追加对应 `location` 块（路径仍以 `/api/v1/...` 起始）。
+4. 如需新数据库表或字段，在 `services/user-service/migrations/` 下追加 SQL 文件。
+
+### 新增服务域（新限界上下文）
+
+当业务边界明显独立（如订单 `order-service`、支付 `payment-service`）时再新建独立服务：
+
+1. 在 `services/<service-domain>/` 下创建独立 crate（参考 `services/user-service/` 的目录布局：单 `Cargo.toml` + 单 `Dockerfile` + 模块化的 `src/`）。
+2. 在 `gateway/nginx/conf.d/services/` 添加路由配置文件。
+3. 在 `gateway/nginx/nginx.conf` 添加对应 `upstream`。
+4. 在根目录 `docker-compose.yml` / `docker-compose.dev.yml` 中追加服务定义。
+5. 在 [PORT_ALLOCATION.md](PORT_ALLOCATION.md) 申请新的百位段端口并更新分配表。

 ### 共享代码提取

-当前 `shared/` 目录为空。当多个服务需要共用模型、中间件或工具函数时：
+当前 `shared/` 目录为空。当多个服务域需要共用模型、中间件或工具函数时：
+
 1. 在 `shared/` 下创建子模块（如 `shared/models`、`shared/middleware`）。
 2. 将共享 crate 以 path dependency 引入各微服务：
   ```toml
@@ -268,6 +299,5 @@ cargo run

 ## 注意事项

- `services/user-service/Dockerfile` 是一个通用构建文件，但当前各微服务使用自己的 Dockerfile。修改时请确认影响范围。
- 当前 `shared/` 为空，Agent 在修改代码时若发现重复逻辑，可提议提取到 `shared/`。
+- 当前 `shared/` 为空，Agent 在修改代码时若发现跨服务域重复逻辑，可提议提取到 `shared/`；同一服务内部的重复逻辑直接抽到模块即可，无需走 `shared/`。
 - 网关配置文件中的 `api.example.com` 为占位域名，本地开发需配置 hosts 或使用 `localhost`。