Python Patterns 是一个面向 2025 年的 Python 开发原则与决策技能,核心理念是教人“思考”而不是记忆和复制模式。使用该技能时,应在框架偏好不明确时先询问用户,根据上下文选择异步或同步,不要每次都默认同一框架。
一、框架选型(2025)
按构建目标选择:API 优先 / 微服务用 FastAPI(异步、现代、快速);全栈 Web / CMS / 后台用 Django(batteries-included);简单脚本或学习用途用 Flask(极简、灵活);AI/ML API 服务用 FastAPI(Pydantic、异步、uvicorn);后台工作者用 Celery 加任意框架。
对比原则:FastAPI 最适合 API 和微服务,原生支持异步,Admin 需手动实现,ORM 自选,学习曲线低;Django 最适合全栈和 CMS,Django 5.0+ 支持异步,内置 Admin,使用 Django ORM,学习曲线中等;Flask 最适合简单场景和学习,异步需通过扩展,Admin 需扩展,ORM 自选,学习曲线低。选型时应问:这是纯 API 还是全栈?需要 Admin 界面吗?团队熟悉异步吗?现有基础设施是什么?
二、异步与同步决策
async def 更适合:I/O 密集型操作(数据库、HTTP、文件)、大量并发连接、实时特性、微服务通信、FastAPI/Starlette/Django ASGI。同步 def 更适合:CPU 密集型操作、简单脚本、遗留代码库、团队不熟悉异步、只有阻塞库(无异步版本)。黄金法则是 I/O 密集型用异步,CPU 密集型用同步加多进程。不要粗心混用同步与异步、不要在异步代码中用同步库、不要强迫 CPU 工作使用异步。异步库选择:HTTP 客户端用 httpx;PostgreSQL 用 asyncpg;Redis 用 aioredis / redis-py async;文件 I/O 用 aiofiles;数据库 ORM 用 SQLAlchemy 2.0 async、Tortoise。
三、类型提示策略
始终标注:函数参数、返回类型、类属性、公共 API。可跳过:局部变量(交给推断)、一次性脚本、测试(通常)。常见模式包括 Optional(可能为 None)、Union(多种类型之一)、泛型集合(list[Item]、dict[str, int])、Callable。Pydantic 适用于 API 请求/响应模型、配置、数据验证、序列化,好处是运行时验证、自动生成 JSON schema、与 FastAPI 原生协作、错误信息清晰。
四、项目结构原则
小型项目/脚本:main.py、utils.py、requirements.txt。中型 API:app/ 下含 init.py、main.py、models/、routes/、services/、schemas/,外加 tests/ 和 pyproject.toml。大型应用:src/myapp/ 下含 core/、api/、services/、models/ 等,外加 tests/ 和 pyproject.toml。FastAPI 可按层组织(routes、services、models、schemas、dependencies)或按功能组织(users/、products/ 各自含 routes.py、service.py、schemas.py)。
五、Django 原则(2025)
Django 5.0+ 支持异步视图、异步中间件、有限的异步 ORM 与 ASGI 部署。适合异步的场景:外部 API 调用、WebSocket(Channels)、高并发视图、触发后台任务。最佳实践:模型设计采用胖模型、瘦视图,用 manager 处理常见查询,用抽象基类共享字段;视图复杂 CRUD 用类视图,简单端点用函数视图,DRF 用 viewsets;查询用 select_related() 处理外键、prefetch_related() 处理多对多,避免 N+1,用 .only() 取特定字段。
六、FastAPI 原则
使用 async def:使用异步数据库驱动、发起异步 HTTP 调用、I/O 密集型操作、需要处理并发。使用 def:阻塞操作、同步数据库驱动、CPU 密集型工作(FastAPI 会自动放入线程池)。依赖注入用于数据库会话、当前用户/认证、配置、共享资源,好处是可测试性、清晰分离、自动清理(yield)。Pydantic v2 与 FastAPI 紧密集成:请求自动验证,返回类型即响应 schema。
七、后台任务
BackgroundTasks 适合简单、进程内、无需持久化的即发即忘任务;Celery 适合分布式、复杂工作流;ARQ 适合异步、基于 Redis;RQ 适合简单 Redis 队列;Dramatiq 适合基于 actor、比 Celery 简单。长运行任务、需要重试、分布式 worker、持久化队列、复杂工作流应使用 Celery/ARQ。
八、错误处理原则
FastAPI 中创建自定义异常类、注册异常处理器、返回一致的错误格式、记录日志但不暴露内部细节。模式:在 service 中抛出领域异常,在 handler 中捕获并转换,客户端得到干净的错误响应。错误响应应包含错误码(程序可读)、消息(人类可读)、详细信息(适用时的字段级),但不包含堆栈跟踪(安全)。
九、测试原则
单元测试验证业务逻辑用 pytest;集成测试验证 API 端点用 pytest + httpx/TestClient;E2E 测试完整工作流用 pytest + DB。异步测试用 pytest-asyncio 配合 httpx 的 AsyncClient。常见 fixture 包括 db_session、client、authenticated_user、sample_data。
十、决策清单
实现前应确认:是否询问用户框架偏好?是否针对当前上下文选择框架(而非默认)?是否决定异步还是同步?是否规划类型提示策略?是否定义项目结构?是否规划错误处理?是否考虑后台任务?
十一、应避免的反模式
不要为简单 API 默认用 Django(FastAPI 可能更合适);不要在异步代码中用同步库;不要跳过公共 API 的类型提示;不要把业务逻辑放在 routes/views;不要忽略 N+1 查询;不要粗心混用异步与同步。应当基于上下文选择框架、询问异步需求、用 Pydantic 做验证、分离关注点(routes → services → repos)、测试关键路径。该技能强调 Python 模式是为你的具体上下文做决策,不要复制代码,而要思考什么最适合你的应用。