用途
fastapi-patterns 面向现代、生产级 FastAPI 开发，围绕项目布局、Pydantic v2 数据模型、依赖注入、异步模式、认证授权、事务性服务方法与测试，给出一套可直接参照的实践范式。
项目结构
示例采用以下目录组织：
my_app/
|-- app/
| |-- main.py # App factory, lifespan, middleware
| |-- config.py # Settings via pydantic-settings
| |-- dependencies.py # Shared FastAPI dependencies
| |-- database.py # SQLAlchemy engine + session
| |-- routers/
| | `-- users.py
| |-- models/ # SQLAlchemy ORM models
| | `-- user.py
| |-- schemas/ # Pydantic request/response schemas
| | `-- user.py
| `-- services/ # Business logic layer
| `-- user_service.py
|-- tests/
| |-- conftest.py
| `-- test_users.py
|-- pyproject.toml
`-- .env
分层职责为：routers 负责路由与端点，models 存放 SQLAlchemy ORM 模型，schemas 存放 Pydantic 请求/响应模型，services 承载业务逻辑。
应用工厂与生命周期
通过 create_app() 应用工厂创建 FastAPI 实例，并使用 asynccontextmanager 定义 lifespan。启动时可在开发/演示环境用 Base.metadata.create_all 自动建表，严格生产环境应改用 Alembic 迁移管理 schema；关闭时调用 engine.dispose() 释放连接池资源。同时挂载 CORSMiddleware，并将 users 路由以 /users 前缀注册。
配置管理
使用 pydantic-settings 的 BaseSettings 与 SettingsConfigDict(env_file=".env") 读取配置，字段包括应用名称、版本、debug 开关、数据库 URL、密钥、JWT 算法与令牌过期时间，以及允许的来源、方法、请求头与凭证开关等 CORS 相关配置。
Pydantic v2 数据模型
schemas 中定义 UserBase、UserCreate、UserUpdate、UserResponse 与 UserListResponse。UserCreate 使用 model_validator(mode="after") 校验两次密码一致；UserResponse 通过 model_config = {"from_attributes": True} 支持从 ORM 对象转换。字段使用 Field 约束长度，邮箱使用 EmailStr。
依赖注入
dependencies.py 中定义数据库会话依赖 get_db，异常时回滚并重新抛出；定义 get_current_user 解析 JWT 并查询用户，失败返回 401；定义 get_current_active_user 在用户未激活时返回 403。再用 Annotated 类型别名 DbDep、CurrentUserDep、ActiveUserDep 统一注入。JWT 解码采用防御式处理，兼容字符串/整数类型转换差异。
路由与端点设计
路由层保持轻量，按 REST 语义提供创建用户（201）、获取当前用户、分页列出用户（skip/limit 带 Query 约束）、更新用户（先做授权判断，再调用更新）以及登录换取令牌等端点。所有端点声明 response_model，避免意外泄露字段并生成清晰的 OpenAPI schema。
服务层与事务
UserService 封装业务逻辑：创建用户时对密码做哈希后提交，捕获 IntegrityError 转为自定义的 DuplicateUserError；列表查询同时返回总数与分页结果，并强制使用 .order_by(User.id) 确定性排序；更新时使用 model_dump(exclude_unset=True) 只更新传入字段；认证方法校验密码后签发带 sub 与 exp 的 JWT。文中特别提示：应用层的唯一性处理需要底层数据库唯一索引支撑，否则无法安全防止并发竞态。
测试
使用 httpx 的 ASGITransport 与 pytest-asyncio，在 conftest 中基于内存 SQLite 建立测试引擎，提供 setup_db、db_session、client、registered_user、auth_token、auth_client 等夹具，并通过 app.dependency_overrides 覆盖 get_db。
反模式对照
文中列举两类反模式：一是把业务逻辑写进路由处理器（推荐改为瘦路由加事务性服务）；二是在异步路由里使用同步数据库调用阻塞事件循环（推荐改用 async SQLAlchemy 的 await db.execute）。
最佳实践与限制
最佳实践包括：始终声明类型化 response_model；用类型别名整合依赖注入；在服务层事务边界内捕获结构性数据库错误；防御式解析 JWT；为所有 offset/limit 分页强制确定性排序；将授权检查与认证依赖分离以准确区分 401 与 403。关于定价、平台支持范围、性能指标及其他未在资料中说明的信息，暂未提供。