3f4165fe78
核心实现：搭建 Monorepo 架构，完成 shared 共享包、gateway、user-service 基础框架开发 技术落地：严格匹配指定技术栈版本，完成 Docker、gRPC、FastAPI、PostgreSQL、Redis 等配置，实现服务间基础连通 配套文件：生成 Makefile、环境变量模板、数据库 / 脚本初始化文件及启动验证文档 架构定位：仅搭建基础架构骨架，无任何业务逻辑、业务规则及业务相关字段，为后续业务开发提供支撑
192 lines
12 KiB
Markdown
192 lines
12 KiB
Markdown
# asset_helper_backend 微服务基础架构（V1）
|
||
|
||
请一次性完整生成 asset_helper_backend Monorepo 微服务后端项目，严格遵循以下所有要求，确保所有文件可直接编译运行、Docker Compose 本地一键启动，无任何报错，代码风格统一、类型完整，完全适配单人+AI（Trae）的开发模式；同时需支持本机无额外环境（仅需安装Docker和Docker Compose）即可启动，且包含清晰的启动验证步骤，方便我确认项目启动效果；**本项目为第一版基础架构开发，仅搭建架构骨架，不包含任何业务逻辑**。
|
||
|
||
## 一、严格锁定技术栈版本（一字不差，不可修改）
|
||
|
||
1. Gateway: FastAPI + WebSocket（唯一对外入口，负责HTTP请求转发和WebSocket实时通信，基于Starlette框架实现异步高并发通信，支持文本与二进制消息传输）
|
||
|
||
2. 微服务内部通信: FastAPI + gRPC（高性能跨服务通信，基于HTTP/2协议，支持双向流、头部压缩和多路复用，吞吐量优于传统REST API）
|
||
|
||
3. 数据库: PostgreSQL 18.3-alpine3.23（每个微服务独立DB实例，支持数据持久化和初始化脚本执行，配置健康检查确保服务可用性）
|
||
|
||
4. 缓存/消息: Redis 8.6.2-alpine（轻量级缓存，支持高并发访问，配置健康检查）
|
||
|
||
5. 容器化: Docker + Docker Compose（实现服务隔离与快速部署，区分本地开发和生产环境配置）
|
||
|
||
6. Python: 3.13.7-alpine3.22（轻量级基础镜像，体积小巧，适合容器化部署，支持异步I/O操作）
|
||
|
||
7. 依赖管理: pyproject.toml + uv（全局统一依赖管理，启用uv workspaces，整合所有子服务依赖）
|
||
|
||
8. 开发模式: 单人+AI（Trae），Monorepo架构，微服务独立部署、可扩展
|
||
|
||
## 二、严格遵循目录结构（一字不差，所有文件必须生成，无遗漏）
|
||
|
||
asset_helper_backend/
|
||
|
||
├── docker-compose.yml # 本地开发配置（不变，包含所有服务及健康检查）
|
||
|
||
├── docker-compose.prod.yml # 生产环境配置（不变，无挂载、配置重启策略）
|
||
|
||
├── .env.example # 环境变量模板（包含所有必要环境变量，可直接复制为.env使用）
|
||
|
||
├── Makefile # 单人+AI通用命令入口（实现所有核心命令，可直接执行）
|
||
|
||
├── .gitignore # 避免AI提交冲突（忽略.env、虚拟环境、编译文件等）
|
||
|
||
├── pyproject.toml # 全局Python依赖规范（启用uv workspaces，统一依赖版本）
|
||
|
||
├── scripts/ # 可直接执行脚本（权限配置为可执行，无需手动修改）
|
||
|
||
│ ├── init-db.sh # 初始化数据库，为每个微服务创建独立库、用户和权限
|
||
|
||
│ └── proto-gen.sh # 编译gRPC协议文件，输出到各服务指定目录
|
||
|
||
├── shared/ # 共享核心包（纯工具、无业务逻辑，可被所有服务依赖，贴合第一版基础架构定位）
|
||
|
||
│ ├── src/shared/
|
||
|
||
│ │ ├── models/ # Pydantic基模型和SQLAlchemy基类
|
||
|
||
│ │ ├── exceptions/ # 统一异常类和异常处理器
|
||
|
||
│ │ ├── middleware/ # 通用中间件（关联ID、日志、异常处理）
|
||
|
||
│ │ ├── utils/ # 工具类（配置加载、日志、安全、gRPC/Redis客户端）
|
||
|
||
│ │ └── proto/ # gRPC协议定义文件（先创建user.proto）
|
||
|
||
│ ├── pyproject.toml # 共享包依赖配置
|
||
|
||
│ └── Dockerfile # 共享包构建配置
|
||
|
||
├── services/ # 微服务目录（单人+AI开发，可无限新增）
|
||
|
||
│ ├── gateway/ # 对外入口：HTTP + WebSocket，仅搭建基础框架，无业务逻辑处理
|
||
|
||
│ │ ├── app/
|
||
|
||
│ │ │ ├── api/ # HTTP路由（转发到gRPC服务）
|
||
|
||
│ │ │ ├── ws/ # WebSocket处理（连接管理、消息处理）
|
||
|
||
│ │ │ ├── core/ # 配置、启动、依赖注入
|
||
|
||
│ │ │ └── main.py # FastAPI实例启动（包含HTTP和WebSocket）
|
||
|
||
│ │ ├── Dockerfile # 基于python:3.13.7-alpine3.22构建，启动uvicorn
|
||
|
||
│ │ └── requirements.txt # 网关服务依赖
|
||
|
||
│ └── user-service/ # 用户微服务：纯gRPC接口，无HTTP，仅搭建基础框架，无业务逻辑
|
||
|
||
│ ├── app/
|
||
|
||
│ │ ├── api/ # gRPC服务实现（对应proto定义的所有方法）
|
||
|
||
│ │ ├── core/ # 配置（继承shared.config）
|
||
|
||
│ │ ├── db/ # 异步SQLAlchemy会话和User模型
|
||
|
||
│ │ └── main.py # gRPC服务器启动
|
||
|
||
│ ├── Dockerfile # 基于python:3.13.7-alpine3.22构建，启动gRPC服务
|
||
|
||
│ └── requirements.txt # 用户服务依赖
|
||
|
||
└── infra/ # 基础设施（不变，包含数据库、缓存、反向代理配置）
|
||
|
||
├── postgres/ # PostgreSQL相关配置（数据持久化、初始化）
|
||
|
||
├── redis/ # Redis相关配置（数据持久化）
|
||
|
||
└── nginx/ # Nginx反向代理配置
|
||
|
||
## 三、核心文件具体要求（必须完全实现，不可省略）
|
||
|
||
### 1. 根目录文件
|
||
|
||
（1）pyproject.toml：指定Python 3.13.7，全局依赖包含fastapi、uvicorn、grpcio、grpcio-tools、pydantic、sqlalchemy、asyncpg、redis、python-dotenv、loguru；开发依赖包含ruff、pytest、pytest-asyncio、pre-commit；启用uv workspaces，包含shared/、services/gateway/、services/user-service/。
|
||
|
||
（2）Makefile：必须实现all、build、up、down、logs、proto-gen、init-db、test、lint命令，命令可直接执行，无需手动修改。
|
||
|
||
（3）.gitignore：忽略.env、__pycache__、.venv、*.pyc、dist/、build/、*.log、docker-compose.override.yml。
|
||
|
||
（4）scripts/proto-gen.sh：自动编译shared/src/shared/proto/**/*.proto文件，输出到各服务的app/grpc_generated/目录，添加可执行权限，可直接运行。
|
||
|
||
（5）scripts/init-db.sh：为每个微服务创建独立PostgreSQL库、用户、权限，添加可执行权限，可直接运行，支持数据库初始化脚本执行。
|
||
|
||
（6）.env.example：包含ENV、DEBUG、POSTGRES_USER、POSTGRES_PASSWORD、REDIS_URL、GRPC_PORT、HTTP_PORT等必要环境变量，标注默认值。
|
||
|
||
### 2. shared共享包
|
||
|
||
（1）shared/pyproject.toml：名称为asset_helper_shared，依赖包含fastapi、pydantic、grpcio、sqlalchemy、asyncpg、redis、loguru。
|
||
|
||
（2）shared.models：实现BaseModel（Pydantic基类）、BaseDBModel（SQLAlchemy基类，含id、created_at、updated_at字段）。
|
||
|
||
（3）shared.exceptions：实现AppException（基类），以及NotFoundError、UnauthorizedError、ForbiddenError、BadRequestError、InternalError等具体异常，同时实现全局异常处理器（可被gateway直接使用）。
|
||
|
||
（4）shared.middleware：实现CorrelationIdMiddleware、LoggingMiddleware、ExceptionMiddleware，适配FastAPI异步请求流程。
|
||
|
||
（5）shared.utils：实现config.py（Pydantic Settings加载环境变量）、logger.py（loguru全局日志配置）、security.py（JWT生成与验证、密码哈希）、grpc_client.py（gRPC客户端基类，支持服务调用）、redis_client.py（Redis连接池配置，支持异步操作）。
|
||
|
||
（6）shared/proto/user.proto：定义UserService服务，包含GetUser、CreateUser、UpdateUser、DeleteUser、ListUsers五个接口，指定proto3版本，定义请求和响应消息结构，字段编号合理分配；仅定义基础接口模板，不包含任何业务规则和业务字段设计，贴合基础架构定位。
|
||
|
||
### 3. user-service（纯gRPC微服务）
|
||
|
||
（1）技术与端口：Python 3.13.7-alpine3.22，gRPC服务监听0.0.0.0:50051，独立PostgreSQL库为user_db。
|
||
|
||
（2）目录实现：app/main.py启动gRPC服务器；app/core/config.py继承shared.config；app/db/session.py实现异步SQLAlchemy会话；app/db/models.py实现User模型（继承shared.models.BaseDBModel），仅包含基础字段，无业务相关字段；app/api/user_service.py实现UserService所有gRPC方法（仅模拟基础数据库CRUD操作，无任何业务逻辑和业务规则）；app/grpc_generated/目录用于存放自动生成的gRPC代码。
|
||
|
||
（3）Dockerfile：基于python:3.13.7-alpine3.22，安装依赖、复制代码、启动gRPC服务，配置健康检查。
|
||
|
||
### 4. gateway（对外入口）
|
||
|
||
（1）技术与端口：FastAPI + WebSocket，HTTP服务监听0.0.0.0:8000，WebSocket端点为/ws，内部调用user-service:50051的gRPC服务。
|
||
|
||
（2）目录实现：app/main.py创建FastAPI实例，集成HTTP和WebSocket；app/core/config.py配置服务参数；app/api/v1/users.py实现用户HTTP CRUD路由（仅负责转发到gRPC服务，无任何业务逻辑处理）；app/ws/manager.py实现WebSocket连接管理器（支持多连接管理）；app/ws/handlers.py实现用户消息处理（支持文本和二进制消息，无业务相关消息处理逻辑）；app/dependencies.py实现gRPC客户端注入。
|
||
|
||
（3）Dockerfile：基于python:3.13.7-alpine3.22，安装依赖、复制代码、启动uvicorn（支持WebSocket），配置健康检查。
|
||
|
||
### 5. Docker Compose配置
|
||
|
||
（1）docker-compose.yml（本地）：包含postgres（18.3-alpine3.23）、redis（8.6.2-alpine）、user-service、gateway四个服务；所有服务加入asset_helper_net网络；配置服务依赖健康检查（postgres使用pg_isready检查，redis使用redis-cli ping检查）；环境变量从.env读取；配置数据持久化卷；无需本机安装Python、PostgreSQL、Redis等依赖，仅需Docker和Docker Compose即可启动；新增启动前置说明（告知需先安装Docker和Docker Compose，以及复制.env.example为.env的步骤）。
|
||
|
||
（2）docker-compose.prod.yml（生产）：无本地文件挂载；配置服务重启策略为always；仅暴露gateway:8000端口，其他服务不对外暴露端口；强化安全配置，移除开发环境冗余参数。
|
||
|
||
## 四、最终交付要求（必须满足，否则需重新调整）
|
||
|
||
1. 所有技术栈版本严格匹配，无任何版本偏差；
|
||
|
||
2. 目录结构与要求完全一致，无遗漏、无多余文件；
|
||
|
||
3. 执行make proto-gen可正常生成gRPC代码，无编译错误；
|
||
|
||
4. 执行make init-db可正常初始化所有微服务的独立数据库；
|
||
|
||
5. 执行make up可一键启动所有容器，所有服务健康运行，无报错；
|
||
|
||
6. 访问gateway:8000/docs可正常打开Swagger文档，查看HTTP接口；
|
||
|
||
7. gateway的WebSocket端点/ws可正常连接，支持消息收发；
|
||
|
||
8. user-service的gRPC端口50051可正常连通，gateway能正常调用其gRPC接口；
|
||
|
||
9. shared共享包可被所有服务正常导入，无导入错误；
|
||
|
||
10. 代码类型标注完整，符合Python规范，无语法错误、无冗余代码；
|
||
|
||
11. 所有脚本可直接执行，无需手动修改权限或配置；
|
||
|
||
12. 项目支持后续新增微服务，扩展灵活，不影响现有服务运行；
|
||
|
||
13. 本机无Python、PostgreSQL、Redis等环境也可正常启动，仅需安装Docker和Docker Compose，Trae需在项目根目录生成清晰的「本地启动&验证步骤文档」（命名为STARTUP_VERIFY.md）；
|
||
|
||
14. STARTUP_VERIFY.md需包含：Docker和Docker Compose安装指引（极简版）、复制.env.example为.env的操作步骤、执行make up启动服务的命令、服务启动后验证步骤（含Swagger访问、WebSocket连接、gRPC连通性的具体操作和预期结果）、常见启动报错排查方法；
|
||
|
||
15. 启动验证步骤需简单易懂，无需专业技术背景，可直接按步骤操作确认项目启动效果，确保每一步验证都有明确的操作命令和预期反馈；
|
||
|
||
16. 全程严格遵循“第一版基础架构”定位，所有代码仅包含架构层、工具层实现，不涉及任何业务逻辑、业务规则、业务字段，不添加任何与具体业务相关的代码或配置；
|
||
|
||
17. user-service的User模型仅包含基础通用字段（如id、created_at、updated_at、username、password_hash），不添加任何业务相关字段（如角色、权限、业务关联信息等），gRPC方法仅实现基础CRUD，无业务逻辑判断。
|
||
> （注：文档部分内容可能由 AI 生成） |