用途:当请求与响应载荷需要显式控制字段结构、字段级策略或自定义 DTO 工厂时使用本技能,处理 Litestar 的入站解析与出站序列化。
主要能力:每个应用层级提供两个 DTO 参数——dto 用于入站解析,未设 return_dto 时也用于出站;return_dto 仅控制出站序列化。DTO 可声明在 handler、controller、router 或 application 上,按最接近 handler 的层级生效。常用模式为 dto=WriteDTO 解析入站、return_dto=ReadDTO 序列化出站,或将 return_dto=None 关闭序列化(如 DELETE 返回 None)。
DTOConfig 策略:支持 exclude(可含嵌套路径如 "pets.0.id")、rename_fields、rename_strategy="camel" 或回调、max_nested_depth、forbid_unknown_fields=True、partial=True(适配 PATCH)、leading_underscore_private、experimental_codegen_backend。显式 rename_fields 映射不再被 rename_strategy 二次转换。
字段标记:用 dto_field(...) 标记字段语义,"private" 既不解析也不序列化,"read-only" 不解析入站数据;下划线开头的字段默认隐式私有。
DTOData[T]:用于创建与更新流程,data.create_instance(...) 可从校验后输入创建实例并注入服务端值,嵌套值可用双下划线路径(如 address__id=...)传入;data.update_instance(existing) 在 partial=True 时支持部分更新,PATCH 模式常先排除不可变字段(如 id)。
包装器:DTO 工厂可转换受支持的包装器内数据,包括泛型 dataclass 包装器(如 WithCount[T])、Litestar 分页包装器(如 ClassicPagination[T] 作用于 items)、Response[T](作用于 content)。
性能:DTO codegen 后端自 2.2.0 引入,2.8.0 起稳定并默认启用,可用 DTOConfig(experimental_codegen_backend=...) 按 DTO 切换,仅在调试兼容性或行为差异时选择性覆盖。
自定义 DTO:优先使用内置工厂,仅当现有工厂加 DTOConfig 无法表达所需行为时实现自定义 DTO,需实现 AbstractDTO 的 generate_field_definitions(model_type) 与 detect_nested_field(field_definition)。内置工厂包括 DataclassDTO、SQLAlchemyDTO 及插件提供的 DTO。
实施与检查:读写 DTO 策略不同时应分开;配置显式可审,避免隐式字段暴露;嵌套序列化深度应作为 API 与性能控制手段;严格接口可启用 forbid_unknown_fields=True;用 DTO 强制不可变与服务端字段;保持 handler 聚焦业务逻辑。检查项包括 dto/return_dto 是否按 handler 有意选择或禁用、层级优先级是否意外覆盖 handler 意图、exclude/rename/嵌套配置是否生成预期载荷、未知字段行为是否符合严格度、私有/只读/下划线字段是否可被客户端写入、PATCH 是否使用 partial=True 与 DTOData.update_instance()、包装器响应是否仍应用 DTO 转换、OpenAPI 输出是否与 DTO 契约一致。
相关参考文档:https://docs.litestar.dev/2/usage/dto/index.html、https://docs.litestar.dev/2/usage/dto/0-basic-use.html、https://docs.litestar.dev/2/usage/dto/1-abstract-dto.html、https://docs.litestar.dev/2/usage/dto/2-creating-custom-dto-classes.html。
限制:本资料未提供收费、价格与平台相关信息。