litestar-middleware

中间件

执行工作流

1. 确认该需求确实适合由中间件处理：应是广泛的 ASGI 封装，而非路由业务逻辑。
2. 优先使用基于配置的内置中间件。
3. 谨慎选择合适的层级和顺序。
4. 判断相关功能应归属于中间件、生命周期钩子还是路由逻辑。
5. 对于自定义中间件，选择最简单且正确的实现方式。
6. 验证成功响应和异常生成的响应，并检查排除项及作用域处理。

核心规则

• 让中间件专注于一个横切关注点。
• 创建自定义实现前，优先考虑内置中间件或配置对象。
• 将中间件顺序视为 API 行为的一部分。
• 根据需要，让中间件支持 http、websocket 和 lifespan 作用域。
• 如果任务是修改响应对象，而非封装 ASGI 消息，则使用生命周期钩子。
• 确保中间件非阻塞且符合 ASGI 规范。
• 明确说明对 404 和 405 的预期，因为这些由路由器生成的异常发生在中间件栈之前。

决策指南

• 对于 CORS、CSRF、压缩、速率限制、日志记录、会话和允许的主机，使用内置配置中间件。
• 对于非常小的封装，使用中间件工厂。
• 对于可配置的生产环境自定义中间件，使用 ASGIMiddleware。
• 对于最精简的底层行为，使用 MiddlewareProtocol。
• 仅在兼容性或迁移场景中使用 AbstractMiddleware。
• 当需要向中间件工厂或类传入构造函数风格的参数时，使用 DefineMiddleware。
• 如果行为属于 after_request、before_send 或相关钩子阶段，则改用 litestar-lifecycle-hooks。

参考文件

只阅读所需章节：

• 有关中间件基础、顺序、排除项和内置中间件选择，请阅读 references/builtin-and-ordering.md。
• 有关自定义中间件实现方式、ASGIMiddleware、MiddlewareProtocol、AbstractMiddleware 和 DefineMiddleware，请阅读 references/custom-middleware-patterns.md。

建议的默认做法

• 每次先从一个中间件关注点入手。
• 明确设置并审查内置配置值。
• 将排除项和基于 opt 的跳过范围限定得足够小，并进行测试。
• 只有在顺序假设确实不明显时，才在代码注释中说明。
• 同时针对成功和失败的下游处理程序测试中间件。

反模式

• 将特定路由的业务规则放入中间件。
• 在内置配置或生命周期钩子已适用时，仍创建自定义中间件。
• 多个封装相互作用时忽略中间件顺序。
• 在错误的 ASGI 阶段修改请求或响应状态。
• 假设路由器生成的 404 和 405 会经过中间件。
• 让中间件隐式依赖未记录的 opt 排除项或路径模式。

验证清单

• 确认中间件只附加在预期的层级。
• 确认顺序同时符合层级优先级和列表顺序。
• 确认通过路径模式、exclude_opt_key 或作用域设置的排除项按预期生效。
• 确认成功响应和异常生成的响应均能正确处理。
• 确认在正确的边界处理 404 和 405。
• 确认自定义中间件仍符合 ASGI 规范且非阻塞。
• 确认内置安全和日志记录中间件的设置符合部署预期。

跨技能衔接

• 对于钩子阶段的逻辑，使用 litestar-lifecycle-hooks，而不是原始 ASGI 封装。
• 对于特定领域的中间件结果，使用 litestar-authentication、litestar-security、litestar-logging 和 litestar-metrics。
• 如果中间件交互是运行时缺陷的根源，使用 litestar-debugging。
• 如果中间件行为取决于层级放置或 opt 策略，使用 litestar-routing。

Litestar References

• https://docs.litestar.dev/latest/usage/middleware/index.html
• https://docs.litestar.dev/latest/usage/middleware/using-middleware.html
• https://docs.litestar.dev/latest/usage/middleware/builtin-middleware.html
• https://docs.litestar.dev/latest/usage/middleware/creating-middleware.html