用途:在 Litestar 中构建类型正确的响应,涵盖从普通 JSON 返回、Response[T] 容器,到文件、流、SSE、重定向、模板和第三方 ASGI 响应的选择与配置,并确保 OpenAPI 输出准确。
主要能力:1) 返回值选择——若默认序列化匹配契约就用普通类型化数据;需要运行时控制头、Cookie、后台任务或状态码时用 Response[T];需要统一序列化策略时用分层 response_class;包装第三方 ASGI 或低层行为时返回 ASGIApp。2) 显式设置状态码、媒体类型、头与 Cookie。3) 专用响应类型处理重定向、文件、流、SSE、模板。4) 用法规则:保持响应类泛型参数精确以维护 schema;动态头/Cookie 用 documentation_only=True 标注并在响应或钩子中设值;204、304 等无主体响应应返回 None 契约;成功信封与异常处理信封保持一致;流与 SSE 生成器需可取消并由断连行为约束;文件与重定向行为显式化。5) 验证清单:确认注解与主体、状态码一致;空主体用 None;分层 response_class、response_headers、response_cookies 优先级符合预期;流/SSE/重定向/文件媒体类型正确;后台任务在主体发送后运行;OpenAPI 保持准确。
使用方式:按需查阅 reference 文件——response-basics.md 涵盖类型化返回、状态码、分层 response_class、自定义类与后台任务;response-containers.md 涵盖头、Cookie、重定向、文件、流、SSE、模板与 ASGI 返回。建议使用 litestar.status_codes 的状态码常量;无限 SSE 流等场景可用子进程测试客户端。
适用场景:需要按契约精确控制 API 响应语义的 Litestar 项目,尤其是涉及文件、流、SSE、重定向和统一序列化策略的接口。
限制:资料未提供安装命令、价格、平台信息或具体代码示例;未提及收费情况。反模式包括处处返回 Response[Any]、过度使用自定义响应类、为 204 返回主体、动态头未文档化、仅用进程内客户端测试无限流等。