名称: python-模式描述: Python 开发原则与决策制定。框架选择、异步模式、类型提示、项目结构。教授思考，而非复制。允许工具: 读取、写入、编辑、全局搜索、查找

Python 模式

Python 开发原则与决策制定（适用于2025年）。 学会思考，而不是死记硬背模式。

⚠️ 如何使用本技能

本技能教授决策制定原则，而非固定的代码复制。

当不明确时，询问用户框架偏好
根据上下文选择异步或同步
不要每次都默认使用相同的框架

1. 框架选择（2025年）

决策树

你在构建什么？
│
├── API优先 / 微服务
│   └── FastAPI（异步、现代、快速）
│
├── 全栈网络 / CMS / 管理后台
│   └── Django（内置齐全）
│
├── 简单 / 脚本 / 学习
│   └── Flask（最小化、灵活）
│
├── AI/ML API 服务
│   └── FastAPI（Pydantic、异步、uvicorn）
│
└── 后台任务
    └── Celery + 任何框架

比较原则

因素	FastAPI	Django	Flask
最适合	API、微服务	全栈、CMS	简单、学习
异步	原生支持	Django 5.0+	通过扩展
管理后台	手动构建	内置	通过扩展
ORM	自选	Django ORM	自选
学习曲线	低	中	低

选择问题提问：

这是仅API还是全栈？
需要管理后台吗？
团队熟悉异步吗？
现有基础设施？

2. 异步与同步决策

何时使用异步

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 异步、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: ...

Pydantic 用于验证

何时使用 Pydantic：
├── API 请求/响应模型
├── 配置/设置
├── 数据验证
├── 序列化

好处：
├── 运行时验证
├── 自动生成 JSON 模式
├── 与 FastAPI 原生集成
└── 清晰的错误信息

4. 项目结构原则

结构选择

小型项目 / 脚本：
├── 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/（API 端点）
├── services/（业务逻辑）
├── models/（数据库模型）
├── schemas/（Pydantic 模型）
└── dependencies/（共享依赖）

按功能：
├── users/
│   ├── routes.py
│   ├── service.py
│   └── schemas.py
└── products/
    └── ...

5. Django 原则（2025年）

Django 异步（Django 5.0+）

Django 支持异步：
├── 异步视图
├── 异步中间件
├── 异步 ORM（有限）
└── ASGI 部署

何时在 Django 中使用异步：
├── 外部 API 调用
├── WebSocket（Channels）
├── 高并发视图
└── 后台任务触发

Django 最佳实践

模型设计：
├── 厚模型、薄视图
├── 使用管理器处理常见查询
├── 抽象基类用于共享字段

视图：
├── 基于类的用于复杂 CRUD
├── 基于函数的用于简单端点
├── 使用视图集与 DRF

查询：
├── select_related() 用于外键
├── prefetch_related() 用于多对多
├── 避免 N+1 查询
└── 使用 .only() 选择特定字段

6. FastAPI 原则

async def vs def 在 FastAPI 中

使用 async def 当：
├── 使用异步数据库驱动
├── 进行异步 HTTP 调用
├── I/O 密集型操作
└── 想要处理并发

使用 def 当：
├── 阻塞操作
├── 同步数据库驱动
├── CPU 密集型工作
└── FastAPI 自动在线程池中运行

依赖注入

使用依赖项用于：
├── 数据库会话
├── 当前用户 / 认证
├── 配置
├── 共享资源

好处：
├── 可测试性（模拟依赖项）
├── 清晰分离
├── 自动清理（yield）

Pydantic v2 集成

# FastAPI + Pydantic 紧密集成：

# 请求验证
@app.post("/users")
async def create(user: UserCreate) -> UserResponse:
    # user 已验证
    ...

# 响应序列化
# 返回类型成为响应模式

7. 后台任务

选择指南

解决方案	最适合
BackgroundTasks	简单、进程内任务
Celery	分布式、复杂工作流
ARQ	异步、基于 Redis
RQ	简单 Redis 队列
Dramatiq	基于 Actor、比 Celery 简单

何时使用每种

FastAPI BackgroundTasks：
├── 快速操作
├── 无需持久化
├── 发射后不管
└── 同一进程

Celery/ARQ：
├── 长时间运行任务
├── 需要重试逻辑
├── 分布式工作器
├── 持久队列
└── 复杂工作流

8. 错误处理原则

异常策略

在 FastAPI 中：
├── 创建自定义异常类
├── 注册异常处理器
├── 返回一致的错误格式
└── 记录而不暴露内部信息

模式：
├── 在服务中引发领域异常
├── 在处理器中捕获并转换
└── 客户端获得干净的错误响应

错误响应哲学

包括：
├── 错误代码（可编程）
├── 消息（人类可读）
├── 细节（字段级时适用）
└── 不要包含堆栈跟踪（安全）

9. 测试原则

测试策略

类型	目的	工具
单元测试	业务逻辑	pytest
集成测试	API 端点	pytest + httpx/TestClient
端到端测试	完整工作流	pytest + 数据库

异步测试

# 使用 pytest-asyncio 进行异步测试

import pytest
from httpx import AsyncClient

@pytest.mark.asyncio
async def test_endpoint():
    async with AsyncClient(app=app, base_url="http://test") as client:
        response = await client.get("/users")
        assert response.status_code == 200

夹具策略

常见夹具：
├── db_session → 数据库连接
├── client → 测试客户端
├── authenticated_user → 带令牌的用户
└── sample_data → 测试数据设置

10. 决策清单

实现前：

[ ] 询问用户框架偏好？
[ ] 为当前上下文选择框架？（不只是默认）
[ ] 决定异步 vs 同步？
[ ] 计划类型提示策略？
[ ] 定义项目结构？
[ ] 计划错误处理？
[ ] 考虑后台任务？

11. 避免的反模式

❌ 不要：

为简单 API 默认使用 Django（FastAPI 可能更好）
在异步代码中使用同步库
为公共 API 跳过类型提示
将业务逻辑放在路由/视图中
忽略 N+1 查询
随意混合异步和同步

✅ 做：

根据上下文选择框架
询问异步需求
使用 Pydantic 进行验证
分离关注点（路由 → 服务 → 存储库）
测试关键路径

记住：Python 模式是关于根据您的具体上下文做出决策。不要复制代码——思考什么最适合您的应用。

名称: python-模式 描述: Python 开发原则与决策制定。框架选择、异步模式、类型提示、项目结构。教授思考，而非复制。 允许工具: 读取、写入、编辑、全局搜索、查找

Python 模式

⚠️ 如何使用本技能

1. 框架选择（2025年）

决策树

比较原则

选择问题提问：

2. 异步与同步决策

何时使用异步

黄金规则

异步库选择

3. 类型提示策略

何时使用类型

常见类型模式

Pydantic 用于验证

4. 项目结构原则

结构选择

FastAPI 结构原则

5. Django 原则（2025年）

Django 异步（Django 5.0+）

Django 最佳实践

6. FastAPI 原则

async def vs def 在 FastAPI 中

依赖注入

Pydantic v2 集成

7. 后台任务

选择指南

何时使用每种

8. 错误处理原则

异常策略

错误响应哲学

9. 测试原则

测试策略

异步测试

夹具策略

10. 决策清单

11. 避免的反模式

❌ 不要：

✅ 做：

名称: python-模式描述: Python 开发原则与决策制定。框架选择、异步模式、类型提示、项目结构。教授思考，而非复制。允许工具: 读取、写入、编辑、全局搜索、查找