litestar-responses

响应

执行工作流

1. 从符合契约的最简单返回形式开始：普通类型化数据、Response[T] 或专用响应容器。
2. 默认值不够时，显式设置状态码、媒体类型、标头和 Cookie。
3. 对重定向、文件、流、SSE、模板或第三方 ASGI 响应，选择专用响应类型。
4. 仅当多个处理器需要共享序列化或封套行为时，才应用响应类分层。
5. 验证类型化响应、仅用于文档的标头和 Cookie、空响应体状态码，以及专用响应容器的 OpenAPI 准确性。

核心规则

• 对标准 JSON 响应，优先使用普通类型化返回值。
• 需要在运行时控制标头、Cookie、后台任务或状态码时，使用 Response[T]。
• 为响应类指定精确的泛型参数，确保架构生成准确。
• 如果客户端依赖运行时标头和 Cookie，就对其进行文档说明，尤其是值动态设置时。
• 将 204、304 和其他无响应体的响应视为返回 None 的契约。
• 如果 API 使用共享契约，请确保成功响应封套与异常处理响应封套保持一致。
• 使用专用响应容器，而非手动重新实现文件、重定向、流或 SSE 行为。
• 有意且局部地应用分层的 response_class、response_headers 和 response_cookies 覆盖。

选择指南

• Litestar 默认行为已符合契约时，返回普通数据。
• 负载正常但元数据是动态的时，返回 Response[T]。
• 多个端点需要相同的序列化策略时，使用 response_class=。
• 封装第三方 ASGI 响应对象或实现自定义底层行为时，返回 ASGIApp。
• 传输语义特殊时，使用 File、Stream、ServerSentEvent 或重定向响应。
• 对进程内客户端无法良好模拟的实时服务端场景，使用子进程测试客户端，尤其是无限 SSE 流。

参考文件

只阅读所需章节：

• 关于普通类型化返回值、Response[T]、状态码、分层的 response_class、自定义响应类和后台任务，请阅读 references/response-basics.md。
• 关于标头、Cookie、重定向、文件、流、SSE、模板和 ASGI 应用返回值，请阅读 references/response-containers.md。

推荐默认做法

• 除非需要传输层控制，否则让 Litestar 序列化普通 JSON 返回值。
• 在代码和测试中使用 litestar.status_codes 中的状态码常量。
• 使用 documentation_only=True 元数据记录动态标头和 Cookie，并在响应或钩子中设置运行时值。
• 确保流和 SSE 生成器可安全取消，并根据断开连接行为限制其运行。
• 明确文件传输和重定向行为，确保中间层和客户端的行为可预测。

反模式

• 到处返回 Response[Any]，导致架构精度丢失。
• 在普通 Response[T] 或内置容器已足够时，仍使用自定义响应类。
• 为 204 No Content 端点返回响应体。
• 如果客户端依赖动态标头或 Cookie，却不在 OpenAPI 中记录它们。
• 仅使用进程内客户端测试无限流或 SSE 行为。
• 手动重新实现文件服务，而不使用 File。

验证清单

• 确认返回注解与实际响应正文和状态码一致。
• 确认空正文响应使用 None 注解和正文。
• 确认分层的 response_class、response_headers 和 response_cookies 优先级符合预期。
• 如果客户端依赖动态标头和 Cookie，确认已对其进行说明。
• 确认流式响应、SSE、重定向和文件响应使用了预期的媒体类型和传输行为。
• 确认后台任务仅在响应正文发送完毕后运行。
• 确认自定义响应类或容器变更后，OpenAPI 输出仍然准确。
• 确认响应文档与 litestar-openapi 元数据和示例保持一致。

跨技能交接

• 使用 litestar-exception-handling 设计错误封装和失败响应。
• 如果响应变更会显著影响架构输出，请使用 litestar-openapi。
• 如需深入了解模板引擎相关事项，请使用 litestar-templating。
• 使用 litestar-testing 对状态码、标头、Cookie、流式响应、重定向和 SSE 行为进行断言。

Litestar 参考资料

• https://docs.litestar.dev/latest/usage/responses.html
• https://docs.litestar.dev/latest/reference/response/index.html
• https://docs.litestar.dev/latest/usage/testing.html