yuxuanhui
40 lines
1.8 KiB
Markdown
40 lines
1.8 KiB
Markdown
# 跨层契约思考指南
|
||
|
||
本仓库的最小链路是：
|
||
|
||
```text
|
||
FastAPI 路由
|
||
→ Pydantic response model
|
||
→ 同源 /api/v1 代理
|
||
→ requestJson<T>
|
||
→ feature *.types.ts / *.api.ts
|
||
→ React Query hook
|
||
→ 页面加载、错误、成功状态
|
||
```
|
||
|
||
以系统状态为例，链路对应：
|
||
|
||
- 后端：`interfaces/http/router.py` 挂载 `/api/v1/system/status`，`interfaces/http/system.py` 返回 `SystemStatusResponse`。
|
||
- 后端测试：`tests/test_system_http.py` 断言状态码和完整 JSON。
|
||
- 前端：`features/system/api/system.api.ts` 使用 `/api/v1/system/status`，`system.types.ts` 描述字段，`system.query.ts` 管理缓存。
|
||
- 页面测试：`system-status-page.test.tsx` 断言“运行正常”和环境文本。
|
||
|
||
## 修改 HTTP 字段前
|
||
|
||
1. 找到后端响应模型、路由和现有契约测试。
|
||
2. 找到 feature API 函数、TypeScript 类型、query hook 和页面分支。
|
||
3. 确认开发 Vite 代理和生产 Nginx 仍覆盖该路径；浏览器代码保持同源路径。
|
||
4. 同步更新后端 HTTP 测试和前端行为测试，再运行两端质量命令。
|
||
|
||
## 常见跨层遗漏
|
||
|
||
- 只修改 Pydantic 字段，没有修改 `*.types.ts`，导致 UI 仍读取旧形状。
|
||
- 把 `/api/v1` 改成后端绝对 URL，绕过 `vite.config.ts` 和 Nginx 的同源代理。
|
||
- 在页面内直接 `fetch`，绕过 `requestJson` 的 `ApiError` 和 `AbortSignal`。
|
||
- 用 Zustand 缓存服务器响应，造成 React Query 缓存与全局 store 的双重事实来源。
|
||
- 只测试请求成功，没有测试 `isPending`、`isError` 或字段缺失时的安全展示。
|
||
|
||
## 边界验证
|
||
|
||
提交前至少回答：输入在哪里解析？错误在哪里转换？状态由谁拥有？字段是否在后端、客户端类型和 UI 测试中一致？如果答案不清楚，先补充契约或拆分边界，再实现功能。
|