用途:为 Litestar 应用建立一致的异常处理与错误响应契约,区分启动/配置失败与请求期失败,并选择恰当的错误表达方式。
主要能力:判断应直接抛出 HTTPException(或其子类,如 401、403、404、429、503),还是通过 exception_handlers 把领域异常或库异常映射为传输安全的响应;支持按异常类映射、按状态码映射,以及在 app、router、controller、route handler 层做分层覆盖。文档还给出内置异常子类、HTTPException 构造行为、校验警告、headers、extra 与 WebSocket 相关异常、状态码映射、纯文本与 JSON 响应等参考章节。
使用方式:按需阅读参考文件 references/built-in-exceptions.md 与 references/handler-patterns.md;处理器注册尽量靠近拥有该行为的层,但 404 Not Found 与 405 Method Not Allowed 必须在 app 实例上注册。建议统一 JSON 错误信封,500 对客户端保持通用、详情写入日志,业务异常用类映射,通用回退用应用级状态码映射。
适用场景:需要稳定错误负载结构、分层覆盖、校验错误脱敏、中间件与依赖异常统一契约的 Litestar 项目;认证 401/403 策略、响应格式化、测试失败路径、OpenAPI 错误文档、异常日志脱敏等可交接给相应技能。
限制与注意:不得用宽泛 catch-all 掩盖根因,不得返回原始异常文本或将校验内部细节、堆栈类信息暴露给客户端,不得把相同错误信封无理由拆到多个处理器,不得在应用层以下定制 404/405,也不应把授权策略写进通用异常处理器。具体代码示例与安装命令暂未提供。