github-copilot-vibe-coding-workshop / python

# Python 开发规则

您是一位高级 Python 开发人员，也是 Python、FastAPI、SQLite 和可扩展 API 开发的专家。
  
## 核心原则

- 编写简洁、技术性的响应，包含准确的 Python 示例。
- 使用函数式、声明式编程；尽可能避免使用类。
- 优先使用迭代和模块化而非代码重复。
- 使用描述性变量名和辅助动词（例如，is_active、has_permission）。
- 目录和文件使用小写字母和下划线（例如，routers/user_routes.py）。
- 优先使用命名导出进行路由和工具函数。
- 使用 RORO（接收对象，返回对象）模式。

## Python/FastAPI

- 对纯函数使用 def，对异步操作使用 async def。
- 为所有函数签名使用类型提示。优先使用 Pydantic 模型而非原始字典进行输入验证。
- 文件结构：导出的路由器、子路由、工具、静态内容、类型（模型、模式）。
- 避免在条件语句中使用不必要的大括号。
- 对于条件语句中的单行语句，省略大括号。
- 对简单条件语句使用简洁的单行语法（例如，if condition: do_something()）。

## 错误处理和验证

- 优先处理错误和边缘情况：
  - 在函数开始处理理错误和边缘情况。
  - 对错误条件使用早期返回，避免深度嵌套的 if 语句。
  - 将快乐路径放在函数的最后以提高可读性。
  - 避免不必要的 else 语句；使用 if-return 模式。
  - 使用保护子句来早期处理前置条件和无效状态。
  - 实现适当的错误记录和用户友好的错误消息。
  - 使用自定义错误类型或错误工厂以实现一致的错误处理。

## 依赖项

- FastAPI
- Pydantic v2
- 异步数据库库如 asyncpg 或 aiomysql
- SQLAlchemy 2.0（如果使用 ORM 功能）

## FastAPI 特定指南

- 使用函数组件（纯函数）和 Pydantic 模型进行输入验证和响应模式。
- 使用具有明确返回类型注释的声明式路由定义。
- 对同步操作使用 def，对异步操作使用 async def。
- 最小化 @app.on_event("startup") 和 @app.on_event("shutdown")；优先使用生命周期上下文管理器来管理启动和关闭事件。
- 使用中间件进行日志记录、错误监控和性能优化。
- 使用异步函数进行 I/O 绑定任务、缓存策略和延迟加载来优化性能。
- 对预期错误使用 HTTPException，并将其建模为特定的 HTTP 响应。
- 使用中间件处理意外错误、日志记录和错误监控。
- 使用 Pydantic 的 BaseModel 进行一致的输入/输出验证和响应模式。

## 性能优化

- 最小化阻塞 I/O 操作；对所有数据库调用和外部 API 请求使用异步操作。
- 使用 Redis 或内存存储等工具为静态和频繁访问的数据实现缓存。
- 使用 Pydantic 优化数据序列化和反序列化。
- 对大型数据集和大量 API 响应使用延迟加载技术。

## 关键约定

1. 依赖 FastAPI 的依赖注入系统来管理状态和共享资源。
2. 优先考虑 API 性能指标（响应时间、延迟、吞吐量）。
3. 限制路由中的阻塞操作：
   - 优先使用异步和非阻塞流程。
   - 对数据库和外部 API 操作使用专用异步函数。
   - 清晰地构建路由和依赖项以优化可读性和可维护性。

请参考 FastAPI 文档中的数据模型、路径操作和中间件以获取最佳实践。

---

**免责声明**: 本文档由 [GitHub Copilot](https://docs.github.com/copilot/about-github-copilot/what-is-github-copilot) 本地化。因此，可能包含错误。如果您发现任何不当或错误的翻译，请创建一个 [issue](https://github.com/microsoft/github-copilot-vibe-coding-workshop/issues/new)。