用途:当需求聚焦 HTTP 处理器的请求—响应用生命周期(而非应用启动引导或整体 ASGI 包装)时使用本技能。
主要能力:
- before_request:在路由处理器调用前运行,接收 Request,返回 None 或任意可作响应的值;返回非 None 会绕过处理器,适合请求增强、条件短路与写入 request.state 的请求级标记。
- after_request:在处理器返回并解析出 Response 后运行,接收 Response 且必须返回 Response,可原地修改或替换响应,适合响应归一化、补充元数据与响应类型转换。
- after_response:在响应已发送后运行,接收 Request,返回 None,无法影响已发送的响应,适合发送后指标、计数、审计与外部通知。
分层模型:钩子可定义在 app、router、controller 或 handler 层;同一钩子出现在多层时,最靠近处理器的层优先,属于覆盖而非叠加。
使用方式:先按需求确定阶段,再有意识地选择放置层,保持钩子小而确定、面向横切关注点;before_request 可通过 request.state 向处理器传递数据,除非有意短路否则返回 None;after_request 优先修改现有响应;after_response 副作用需可安全重复执行。需显式测试正常流程、短路流程与层级优先级。
适用场景:请求门控、请求状态增强、提前返回 HTTP 结果、响应头与内容整形、发送后埋点与审计。
限制与边界:领域规则应放入服务或处理器,不要藏在钩子里;需要原始 ASGI scope/receive/send、跨路由组包装或 WebSocket/生命周期覆盖时改用中间件;before_send、after_exception、on_app_init、启动/关闭等应使用应用引导技能;解耦的进程内副作用宜用事件机制。
参考:https://docs.litestar.dev/latest/usage/lifecycle-hooks.html https://docs.litestar.dev/latest/usage/middleware/index.html https://docs.litestar.dev/latest/usage/middleware/using-middleware.html