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

2.7 KiB
Raw Permalink Blame History

CODEBUDDY.md

此文件为 CodeBuddy Code 在此代码库中工作时提供指导。

常用命令

应用启动

# 安装依赖
pip install -r requirements.txt

# 使用便捷启动脚本（推荐）
python start.py --env dev          # 开发环境
python start.py --env prod         # 生产环境
python start.py --port 9000        # 指定端口

# 直接运行主文件
python main.py

环境配置

# 环境变量优先级（从高到低）：
# 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 类
  • 遵循现有配置验证模式
  • 支持环境变量覆盖

数据存储

  • 当前使用内存数据存储用于演示
  • 实际实现将在服务层集成数据库
  • 服务接口设计支持无缝替换存储后端