Python后端开发专家指南：Django与FastAPI最佳实践、数据库迁移与HTMX整合

python-backend-expert by oimiragieo/agent-studio

74 周安装量

19 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/oimiragieo/agent-studio --skill python-backend-expert

Python Web框架开发系统架构

🇨🇳中文介绍

Python 后端专家

alembic 数据库迁移

在审查或编写代码时，请遵循以下准则：

使用 alembic 进行数据库迁移。

用于 HTMX 的 Django 基于类的视图

在审查或编写代码时，请遵循以下准则：

使用 Django 基于类的视图来处理 HTMX 响应

Django 表单处理

在审查或编写代码时，请遵循以下准则：

使用 Django 表单进行表单处理
对 HTMX 请求使用 Django 的表单验证

Django 表单

在审查或编写代码时，请遵循以下准则：

利用 Django 的表单和模型表单类进行表单处理和验证。
使用 Django 的验证框架来验证表单和模型数据。
将业务逻辑保留在模型和表单中；保持视图轻量级并专注于请求处理。

Django 框架规则

在审查或编写代码时，请遵循以下准则：

始终使用最新稳定版本的 Django，并熟悉其最新特性和最佳实践。

Django 中间件

在审查或编写代码时，请遵循以下准则：

审慎使用中间件来处理横切关注点，如身份验证、日志记录和缓存。
使用 Django 的中间件来处理常见任务，如身份验证、日志记录和安全。

用于请求/响应的 Django 中间件

在审查或编写代码时，请遵循以下准则：

利用 Django 的中间件进行请求/响应处理

Django 模型

在审查或编写代码时，请遵循以下准则：

利用 Django 的 ORM 进行数据库交互；除非出于性能考虑必须使用，否则避免使用原始 SQL 查询。
将业务逻辑保留在模型和表单中；保持视图轻量级并专注于请求处理。

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

用于数据库操作的 Django ORM

在审查或编写代码时，请遵循以下准则：

使用 Django ORM 进行数据库操作

在审查或编写代码时，请遵循以下准则：

使用 Django 模板渲染 HTML，使用 DRF 序列化器处理 JSON 响应

Django 5.x 特性 (2025+)

在审查或编写代码时，请遵循以下准则：

Django 5.2 是当前的 LTS（长期支持）版本；新项目应以其为目标（支持至 2028 年）
在模型字段上使用 db_default 来设置数据库计算的默认值（例如，db_default=Now()），而不是使用应由数据库拥有值的 Python 端默认值
在 Django 管理后台中使用分面过滤器（ModelAdmin.show_facets），以便在筛选选项旁显示计数
利用改进的异步 ORM 支持：Django 5.x 扩展了 async 原生查询集方法——在异步视图中优先使用 await qs.acount()、await qs.afirst()、async for obj in qs
使用 MIDDLEWARE 列表进行声明式中间件配置；对于高吞吐量的 ASGI 部署，优先使用支持异步的中间件
当所有视图都需要身份验证时，使用 LoginRequiredMiddleware（Django 5.1+）而不是装饰每个视图
使用 GeneratedField 处理数据库生成的列（在数据库级别从其他列计算得出）

FastAPI 模式 (2025+)

在审查或编写代码时，请遵循以下准则：

使用 lifespan 上下文管理器（而非已弃用的 @app.on_event）进行启动/关闭资源管理：
```
from contextlib import asynccontextmanager
```
from fastapi import FastAPI

@asynccontextmanager async def lifespan(app: FastAPI): # 启动：初始化数据库连接池、HTTP 客户端、缓存 app.state.db_pool = await create_pool() yield # 关闭：关闭资源 await app.state.db_pool.close()

app = FastAPI(lifespan=lifespan)
对所有请求/响应模式使用 Pydantic v2 模型；Pydantic v2 是 FastAPI 0.100+ 的默认版本。使用 model_config = ConfigDict(...) 而不是内部的 class Config
使用带有 lru_cache 的 pydantic-settings（BaseSettings）进行配置管理：
```
from functools import lru_cache
```
from pydantic_settings import BaseSettings

class Settings(BaseSettings): database_url: str model_config = ConfigDict(env_prefix="APP_")

@lru_cache def get_settings() -> Settings: return Settings()
正确界定依赖范围：每个请求（数据库会话、身份验证）、路由器级别（审计日志记录、命名空间缓存）、应用程序生命周期（Kafka 生产者、功能标志 SDK、追踪导出器）
使用带有 Depends 的 Annotated 类型提示以获得更清晰的依赖签名：
```
from typing import Annotated
```
from fastapi import Depends

DbSession = Annotated[AsyncSession, Depends(get_db)] CurrentUser = Annotated[User, Depends(get_current_user)]
按领域组织项目结构：routers/、services/、repositories/、schemas/、models/——避免在原型之外使用扁平的单一文件应用
对于 I/O 密集型路由，优先使用 async def 路径操作；仅对应在线程池中运行的 CPU 密集型工作使用 def（同步）
使用带有 prefix、tags 和 dependencies 的 APIRouter 来分组相关路由并应用共享中间件

SQLAlchemy 2.0 异步模式 (2025+)

在审查或编写代码时，请遵循以下准则：

使用 create_async_engine + async_sessionmaker（不要直接使用已弃用的 AsyncSession 工厂）；在应用程序启动时为每个服务创建一个引擎
使用新的 Mapped + mapped_column 声明式风格（SQLAlchemy 2.0+），而不是传统的 Column 风格：
```
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
```
from sqlalchemy import String

class Base(DeclarativeBase): pass

class User(Base): tablename = "users" id: Mapped[int] = mapped_column(primary_key=True) email: Mapped[str] = mapped_column(String(255), unique=True) is_active: Mapped[bool] = mapped_column(default=True)
使用 async with 会话作用域，通过 FastAPI 依赖注入提供数据库会话：
```
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
```
async_session = async_sessionmaker(engine, expire_on_commit=False)

async def get_db() -> AsyncGenerator[AsyncSession, None]: async with async_session() as session: yield session
在 SQLAlchemy 2.0+ 中，所有查询都使用 select()（而不是传统的 session.query()）
在异步上下文中，显式使用 selectinload / joinedload 以避免隐式延迟加载 I/O（延迟加载在异步环境中会引发 MissingGreenlet 错误）
对于 upsert 操作，使用 insert().on_conflict_do_update()（PostgreSQL）或特定数据库方言的等效方法，而不是单独的 select + update 往返
使用适合异步的连接池大小：异步驱动（asyncpg、aiomysql）比同步驱动需要更小的连接池；对于中等负载，pool_size=5, max_overflow=10 是一个安全的默认值

Python 3.13 / 3.14 特性 (2025+)

在审查或编写代码时，请遵循以下准则：

Python 3.13（2024年10月发布） 是当前用于生产的稳定版本；Python 3.14（2025年10月发布）也是稳定版本
无 GIL 模式（PEP 703，3.13 中为实验性，3.14 中趋于成熟）： 可以使用 python3.13t（无 GIL 构建）禁用 GIL。在为 3.13+ 编写的新代码中，避免假设 GIL 对共享可变状态的保护；使用显式锁或线程安全的数据结构。未经对所有 C 扩展的全面测试，请勿在生产环境中启用无 GIL 模式
实验性 JIT 编译器（PEP 744，3.13+）： 通过 PYTHON_JIT=1 启用。为紧密循环和数值计算代码提供可观的加速。无需更改代码；只需了解其存在，以便用于性能敏感的服务
改进的错误消息（3.13+）： 回溯现在默认以颜色进行语法高亮显示。常见错误（属性名拼写错误、缺少导入）的错误消息描述性显著增强——在调试时可依赖它们
Python 3.14 — 模板字符串 / T-字符串（PEP 750）： 新的 t"..." 字符串字面量，延迟插值，适用于构建安全的 SQL/HTML 而无需注入风险。在构建动态查询或 HTML 片段时，优先使用 T-字符串而不是 f-字符串
Python 3.14 — 延迟注解求值（PEP 649）： 注解现在默认延迟求值（不再需要 from __future__ import annotations）。这以零运行时成本解决了类型提示中的前向引用问题
Python 3.14 — 并行子解释器： interpreters 标准库模块通过子解释器实现真正的并行性，而无需禁用 GIL。适用于以前需要多进程处理的 CPU 密集型工作负载
Python 3.14 — 增量垃圾回收器： 减少 GC 暂停时间，提高长时间运行的异步服务中的延迟一致性
所有新项目都使用 pyproject.toml（不仅仅是 setup.py / requirements.txt）；使用 uv 或 pip 配合 pyproject.toml 进行可复现的依赖管理
始终在 pyproject.toml 的 requires-python 字段中指定最低 Python 版本

此专家技能整合了 1 项独立技能：

python-backend-expert

始终使用 lifespan 上下文管理器进行 FastAPI 启动/关闭资源管理——@app.on_event 已弃用，并将在未来版本中移除。
绝不在 SQLAlchemy 2.0+ 中使用 session.query()——使用带有 2.0 风格 API 的 select()；传统查询 API 将被移除。
始终对所有数据库操作使用参数化查询或 ORM——绝不使用字符串插值或 f-字符串构建 SQL（SQL 注入向量）。
绝不在异步 FastAPI 路由中执行阻塞 I/O——对阻塞操作使用带有可等待驱动的 async def 或 run_in_executor，以避免事件循环饥饿。
始终在边界使用 Pydantic v2 模型验证所有请求数据——绝不将原始请求字典传递到业务逻辑层。

反模式	失败原因	正确方法
使用 `@app.on_event` 进行启动/关闭	在 FastAPI 中已弃用；版本升级时会中断	使用带有 `lifespan` 参数的 `@asynccontextmanager`
在 SQLAlchemy 2.0+ 中使用 `session.query()`	传统查询 API 已弃用并将被移除	使用 `select()` 语句配合 `session.execute()`
使用 f-字符串或 `%` 格式化构建 SQL 字符串	SQL 注入漏洞；严重的安全缺陷	通过 ORM 或带有绑定参数的 `text()` 使用参数化查询
在 `async def` 路由中直接调用阻塞 I/O	阻塞整个事件循环；导致级联延迟	使用可等待的异步驱动；对同步代码使用 `loop.run_in_executor()`
将业务逻辑放在 FastAPI 路径函数中	将路由与逻辑耦合；使单元测试无法进行	将逻辑提取到服务/仓库层；通过 `Depends()` 注入

记忆协议（强制）

cat .claude/context/memory/learnings.md

完成后： 记录发现的任何新模式或例外情况。

假设中断：您的上下文可能会重置。如果它不在记忆中，那就没有发生。