Python Patterns 是一份面向 2025 年的 Python 开发原则与决策指南,其核心目标是教人“思考”而非记忆模式。该技能并不提供可直接复制的固定代码,而是帮助开发者根据具体上下文做技术选择。资料特别提示:当框架偏好不明确时,应先询问用户;异步还是同步要结合上下文判断;不要每次都默认采用同一个框架。
一、框架选择 资料给出决策树:如果项目是 API 优先或微服务,那么选 FastAPI;如果是全栈 Web、CMS 或后台管理,那么选 Django;如果是简单脚本或学习用途,那么选 Flask;如果是 AI/ML API 服务,那么选 FastAPI;如果涉及后台 worker,那么用 Celery 搭配任意框架。选择前建议询问:是仅 API 还是全栈、是否需要管理后台、团队是否熟悉异步、已有基础设施情况。
二、异步 vs 同步 I/O 密集型操作(数据库、HTTP、文件)、大量并发连接、实时功能、微服务通信以及使用 FastAPI/Starlette/Django ASGI 时,适合用 async def;CPU 密集型操作、简单脚本、遗留代码库、团队不熟悉异步、只有阻塞库时,适合用同步 def。基本规则是:I/O 密集型用异步,CPU 密集型用同步加多进程。应当避免混用同步与异步、在异步代码中使用同步库,以及强行对 CPU 工作使用异步。资料还列出异步库选择,例如 HTTP 客户端用 httpx、PostgreSQL 用 asyncpg、Redis 用 aioredis 或 redis-py async、文件 I/O 用 aiofiles、数据库 ORM 用 SQLAlchemy 2.0 async 或 Tortoise。
三、类型提示策略 函数参数、返回类型、类属性、公开 API 应始终标注类型;局部变量、一次性脚本、测试通常可以省略。资料展示了 Optional、Union、泛型集合与 Callable 等常见写法示例。Pydantic 适合用于 API 请求和响应模型、配置、数据校验与序列化,可提供运行时校验、自动生成 JSON Schema、与 FastAPI 原生集成以及清晰的错误信息。
四、项目结构 小项目或脚本采用单文件加 utils、requirements;中型 API 采用 app 目录,并包含 main、models、routes、services、schemas,外加 tests 与 pyproject.toml;大型应用采用 src 目录布局。FastAPI 结构可以按层划分,即 routes、services、models、schemas、dependencies;也可以按功能划分,即 users、products 等各自的 routes、service、schemas。
五、Django 与 FastAPI 原则 Django 5.0+ 支持异步视图、异步中间件、有限的异步 ORM 与 ASGI 部署,适合外部 API 调用、WebSocket、高并发视图与后台任务触发。最佳实践包括胖模型瘦视图、用 managers 封装常用查询、用抽象基类共享字段、复杂 CRUD 用类视图、简单端点用函数视图、用 select_related/prefetch_related 避免 N+1、用 .only() 取特定字段。FastAPI 中,使用异步数据库驱动、异步 HTTP 调用与 I/O 操作时用 async def;阻塞操作、同步驱动、CPU 工作时用 def,因为 FastAPI 会自动在线程池中运行。依赖注入适合数据库会话、当前用户/认证、配置与共享资源,能提升可测试性。
六、后台任务、错误处理与测试 后台任务选择:BackgroundTasks 用于简单进程内任务;Celery 用于分布式复杂工作流;ARQ 用于基于 Redis 的异步;RQ 用于简单 Redis 队列;Dramatiq 用于基于 actor 且比 Celery 更简单的场景。错误处理方面,建议在 FastAPI 中创建自定义异常类、注册异常处理器、返回一致的错误格式、记录日志但不暴露内部信息;错误响应包含错误码、可读消息与字段级详情,不包含堆栈。测试分为单元测试(pytest)、集成测试(pytest 加 httpx/TestClient)、E2E 测试(pytest 加数据库),异步测试用 pytest-asyncio,并借助 db_session、client、authenticated_user、sample_data 等 fixture。
七、决策清单与反模式 实施前应确认是否询问过框架偏好、是否按当前上下文选择框架、是否确定异步与同步、是否规划类型提示、项目结构、错误处理与后台任务。应避免对简单 API 默认用 Django、在异步代码中用同步库、公开 API 省略类型提示、把业务逻辑放进路由或视图、忽略 N+1 查询、随意混用异步与同步。资料还列出应做的事:按上下文选框架、询问异步需求、用 Pydantic 校验、分离关注点、测试关键路径。
使用方式:该技能作为开发决策参考,在项目设计与实现时按上述原则逐项判断;资料未提供具体安装命令,也未说明收费、平台及其他使用步骤,这些信息暂未提供。