用途:当 Litestar 应用需要插件驱动行为,或任务涉及通过插件、DTO 工厂、OpenAPI schema 插件集成的模型生态时使用。需先判断问题是真正需要实现 Litestar 插件协议,还是仅需生态的 DTO/OpenAPI 集成,并选择最小可用面。
核心插件协议:InitPlugin 通过 on_app_init(self, app_config: AppConfig) -> AppConfig 做应用组合与启动配置,运行在 on_app_init 钩子之后并按 plugins=[...] 顺序执行,适合注入依赖、注册路由与中间件。SerializationPluginProtocol 实现 supports_type 与 create_dto_for_type,仅在注解受支持且未显式声明 dto / return_dto 时自动生成 DTO。DIPlugin 实现 has_typed_init 与 get_typed_init,用于构造函数类型信息不可直接恢复的场景。ReceiveRoutePlugin 实现 receive_route(route: BaseRoute) -> None,仅做路由观察与注册期副作用。OpenAPISchemaPluginProtocol 实现 is_plugin_supported_type 与 to_openapi_schema,只负责 schema 生成。
生态集成:SQLAlchemy 可选 SQLAlchemyPlugin(完整)、SQLAlchemyInitPlugin(会话/引擎与 DI)、SQLAlchemySerializationPlugin(自动 SQLAlchemyDTO),并用 SQLAlchemyDTO[Model] 显式控制契约;配置使用 SQLAlchemyAsyncConfig 或 SQLAlchemySyncConfig,同步处理器一般设 sync_to_thread=True,可用 engine_dependency_key / session_dependency_key 与 before_send_handler 调整。Piccolo 以 PiccoloDTO[Table] 作为 DTO 集成,PATCH 用 DTOConfig(exclude={"id"}, partial=True) 搭配 DTOData[Table].update_instance()。Pydantic 提供 PydanticPlugin、PydanticInitPlugin、PydanticDIPlugin、PydanticDTO[T]、PydanticSchemaPlugin,常见选项包括 exclude、include、exclude_defaults、exclude_none、exclude_unset、prefer_alias、validate_strict、round_trip。dataclass 用 DataclassDTO,msgspec 用 MsgspecDTO,attrs 主要是 AttrsSchemaPlugin 与 is_attrs_class()。TypedDict 无专用插件页,按类型/schema 处理。
用法与限制:只实现所需协议,保持插件顺序确定且可审阅,避免 import 期副作用;当 API 契约与领域模型不同时优先显式 DTO,不要在同一 API 边界混用多个模型/序列化生态。注意最新文档与旧链接布局差异较大,旧 usage/plugins/*.html URL 部分已返回 404;PydanticPlugin 不替代显式 DTO,attrs 也不假设存在完整序列化插件。缺失事实(如收费、价格、平台、效果、使用步骤)暂未提供。