FastAPI-Easy 开发指南¶
本文档说明项目结构、开发计划和待办事项。
许可证: 本项目采用 AGPL-3.0 许可证。详见 LICENSE 文件。
- ✅ 可用于非商业用途
- ❌ 商业用途需要获得明确许可
- 📝 修改代码必须共享
- 📦 使用本项目的软件也必须开源
📁 项目结构分析¶
✅ 当前结构的合理之处¶
- 清晰的模块划分 - core/、backends/、operations/、utils/ 职责分离
- 可扩展的架构 - 易于添加新 ORM、新操作、新工具
- 测试友好的设计 - 依赖注入、接口抽象、易于 mock
⚠️ 需要改进的地方¶
- 缺少类型定义 - 需要添加
types.py定义类型别名和协议 - 缺少验证器 -
utils/validators.py需要实现字段级验证 - 缺少响应格式化器 - 需要添加
formatters.py支持自定义响应格式 - 缺少中间件 - 需要添加
middleware/目录支持错误处理、日志、监控
改进后的项目结构¶
fastapi-easy/
│
├── README.md # 项目主入口
│
├── docs/ # 📚 文档目录
│ ├── README.md # 文档中心
│ ├── DEVELOPMENT.md # 本文件（开发指南）
│ │
│ └── usage/ # 使用指南
│ ├── INDEX.md # 使用指南完整索引
│ ├── README.md # 使用指南导航
│ │
│ ├── 01-quick-start.md # 快速开始（5 分钟）
│ ├── 02-databases.md # 支持的数据库（20 分钟）
│ ├── 03-data-flow.md # 完整流程（15 分钟）
│ ├── 04-filters.md # 搜索和过滤（10 分钟）
│ ├── 05-sorting.md # 排序功能（10 分钟）
│ ├── 06-complete-example.md # 完整示例（20 分钟）
│ ├── 07-architecture.md # 架构设计⭐（30 分钟）
│ ├── 09-error-handling.md # 错误处理（10 分钟）
│ ├── 10-soft-delete.md # 软删除（15 分钟）
│ ├── 11-batch-operations.md # 批量操作（15 分钟）
│ ├── 12-permissions.md # 权限控制（20 分钟）
│ ├── 13-audit-logging.md # 审计日志（15 分钟）
│ ├── 14-configuration.md # 配置管理（15 分钟）
│ ├── 15-testing.md # 测试指南（20 分钟）
│ ├── 16-best-practices.md # 最佳实践（20 分钟）
│ └── 17-troubleshooting.md # 故障排查（15 分钟）
│
├── src/ # 💻 源代码目录（待创建）
│ └── fastapi_easy/
│ ├── __init__.py
│ ├── core/
│ │ ├── crud_router.py # CRUDRouter 主类
│ │ ├── operations.py # 操作系统
│ │ ├── adapters.py # ORM 适配器
│ │ ├── hooks.py # 钩子系统
│ │ ├── errors.py # 错误处理
│ │ └── config.py # 配置系统
│ │
│ ├── backends/ # ORM 后端
│ │ ├── __init__.py
│ │ ├── base.py # 基础适配器
│ │ ├── sqlalchemy.py # SQLAlchemy 适配器
│ │ ├── tortoise.py # Tortoise 适配器
│ │ ├── mongo.py # MongoDB 适配器
│ │ └── sqlmodel.py # SQLModel 适配器
│ │
│ ├── operations/ # 内置操作
│ │ ├── __init__.py
│ │ ├── get_all.py
│ │ ├── get_one.py
│ │ ├── create.py
│ │ ├── update.py
│ │ ├── delete_one.py
│ │ └── delete_all.py
│ │
│ └── utils/ # 工具函数
│ ├── __init__.py
│ ├── validators.py # 验证器
│ ├── filters.py # 过滤器
│ ├── sorters.py # 排序器
│ └── pagination.py # 分页
│
├── tests/ # 🧪 测试目录（待创建）
│ ├── __init__.py
│ ├── conftest.py
│ ├── test_crud_router.py
│ ├── test_operations.py
│ ├── test_backends/
│ │ ├── test_sqlalchemy.py
│ │ ├── test_tortoise.py
│ │ └── ...
│ ├── test_hooks.py
│ ├── test_errors.py
│ └── test_integration.py
│
├── examples/ # 📖 示例项目（待创建）
│ ├── basic/
│ │ └── main.py # 基础示例
│ ├── auth/
│ │ └── main.py # 鉴权示例
│ ├── ecommerce/
│ │ └── main.py # 电商示例
│ └── ...
│
├── references/ # 📚 参考资料
│ ├── fastapi-crudrouter/ # 原项目参考
│ └── dfs-generate/ # 其他项目参考
│
├── LICENSE # AGPL-3.0 许可证
├── setup.py # 项目配置
├── requirements.txt # 依赖列表
├── pyproject.toml # Python 项目配置
└── .gitignore # Git 忽略文件
🧪 测试框架设计¶
测试隔离策略¶
1. 单元测试隔离（无外部依赖）¶
test_core/: 核心模块测试（config、errors、hooks、operations）test_utils/: 工具函数测试（pagination、filters、sorters）- 使用 mock 和 patch 隔离依赖
2. 集成测试隔离（使用真实数据库）¶
test_sqlalchemy/: SQLAlchemy 适配器集成测试test_tortoise/: Tortoise ORM 集成测试- 使用内存数据库（SQLite）和事务回滚隔离
3. 端到端测试隔离（完整 API 流程）¶
test_end_to_end/: 完整 API 流程测试- 测试完整的请求-响应周期
测试隔离技术¶
Fixture 隔离
@pytest.fixture
def mock_adapter():
adapter = AsyncMock(spec=ORMAdapter)
return adapter
@pytest.fixture
async def db_session():
# 使用内存数据库
engine = create_async_engine("sqlite+aiosqlite:///:memory:")
# 创建表、返回 session、清理
事务隔离 - 每个测试在事务中运行 - 测试完成后自动回滚 - 确保测试间数据隔离
测试覆盖目标¶
| 模块 | 目标覆盖率 | 优先级 |
|---|---|---|
| core/ | 95% | P0 |
| utils/ | 90% | P0 |
| backends/ | 85% | P1 |
| operations/ | 90% | P1 |
同步开发策略¶
每个功能的开发步骤： 1. 编写单元测试（测试失败） 2. 实现功能（测试通过） 3. 编写集成测试 4. 代码审查 5. 提交代码
🎯 项目阶段¶
第 1 阶段：核心框架 ✅ 完成¶
- ✅ 项目定位和架构设计
- ✅ 完整的使用指南（20 份文档）
- ✅ 架构文档
- ✅ 源代码实现（16 个核心文件）
第 2 阶段：基础功能和测试 ✅ 完成¶
- ✅ CRUDRouter 核心类
- ✅ 操作系统（Operation System）
- ✅ 内置 CRUD 操作（6 个）
- ✅ 钩子系统
- ✅ 错误处理系统
- ✅ 单元测试框架
- ✅ 项目配置（setup.py、requirements.txt）
第 3 阶段：ORM 适配器 ✅ 完成¶
- ✅ SQLAlchemy 异步适配器
- ✅ Tortoise ORM 适配器
- ✅ 集成测试
- ✅ 性能基准测试
- ✅ 完整文档示例
第 4 阶段：高级功能 ✅ 完成¶
- ✅ 搜索和过滤
- ✅ 排序功能
- ✅ 软删除
- ✅ 批量操作
- ✅ 权限控制
- ✅ 审计日志
- ✅ 缓存支持
- ✅ 速率限制
第 5 阶段：扩展功能 ✅ 完成¶
- ✅ GraphQL 支持
- ✅ WebSocket 支持
- ✅ CLI 工具
- ✅ 响应格式化器
- ✅ 输入验证
- ✅ 中间件系统
第 6 阶段：文档和测试 🔄 进行中¶
- ✅ 完整的使用文档（20 份）
- ✅ 架构设计文档
- ✅ 开发指南
- 🔄 测试覆盖率优化（当前 94%）
- ⏳ 更多集成测试
- ⏳ 性能优化
第 7 阶段：发布和推广 ⏳ 待开始¶
- PyPI 发布
- 示例项目完善
- 社区反馈收集
📋 待办事项（TODO）¶
优先级 P0（必做）¶
Phase 1: 核心架构 ✅ 已完成¶
- CRUDRouter 主类
- Operation 基类和 OperationRegistry
- ORMAdapter 基类
- HookRegistry 和钩子系统
- AppError 和错误处理
- CRUDConfig 配置系统
- 工具函数（pagination、filters、sorters）
Phase 2: 基础功能和测试 ✅ 已完成¶
测试框架 ✅
- [x] 创建 tests/conftest.py
- [x] 全局 fixture 定义
- [x] Mock adapter fixture
- [x] 配置 fixture
- 创建
tests/unit/test_core/ - test_config.py - 配置测试 (10 个测试)
- test_errors.py - 错误处理测试 (16 个测试)
- test_hooks.py - 钩子系统测试 (18 个测试)
-
test_operations.py - 操作系统测试 (9 个测试)
-
创建
tests/unit/test_utils/ - test_pagination.py - 分页测试 (12 个测试)
- test_filters.py - 过滤器测试 (16 个测试)
- test_sorters.py - 排序器测试 (15 个测试)
内置操作 ✅
- [x] 创建 src/fastapi_easy/operations/
- [x] GetAll 操作
- [x] GetOne 操作
- [x] Create 操作
- [x] Update 操作
- [x] DeleteOne 操作
- [x] DeleteAll 操作
项目配置 ✅ - [x] setup.py - 项目安装配置 - requirements.txt - 依赖列表 - 所有 90 个单元测试通过
优先级 P1（重要）✅ 已完成¶
高级功能 ✅¶
- 软删除支持 -
src/fastapi_easy/core/soft_delete.py - 批量操作 -
src/fastapi_easy/core/bulk_operations.py - 权限控制集成 -
src/fastapi_easy/core/permissions.py - 审计日志 -
src/fastapi_easy/core/audit_log.py
测试 ✅¶
- 单元测试框架设置 -
tests/unit/ - 核心功能测试 -
tests/unit/test_core/ - ORM 适配器测试 -
tests/integration/ - 集成测试 -
tests/e2e/
文档 ✅¶
- API 文档 - 20 份详细文档
- 开发者指南 -
docs/DEVELOPMENT.md - 贡献指南 - 本文件中的贡献指南部分
优先级 P2（可选）✅ 已完成¶
扩展功能 ✅¶
- 缓存支持 -
src/fastapi_easy/core/cache.py - 速率限制 -
src/fastapi_easy/core/rate_limit.py - GraphQL 支持 -
src/fastapi_easy/graphql.py - WebSocket 支持 -
src/fastapi_easy/websocket.py
工具 ✅¶
- CLI 工具 -
src/fastapi_easy/cli.py - 代码生成器 - CLI 中集成
- 数据库迁移工具 - 计划中
示例 ✅¶
- 基础示例 -
examples/simple_example.py - 鉴权示例 -
examples/sqlmodel_example.py - 电商示例 - 文档中的完整示例
- 微服务示例 - 计划中
开发工作流¶
1. 环境设置¶
# 克隆项目
git clone https://github.com/your-repo/fastapi-easy.git
cd fastapi-easy
# 创建虚拟环境
python -m venv venv
source venv/bin/activate # Linux/Mac
# 或
venv\Scripts\activate # Windows
# 安装开发依赖
pip install -e ".[dev]"
pip install pytest pytest-asyncio pytest-cov black flake8 mypy
2. 代码风格¶
- 使用 Black 格式化代码
- 使用 Flake8 检查代码质量
- 使用 MyPy 进行类型检查
- 遵循 PEP 8 规范
3. 测试¶
# 运行所有测试
pytest
# 运行特定测试
pytest tests/test_crud_router.py
# 生成覆盖率报告
pytest --cov=fastapi_easy tests/
4. 提交代码¶
# 格式化代码
black src/ tests/
# 检查代码质量
flake8 src/ tests/
mypy src/
# 运行测试
pytest
# 提交
git add .
git commit -m "feat: add feature description"
git push
开发进度¶
当前状态¶
- 📚 文档: 100% 完成（20 份详细文档）
- 💻 代码: 90% 完成（Phase 1-5 完成）
- 🧪 测试: 94% 覆盖率（持续优化中）
- 📦 发布: 准备中
指标统计¶
| 指标 | 数值 |
|---|---|
| 总文件数 | 30+ 个 |
| 总代码行数 | 5000+ 行 |
| 核心模块 | 16 个 |
| 测试覆盖率 | 94% |
| 文档行数 | 4000+ 行 |
| ORM 支持 | SQLAlchemy + Tortoise |
| 功能数量 | 23 个 |
| 许可证 | AGPL-3.0 |
完成时间表¶
| 阶段 | 任务 | 完成时间 | 状态 |
|---|---|---|---|
| 1 | 核心框架 | 2 周 | ✅ 完成 |
| 2 | 基础功能 | 2 周 | ✅ 完成 |
| 3 | ORM 适配器 | 1 周 | ✅ 完成 |
| 4 | 高级功能 | 2 周 | ✅ 完成 |
| 5 | 扩展功能 | 1 周 | ✅ 完成 |
| 6 | 文档和测试 | 进行中 | 🔄 进行中 |
| 7 | 发布推广 | 待开始 | ⏳ 待开始 |
| 总计 | 9 周 |
🤝 贡献指南¶
报告 Bug¶
- 检查是否已有相同的 Issue
- 提供详细的复现步骤
- 包含错误信息和日志
- 注意：本项目采用 AGPL-3.0 许可证
提交功能¶
- 创建 Feature Branch
- 编写代码和测试
- 提交 Pull Request
- 等待代码审查
- 确保遵守 AGPL-3.0 许可证条款
代码审查标准¶
- ✅ 代码风格符合规范
- ✅ 有相应的测试
- ✅ 文档已更新
- ✅ 没有破坏现有功能
- ✅ 遵守 AGPL-3.0 许可证
- ✅ 包含必要的许可证头注释
📞 联系方式¶
- 📧 Email: 1339731209@qq.com
- 🐙 GitHub: fastapi-easy
- 💬 讨论: GitHub Discussions
- 📋 商业许可: 1339731209@qq.com
📝 更新日志¶
v0.1.0 (当前)¶
- 📚 完成项目文档和架构设计
- 📋 创建开发指南
- 🔐 采用 AGPL-3.0 许可证
v1.0.0 (计划)¶
- 💻 所有核心功能已实现
- 🧪 94% 测试覆盖率
- 📦 首次 PyPI 发布
- 🌍 国际化支持
许可证: AGPL-3.0 (详见 LICENSE)
最后更新: 2024 年 11 月 28 日