2026-08-04 18:59:21 +08:00
|
|
|
# 代码复用思考指南
|
2026-08-04 16:47:58 +08:00
|
|
|
|
2026-08-04 18:59:21 +08:00
|
|
|
## 什么时候先搜索
|
2026-08-04 16:47:58 +08:00
|
|
|
|
2026-08-04 18:59:21 +08:00
|
|
|
在创建 helper、常量、转换函数或新的 UI primitive 前，先搜索这些本地模式：
|
2026-08-04 16:47:58 +08:00
|
|
|
|
|
|
|
|
```bash
|
2026-08-04 18:59:21 +08:00
|
|
|
rg "requestJson|ApiError" zhixing-web/src
|
|
|
|
|
rg "QueryKey|queryKey|useQuery" zhixing-web/src
|
|
|
|
|
rg "className|cva\(|cn\(" zhixing-web/src/shared zhixing-web/src/features
|
|
|
|
|
rg "create_app|response_model|Depends\(" zhixing-server/src zhixing-server/tests
|
2026-08-04 16:47:58 +08:00
|
|
|
```
|
|
|
|
|
|
2026-08-04 18:59:21 +08:00
|
|
|
当前仓库已经有明确的复用点：
|
2026-08-04 16:47:58 +08:00
|
|
|
|
2026-08-04 18:59:21 +08:00
|
|
|
- 网络 JSON 请求统一经 `zhixing-web/src/shared/api/request-json.ts`，不要在页面重新实现 `fetch` 和错误判断。
|
|
|
|
|
- Tailwind class 合并统一经 `zhixing-web/src/shared/ui/utils.ts:cn`；有限变体用 `cva`，参照 `button.tsx` 和 `badge.tsx`。
|
|
|
|
|
- 服务端应用组合统一经 `zhixing-server/src/zhixing_server/bootstrap/app.py:create_app`，测试也调用真实工厂。
|
|
|
|
|
- React Query key 以 feature 内 `as const` 常量维护，参照 `system.query.ts`。
|
2026-08-04 16:47:58 +08:00
|
|
|
|
2026-08-04 18:59:21 +08:00
|
|
|
## 复用与边界
|
2026-08-04 16:47:58 +08:00
|
|
|
|
2026-08-04 18:59:21 +08:00
|
|
|
- 只有跨 feature、无业务所有权的能力才进入 `shared/`；一次性页面逻辑留在 feature。
|
|
|
|
|
- 看到两处相似代码时，先确认输入、错误语义和生命周期是否真的相同，再抽象；不要为了消除两行重复创建泛化框架。
|
|
|
|
|
- API 类型和领域概念不能因为“看起来相同”就自动合并。后端 Pydantic 模型、feature TypeScript 类型和 UI view model 各自承担边界责任。
|
2026-08-04 16:47:58 +08:00
|
|
|
|
2026-08-04 18:59:21 +08:00
|
|
|
## 验证问题
|
2026-08-04 16:47:58 +08:00
|
|
|
|
2026-08-04 18:59:21 +08:00
|
|
|
- 新 helper 是否能被现有测试直接覆盖？
|
|
|
|
|
- 抽象后是否让导入方向更清楚，而不是引入 shared → feature 反向依赖？
|
|
|
|
|
- 是否保留了 `AbortSignal`、错误状态、可访问性和类型约束等原有行为？
|
