用途:为 Litestar 服务提供系统化的调试流程,目标是先复现问题、再定位失败层,最后修复根因并用回归测试固化。
主要能力:按执行工作流推进——用尽可能小的应用、路由或测试用例复现;先判断失败发生在请求、路由、依赖注入、中间件、认证、响应、异常处理还是生命周期层;只开启最低限度的安全诊断(本地 debug=True、聚焦日志或临时断言);检查行为偏离预期的边界;修复根因、移除临时诊断并添加回归测试;重跑相关测试并检查周边契约是否有回归。
使用方式:核心规则要求 debug=True 仅限本地使用;优先使用确定性日志、断言和聚焦复现应用,而非随手 print 调试;改代码前先缩小失败层;以请求和应用日志作为证据而非猜测;调试输出不得包含密钥和敏感载荷;根因明确后移除临时诊断;可行时用回归测试固化修复。决策指南建议:现有应用太大难以快速推理时用微型复现应用;可通过 HTTP 或 websocket 契约观察时用 litestar-testing 客户端;主要缺证据而非代码缺陷时用 litestar-logging;仅当本地 traceback 细节能实质缩短排查时才用 debug=True;失败子系统明确后交给更具体的 Litestar 技能。
参考文件:reproduction-and-isolation.md 讲复现策略、层隔离与临时诊断;subsystem-patterns.md 讲请求、认证、响应、异常与生命周期等常见子系统调试模式。
推荐默认:用最小路由和最小输入复现;一次只保留一个假设并快速验证;先加证据再改行为;用日志比较子系统边界的期望值与实际值;找到缺陷后把复现转成稳定测试。
反模式:修复后仍保留 debug=True 或啰嗦诊断;未隔离失败就同时改动多个子系统;用宽泛异常捕获掩盖症状;未复现精确契约就假定是请求、认证或响应缺陷;调试时记录密钥、令牌或原始敏感请求体。
校验清单:确认修复前可复现、修复后不再复现;确认正常路径与失败路径契约仍正确;确认临时与长期诊断都不泄露敏感值;确认回归测试在修复前失败、修复后通过;确认临时调试代码已移除。
跨技能交接:需要更好收集证据时用 litestar-logging;用 litestar-testing 固化复现并锁定修复;失败边界明确后用 litestar-requests、litestar-responses、litestar-exception-handling 或 litestar-authentication;运行时缺陷理解清楚且需要持续可见性后再用 litestar-metrics。
官方参考:https://docs.litestar.dev/latest/usage/debugging.html 和 https://docs.litestar.dev/latest/usage/testing.html。具体收费、价格与平台信息暂未提供。