python-test
/
fastapi-demo
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
fastapi-demo/CLAUDE.md

9.3 KiB
Raw Blame History

CLAUDE.md

此文件为 Claude Code (claude.ai/code) 在此代码库中工作时提供指导。

常用命令

运行应用程序

# 安装依赖
pip install -r requirements.txt
pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/

# 安装数据库驱动
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、关闭热重载、严格安全设置

配置管理

# 复制环境配置模板
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         - 测试环境配置示例

数据库设置

# 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

# 访问交互式 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 中注册新的路由器，设置适当的前缀和标签