yuxuanhui
25 lines
1.9 KiB
Markdown
25 lines
1.9 KiB
Markdown
# 错误处理
|
|
|
|
## 当前行为
|
|
|
|
服务目前没有自定义异常层、全局异常处理器或统一错误 envelope。FastAPI/Pydantic 负责请求验证和标准 HTTP 错误响应；现有成功端点只返回声明过的响应模型。新增错误契约前，应先确认前端是否需要稳定的错误字段，并用 HTTP 契约测试锁定它。
|
|
|
|
## 分层规则
|
|
|
|
- 在 HTTP 边界完成输入解析和验证，不要把 `Request`、`HTTPException` 或 FastAPI 依赖对象带入 domain。
|
|
- 领域或应用层的业务失败应使用可识别的领域异常（当该层实际出现时），由 presentation 层映射为 HTTP 响应；不要在 domain 层导入 FastAPI。
|
|
- 不能恢复的配置错误应在启动时暴露，而不是在每个端点里静默使用空值。`Settings` 的类型和默认值应让错误尽早发生。
|
|
- 不要捕获 `Exception` 后返回成功、空对象或吞掉 traceback。只有在能补充上下文、转换边界错误或保证资源清理时才捕获具体异常。
|
|
|
|
## 前端边界
|
|
|
|
`zhixing-web/src/shared/api/request-json.ts:requestJson` 对非 2xx 响应抛出 `ApiError`，并保留 HTTP 状态码；React Query 通过 `isError` 将其传给 feature 页面。页面应显式渲染加载、错误和成功状态，参照 `features/system/pages/system-status-page.tsx`，不要把错误静默成“无数据”。
|
|
|
|
当前 `requestJson` 只对响应体做泛型断言，不做运行时 schema 校验。因此来自外部或不稳定来源的数据在进入页面前必须增加明确的运行时校验，不能把 TypeScript 类型当成网络验证。
|
|
|
|
## 测试要求
|
|
|
|
- 对新增 HTTP 错误状态，优先在 `zhixing-server/tests/` 验证状态码和 JSON 契约。
|
|
- 对前端错误展示，在页面测试中 mock query hook 的 `isError`/`error` 状态并断言用户可见文本。
|
|
- 不要只测试异常类被抛出而不测试边界响应或用户行为。
|