python-patterns

Python 模式

面向 2025 的 Python 开发原则与决策方法。
学习如何思考，不要只记模式。

---

[WARN] 本技能使用方式

本技能强调决策原则，不是固定代码模板。

• 需求不明确时，先询问用户框架偏好
• 根据 Context（上下文）决定 async（异步）或 sync（同步）
• 不要每次都默认同一框架

---

1. 框架选型（2025）

决策树

你要构建什么？
|
+-- API 优先（API-first）/ 微服务
|   +-- FastAPI（async、现代、速度快）
|
+-- 全栈 Web / CMS / 管理后台
|   +-- Django（开箱即用，batteries-included）
|
+-- 简单应用 / 脚本 / 学习
|   +-- Flask（极简、灵活）
|
+-- AI/ML API 服务化
|   +-- FastAPI（Pydantic、async、Uvicorn）
|
+-- 后台任务
    +-- Celery + 任意 Web 框架

对比原则

维度	FastAPI	Django	Flask
适用场景	API、微服务	全栈、CMS	简单项目、学习
异步支持	原生支持	Django 5.0+	依赖扩展
管理后台	手动构建	内置 Admin（管理后台）	依赖扩展
ORM（对象关系映射）	自由选择	Django ORM	自由选择
学习曲线	低	中	低

选型前必须询问：

1. 是纯 API 还是全栈应用？
2. 是否需要后台管理界面？
3. 团队是否熟悉 async？
4. 是否有现有基础设施约束？

---

2. 异步与同步决策

何时使用异步（async）

async def（异步函数）更适合：
+-- I/O 密集操作（数据库、HTTP、文件）
+-- 大量并发连接
+-- 实时交互场景
+-- 微服务通信
+-- FastAPI/Starlette/Django ASGI（异步服务器网关接口）

def（同步函数）更适合：
+-- CPU 密集操作
+-- 简单脚本
+-- 遗留代码库
+-- 团队不熟悉 async
+-- 依赖阻塞型库（无 async 版本）

黄金法则

I/O bound（I/O 密集）-> async（等待外部资源）
CPU bound（CPU 密集）-> sync + multiprocessing（本地计算）

不要：
+-- 随意混用 sync 与 async
+-- 在 async 代码里调用阻塞库
+-- 为 CPU 任务强行上 async

异步库选型

需求	异步库
HTTP 客户端	httpx
PostgreSQL	asyncpg
Redis（内存数据库）	aioredis / redis-py async
文件 I/O	aiofiles
数据库 ORM	SQLAlchemy 2.0 async, Tortoise

---

3. 类型标注策略

哪些地方要标注

必须标注：
+-- 函数参数
+-- 返回类型
+-- 类属性
+-- 对外公开 API

可省略：
+-- 局部变量（让推断工作）
+-- 一次性脚本
+-- 测试代码（通常可选）

常见类型模式

# 下面是模式示例，请理解其语义：

# Optional（可选）-> 可能为 None
from typing import Optional
def find_user(id: int) -> Optional[User]: ...

# Union（联合类型）-> 多类型之一
def process(data: str | dict) -> None: ...

# 泛型集合
def get_items() -> list[Item]: ...
def get_mapping() -> dict[str, int]: ...

# Callable（可调用）
from typing import Callable
def apply(fn: Callable[[int], str]) -> str: ...