265 lines
10 KiB
Markdown
265 lines
10 KiB
Markdown
# CLAUDE.md
|
||
|
||
此文件为 Claude Code (claude.ai/code) 在此代码库中工作时提供指导。
|
||
|
||
## Conda 环境配置
|
||
|
||
### 环境管理
|
||
```bash
|
||
# 创建新的 conda 环境（Python 3.11）
|
||
conda create -n fastapi-demo python=3.11
|
||
|
||
# 激活 conda 环境
|
||
conda activate fastapi-demo
|
||
|
||
# 查看当前环境
|
||
conda info --envs
|
||
|
||
# 导出环境配置
|
||
conda env export > environment.yml
|
||
|
||
# 从配置文件创建环境
|
||
conda env create -f environment.yml
|
||
|
||
# 更新环境
|
||
conda env update -f environment.yml --prune
|
||
|
||
# 删除环境（如需重建）
|
||
conda deactivate
|
||
conda env remove -n fastapi-demo
|
||
```
|
||
|
||
## 常用命令
|
||
|
||
### 运行应用程序
|
||
```bash
|
||
# 激活 conda 环境（必须先执行）
|
||
conda activate fastapi-demo
|
||
|
||
# 安装依赖（在 conda 环境中）
|
||
pip install -r requirements.txt
|
||
pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/
|
||
|
||
# 使用 conda 安装常用包（可选，推荐用于科学计算包）
|
||
conda install -c conda-forge fastapi uvicorn sqlalchemy pymysql
|
||
|
||
# 安装数据库驱动
|
||
pip install sqlalchemy pymysql -i https://mirrors.aliyun.com/pypi/simple/
|
||
|
||
# 1. 直接运行（使用 .env 或默认配置）
|
||
python main.py
|
||
|
||
# 2. 指定环境运行（推荐）
|
||
ENVIRONMENT=development python main.py # 使用 .env.dev 配置
|
||
ENVIRONMENT=testing python main.py # 使用 .env.test 配置
|
||
ENVIRONMENT=production python main.py # 使用 .env.prod 配置
|
||
|
||
# 3. Windows 系统设置环境变量
|
||
set ENVIRONMENT=development && python main.py
|
||
set ENVIRONMENT=production && python main.py
|
||
|
||
# 4. 手动指定 uvicorn 参数（不推荐，应优先使用配置文件）
|
||
uvicorn main:app --host 0.0.0.0 --port 8000 --reload
|
||
|
||
# 5. 临时覆盖配置（环境变量优先级最高）
|
||
PORT=9000 HOST=127.0.0.1 python main.py
|
||
|
||
# 6. 使用便捷启动脚本（推荐）
|
||
python start.py --env dev # 开发环境
|
||
python start.py --env prod # 生产环境
|
||
python start.py --port 9000 # 指定端口
|
||
python start.py --env dev --reload # 开发环境+强制热重载
|
||
```
|
||
|
||
### 配置文件启动说明
|
||
应用会自动读取配置并使用对应的启动参数：
|
||
|
||
- **开发环境** (`.env.dev`)：自动启用热重载、调试模式、允许所有CORS
|
||
- **测试环境** (`.env.test`)：关闭API文档、严格CORS限制
|
||
- **生产环境** (`.env.prod`)：多worker、关闭热重载、严格安全设置
|
||
|
||
### 配置管理
|
||
```bash
|
||
# 复制环境配置模板
|
||
cp .env.example .env
|
||
# 编辑 .env 文件，修改数据库连接等配置
|
||
|
||
# 查看当前配置
|
||
python -c "from app.core.config import settings; print(f'Environment: {settings.ENVIRONMENT}'); print(f'Debug: {settings.DEBUG}')"
|
||
|
||
# 配置文件说明
|
||
# .env - 当前环境配置（不提交到 git）
|
||
# .env.example - 配置模板文件（提交到 git）
|
||
# .env.prod - 生产环境配置示例
|
||
# .env.test - 测试环境配置示例
|
||
```
|
||
|
||
### 数据库设置
|
||
```bash
|
||
# MySQL 数据库配置
|
||
# 1. 创建数据库
|
||
mysql -u root -p
|
||
CREATE DATABASE fast_demo CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
|
||
|
||
# 2. 配置数据库连接
|
||
# 复制配置模板并修改数据库连接信息
|
||
cp .env.example .env
|
||
# 编辑 .env 文件，修改以下配置：
|
||
# DB_HOST=localhost # 数据库主机
|
||
# DB_PORT=3306 # 数据库端口
|
||
# DB_USER=root # 数据库用户
|
||
# DB_PASSWORD=123456 # 数据库密码
|
||
# DB_NAME=fast_demo # 数据库名称
|
||
|
||
# 3. 应用启动时会自动创建表结构
|
||
# - users 表：用户信息
|
||
# - products 表：产品信息
|
||
```
|
||
|
||
### 测试 API
|
||
```bash
|
||
# 访问交互式 API 文档
|
||
# 在浏览器中打开 http://localhost:8000/docs (Swagger UI)
|
||
# 或 http://localhost:8000/redoc (ReDoc)
|
||
|
||
# 健康检查端点
|
||
curl http://localhost:8000/health
|
||
|
||
# API 端点示例
|
||
curl http://localhost:8000/api/v1/users/ # 获取用户列表
|
||
curl http://localhost:8000/api/v1/products/ # 获取产品列表
|
||
```
|
||
|
||
## 架构说明
|
||
|
||
### 项目结构模式
|
||
这个 FastAPI 演示项目采用分层架构和应用工厂模式，具有清晰的关注点分离：
|
||
|
||
```
|
||
fastapi-demo/
|
||
├── main.py # 应用入口
|
||
├── start.py # 启动脚本
|
||
├── requirements.txt # 依赖管理
|
||
├── alembic.ini # 数据库迁移配置
|
||
├── database_manager.py # 数据库管理工具
|
||
├── .env / .env.dev # 环境配置
|
||
├── app/
|
||
│ ├── __init__.py
|
||
│ ├── core/ # 核心配置
|
||
│ │ ├── application.py # 应用工厂
|
||
│ │ └── config.py # 配置管理
|
||
│ ├── api/ # API 路由层
|
||
│ │ └── v1/
|
||
│ │ ├── router.py # 路由聚合
|
||
│ │ └── endpoints/ # 具体端点
|
||
│ │ ├── users.py # 用户 API
|
||
│ │ └── products.py # 产品 API
|
||
│ ├── services/ # 业务逻辑层
|
||
│ │ ├── user_service.py # 用户服务
|
||
│ │ └── product_service.py # 产品服务
|
||
│ ├── schemas/ # Pydantic 模型
|
||
│ │ ├── user.py # 用户数据模式
|
||
│ │ └── product.py # 产品数据模式
|
||
│ ├── models/ # 数据模型
|
||
│ │ ├── user.py # 用户领域模型
|
||
│ │ └── product.py # 产品领域模型
|
||
│ └── database/ # 数据库配置
|
||
│ ├── connection.py # 数据库连接
|
||
│ ├── models.py # SQLAlchemy 模型
|
||
│ └── base.py # 数据库基类
|
||
├── alembic/ # 数据库迁移
|
||
├── sql/ # SQL 脚本
|
||
└── docs/ # 项目文档
|
||
```
|
||
|
||
#### 架构层次说明
|
||
|
||
- **应用工厂** (`app/core/application.py`)：使用工厂模式创建和配置应用实例，集中管理中间件、路由注册和事件处理器。
|
||
|
||
- **路由聚合** (`app/api/v1/router.py`)：集中管理 v1 版本的所有路由注册，保持主文件精简。
|
||
|
||
- **API 层** (`app/api/v1/endpoints/`)：处理 HTTP 请求和响应的 FastAPI 路由器。每个路由器对应一个资源（用户、产品）并定义 API 端点。
|
||
|
||
- **服务层** (`app/services/`)：使用服务类实现业务逻辑，通过 SQLAlchemy ORM 与 MySQL 数据库交互。服务处理 CRUD 操作和业务规则。
|
||
|
||
- **数据库层** (`app/database/`)：数据库连接配置和会话管理，使用 SQLAlchemy 连接 MySQL 数据库。
|
||
|
||
- **模式层** (`app/schemas/`)：用于请求/响应验证和序列化的 Pydantic 模型。为每个实体遵循 Base、Create、Update 和 Response 模型的模式。
|
||
|
||
- **模型层** (`app/models/`)：表示核心实体的领域模型。这些是配置了 `from_attributes = True` 的 Pydantic BaseModel，以兼容 ORM。
|
||
|
||
- **核心配置** (`app/core/config.py`)：使用 pydantic-settings 的集中式设置管理，支持多环境配置文件和环境变量覆盖。
|
||
|
||
#### 结构特点
|
||
|
||
✅ **符合主流标准**：
|
||
- 分层架构：清晰的 API → Services → Database 分层
|
||
- 关注点分离：schemas (数据验证) 与 models (实体) 分离
|
||
- 版本化路由：`/api/v1/` 结构便于版本管理
|
||
- 配置管理：多环境配置文件支持
|
||
- 数据库迁移：Alembic 集成
|
||
- 应用工厂模式：便于测试和部署
|
||
|
||
**与主流框架对比**：
|
||
- **Django REST Framework 相似**：
|
||
- `services/` ≈ `views.py` (业务逻辑)
|
||
- `schemas/` ≈ `serializers.py` (数据验证)
|
||
- `models/` ≈ `models.py` (数据模型)
|
||
- **Spring Boot 相似**：
|
||
- `core/application.py` ≈ Application 主类
|
||
- `api/endpoints/` ≈ Controller 层
|
||
- `services/` ≈ Service 层
|
||
|
||
### 关键架构决策
|
||
|
||
1. **应用工厂模式**：使用 `create_application()` 函数创建应用，便于测试和配置管理，支持多环境部署。
|
||
|
||
2. **路由模块化**：通过 `router.py` 集中管理路由注册，`main.py` 保持精简，只负责应用启动。
|
||
|
||
3. **版本化的 API 路由**：所有端点都以 `/api/v1/` 为前缀，便于 API 版本迭代和兼容性管理。
|
||
|
||
4. **服务模式**：使用单例服务实例（`user_service`、`product_service`）封装所有业务逻辑，保持路由器精简。
|
||
|
||
5. **模式分离**：为不同操作（Create、Update、Response）设置不同的模式，在 API 设计中提供灵活性，而不暴露内部模型细节。
|
||
|
||
6. **数据库存储**：项目已集成 MySQL 数据库，使用 SQLAlchemy ORM 进行数据持久化。支持自动创建表结构和数据迁移。
|
||
|
||
7. **CORS 中间件**：配置了宽松的设置（`allow_origins=["*"]`）适合开发环境。生产环境中应该限制。
|
||
|
||
8. **事件处理器**：在 `application.py` 中注册启动和关闭事件，便于管理应用生命周期（如数据库连接、缓存初始化等）。
|
||
|
||
### 配置管理详情
|
||
|
||
项目采用类似 Spring Boot 的分层配置管理：
|
||
|
||
1. **配置文件优先级**（从高到低）：
|
||
- 环境变量
|
||
- `.env.{environment}` （如 `.env.dev`, `.env.prod`）
|
||
- `.env` 基础配置文件
|
||
- 代码中的默认值
|
||
|
||
2. **多环境配置**：
|
||
- `.env` - 基础配置：默认使用 MySQL 数据库
|
||
- `.env.dev` - 开发环境：调试开启、允许所有CORS、使用 MySQL
|
||
- `.env.test` - 测试环境：关闭API文档、严格限流、测试数据库
|
||
- `.env.prod` - 生产环境：关闭调试、使用 PostgreSQL、启用监控
|
||
|
||
3. **配置特性**：
|
||
- 类型验证和转换
|
||
- 环境变量解析（如CORS_ORIGINS支持逗号分隔）
|
||
- 配置验证器（如环境名称校验）
|
||
- 便利属性（如 `settings.is_development`）
|
||
|
||
4. **敏感信息管理**：
|
||
- 密钥、密码等敏感信息通过环境变量管理
|
||
- `.env` 文件已添加到 `.gitignore`
|
||
- 提供 `.env.example` 作为配置模板
|
||
|
||
### 添加新功能
|
||
|
||
添加新资源/实体时：
|
||
1. 在 `app/models/` 中创建模型
|
||
2. 在 `app/schemas/` 中创建模式（Base、Create、Update、Response）
|
||
3. 在 `app/services/` 中创建包含 CRUD 操作的服务类
|
||
4. 在 `app/api/v1/endpoints/` 中创建包含端点的路由器
|
||
5. 在 `app/api/v1/router.py` 中注册新的路由器，设置适当的前缀和标签 |