86 lines
2.7 KiB
Markdown
86 lines
2.7 KiB
Markdown
|
# CODEBUDDY.md
|
|||
|
|
|
|||
|
|
此文件为 CodeBuddy Code 在此代码库中工作时提供指导。
|
|||
|
|
|
|||
|
|
## 常用命令
|
|||
|
|
|
|||
|
|
### 应用启动
|
|||
|
|
```bash
|
|||
|
|
# 安装依赖
|
|||
|
|
pip install -r requirements.txt
|
|||
|
|
|
|||
|
|
# 使用便捷启动脚本（推荐）
|
|||
|
|
python start.py --env dev # 开发环境
|
|||
|
|
python start.py --env prod # 生产环境
|
|||
|
|
python start.py --port 9000 # 指定端口
|
|||
|
|
|
|||
|
|
# 直接运行主文件
|
|||
|
|
python main.py
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 环境配置
|
|||
|
|
```bash
|
|||
|
|
# 环境变量优先级（从高到低）：
|
|||
|
|
# 1. 环境变量
|
|||
|
|
# 2. .env.{environment} 文件
|
|||
|
|
# 3. .env 基础配置文件
|
|||
|
|
# 4. 代码中的默认值
|
|||
|
|
|
|||
|
|
# 配置验证
|
|||
|
|
python -c "from app.core.config import settings; print(f'Environment: {settings.ENVIRONMENT}'); print(f'Debug: {settings.DEBUG}')"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 架构设计
|
|||
|
|
|
|||
|
|
### 应用工厂模式
|
|||
|
|
项目采用应用工厂模式，核心文件：
|
|||
|
|
- **应用创建**：`app/core/application.py` - 使用 `create_application()` 工厂函数
|
|||
|
|
- **配置管理**：`app/core/config.py` - 基于 pydantic-settings 的多环境配置
|
|||
|
|
- **路由聚合**：`app/api/v1/router.py` - 集中管理 API 路由注册
|
|||
|
|
|
|||
|
|
### 分层架构
|
|||
|
|
1. **API层** (`app/api/v1/endpoints/`) - FastAPI 路由端点，处理 HTTP 请求/响应
|
|||
|
|
2. **服务层** (`app/services/`) - 业务逻辑封装，使用单例服务实例
|
|||
|
|
3. **模型层** (`app/models/`) - 核心领域模型，Pydantic BaseModel
|
|||
|
|
4. **Schema层** (`app/schemas/`) - 请求/响应验证和序列化
|
|||
|
|
|
|||
|
|
### 路由结构
|
|||
|
|
- 所有 API 以 `/api/v1/` 为前缀
|
|||
|
|
- 路由通过 `app/api/v1/router.py` 统一注册
|
|||
|
|
- 每个资源对应一个独立的路由器文件
|
|||
|
|
|
|||
|
|
### 配置管理
|
|||
|
|
- 支持多环境：development、testing、production
|
|||
|
|
- 自动加载对应配置文件：`.env.dev.{env}`
|
|||
|
|
- 类型安全验证和转换
|
|||
|
|
- 便利属性：`settings.is_development`、`settings.is_production`
|
|||
|
|
|
|||
|
|
### 服务模式
|
|||
|
|
- 使用静态服务类 (`UserService`、`ProductService`)
|
|||
|
|
- 当前使用内存数据库进行演示
|
|||
|
|
- 服务层负责所有 CRUD 操作和业务规则
|
|||
|
|
|
|||
|
|
### 关键特性
|
|||
|
|
- CORS 中间件配置
|
|||
|
|
- 应用生命周期事件处理器
|
|||
|
|
- 模块化路由设计
|
|||
|
|
- 版本化的 API 结构
|
|||
|
|
|
|||
|
|
## 开发规范
|
|||
|
|
|
|||
|
|
### 添加新资源
|
|||
|
|
1. 模型层：在 `app/models/` 创建数据模型
|
|||
|
|
2. Schema层：在 `app/schemas/` 创建 Base/Create/Update/Response 模式
|
|||
|
|
3. 服务层：在 `app/services/` 创建服务类
|
|||
|
|
4. API层：在 `app/api/v1/endpoints/` 创建路由端点
|
|||
|
|
5. 路由注册：在 `app/api/v1/router.py` 注册新路由
|
|||
|
|
|
|||
|
|
### 配置扩展
|
|||
|
|
- 新配置项添加到 `app/core/config.py` 中的 Settings 类
|
|||
|
|
- 遵循现有配置验证模式
|
|||
|
|
- 支持环境变量覆盖
|
|||
|
|
|
|||
|
|
### 数据存储
|
|||
|
|
- 当前使用内存数据存储用于演示
|
|||
|
|
- 实际实现将在服务层集成数据库
|
|||
|
|
- 服务接口设计支持无缝替换存储后端
|