关于 python-best-practices
python-best-practices 是面向 Python 和 FastAPI 开发的速查技能，涵盖架构、Pydantic v2、异步模式、持久化、配置和分页，并指向 code-patterns.md 中的详细示例。
主要功能
- 01路由器－服务－仓储分层架构
- 02Pydantic v2 模式指导
- 03异步与 lifespan 模式
- 04软删除与 SQLAlchemy 指导
- 05配置和分页模式
适用场景
- 01规划 FastAPI 项目结构
- 02设计 API 模式和端点
- 03审查异步路由与数据库模式
- 04统一配置和列表响应
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/python-best-practices确认已加载。
附带文件code-patterns.md
详细介绍
Python + FastAPI 最佳实践 — 快速参考
分层架构
路由 → 服务 → 仓储 → 数据库。每一层只能调用其下方的一层。
完整的项目结构和分层示例请参阅 code-patterns.md。
Pydantic v2
将 Create、Update 和 Response 模式分开。使用 ConfigDict(from_attributes=True) 集成 ORM。使用 str | None 语法（而非 Optional[str]）。
模式示例请参阅 code-patterns.md。
异步模式
用于 I/O 路由时使用 async def，用于 CPU 密集型任务时使用普通 def。使用 lifespan 上下文管理器（而非 on_event）。使用 httpx.AsyncClient 发起外部 HTTP 调用。
异步示例请参阅 code-patterns.md。
软删除
在 SQLAlchemy 模型上使用 SoftDeleteMixin。在所有查询中添加筛选条件 where(Model.deleted_at.is_(None))。
Mixin 和仓储模式请参阅 code-patterns.md。
配置
使用 pydantic-settings 管理所有配置。绝不硬编码密钥、URL 或魔法数字。
Settings 类模式请参阅 code-patterns.md。
分页
所有列表端点都使用通用的 PaginatedResponse[T]。始终返回 total、page、limit 和 has_more。
模式请参阅 code-patterns.md。
注意事项
-
async def和def会影响性能。 调用阻塞代码（例如time.sleep()或同步数据库驱动程序）的async def路由会阻塞整个事件循环。CPU 密集型工作应使用普通def— FastAPI 会在线程池中运行它。只有在需要await某些操作时才使用async def。 -
datetime.utcnow()自 Python 3.12 起已弃用。 请改用datetime.now(UTC)。旧函数会返回无时区信息的 datetime，从而导致比较错误。新函数会返回带时区信息的 UTC 时间。 -
Pydantic 中的可变默认参数看似安全，但也有需要注意之处。
tags: list[str] = []在 Pydantic 中可用（它会复制默认值）。但tags: list[str] = Field(default_factory=list)更明确，对嵌套模型也更安全。对于简单字段，两种写法均可。对于复杂的嵌套默认值，始终使用default_factory。 -
from_attributes=True取代了orm_mode=True。 Pydantic v2 更改了配置 API。使用旧的orm_mode不会报错，但会被静默忽略 — ORM 对象将无法正确序列化。 -
SQLAlchemy 的
Column()已属旧式写法。 SQLAlchemy 2.0 应使用Mapped[type]和mapped_column()。旧的Column(String)仍然可用，但会失去类型检查器支持和 IDE 自动补全。