用途:当持久化架构与 ORM 集成是任务核心时使用,尤其涉及 SQLAlchemy 插件接线或基于 Piccolo DTO 的 API 流程。
主要能力:指导选择 ORM 路径(SQLAlchemy 或 Piccolo);决定 SQLAlchemy 插件策略;在应用初始化时集中配置引擎与会话工厂;定义模型/仓储/服务边界并明确事务归属;通过依赖注入向处理器提供按请求作用域的会话;在 API 边界定义 DTO 与序列化规则。
插件选择:SQLAlchemyPlugin 适用于同时需要应用/会话工具与模型序列化支持的大多数应用;SQLAlchemyInitPlugin 仅需引擎/会话注入与生命周期管理、不需要自动 DTO 序列化时使用;需要自动 SQLAlchemy DTO 生成时添加 SQLAlchemySerializationPlugin;需要显式组合控制时拆分使用 init 与 serialization 插件。
仓储与模型:提供 SQLAlchemyAsyncRepository 用于异步会话流程,支持 CRUD、过滤、排序、分页和批量操作;基础模型提供 UUID 与 BigInt 主键变体及可选审计列(UUIDBase、UUIDAuditBase、BigIntBase、BigIntAuditBase)。建议尽早统一基础策略,查询逻辑放在仓储/服务而非路由处理器中。
依赖注入与生命周期:SQLAlchemyInitPlugin 通过依赖注入提供引擎与会话,将引擎与会话工厂存入 app state,提供 before_send 处理器做请求生命周期清理,并支持 SQLAlchemy 注解的签名命名空间。
序列化与 DTO:SQLAlchemySerializationPlugin 会为使用 SQLAlchemy 模型的处理器数据与返回注解自动创建 DTO 类型(集合亦含),除非已提供显式 DTO。需更严格控制字段、嵌套或安全时使用显式 DTO。
Piccolo:通过 PiccoloDTO 支持以 Piccolo 为中心的 API 流程。定义 Piccolo Table 模型,使用 PiccoloDTO[Model] 做请求/响应塑形,用带 DTOConfig 的自定义子类处理部分更新与字段排除,例如:
class PatchDTO(PiccoloDTO[Task]): config = DTOConfig(exclude={"id"}, partial=True)
实施规则:事务显式且短小,业务完成处提交、失败路径回滚;仓储/服务不含 HTTP 传输关注点;会话归属确定;IO 密集场景优先异步 SQLAlchemy;避免盲目返回可能触发懒加载的 ORM 实体;入站与出站载荷都用 DTO 塑形以保护私有字段。
限制与校验:需确认插件策略匹配需求、异步/同步配置匹配运行时与驱动、迁移/模型元数据与运行时模型一致、会话注入与按请求清理可靠、异常回滚已测试、DTO 边界防止内部字段泄露、热点路径的 N+1 与懒加载问题已处理、列表端点具备确定性的过滤/排序/分页。数据未提供具体收费、价格或平台信息。