API 集成

适用于前端与后端边界的类型、错误、鉴权、上传、实时通信和用户状态设计。需要具体代码模式时加载 integration-patterns.md。

用途

规范前端 API 集成边界，让请求、错误、鉴权和实时数据可维护。

流程

1. 明确接口所有权

   • 同团队 TypeScript 全栈可考虑 tRPC 或共享 schema。
   • 多语言或多消费者 API 优先 OpenAPI/GraphQL codegen。
   • 小型内部应用可用 typed fetch wrapper，但类型必须集中维护。
   • 不在组件里散落 fetch、URL、header、错误解析和 token 逻辑。
   • 公共接口需要明确版本、兼容窗口、废弃字段策略和调用方范围。

2. 建立客户端边界

   • 用一个 API client 处理 base URL、credentials、JSON 解析、超时、取消和统一错误。
   • 环境变量只读取公开前缀，私密 token 不进入客户端 bundle。
   • 组件只消费 domain 函数或 query/mutation hook，不直接拼接接口路径。
   • 204、空响应、非 JSON 错误和网络断开要有明确行为。
   • TypeScript contract 必须覆盖请求、响应、错误形状和分页/游标元数据。

3. 映射用户可理解的错误

   • 401：刷新失败后引导登录。
   • 403：说明权限不足，不重复重试。
   • 404：展示缺失状态或返回上级入口。
   • 409：提示冲突和下一步操作。
   • 422：映射字段级错误。
   • 429/5xx/网络错误：允许退避重试或展示稍后再试。
   • 未识别错误要落到统一 fallback，不把原始后端异常暴露给用户。
   • 所有错误都应归一到用户可恢复动作：重试、重新登录、修改输入、返回上级、联系支持或稍后再试。
   • 错误对象要保留面向日志的 trace id / request id，但 UI 不暴露内部堆栈、SQL、服务名或敏感字段。

4. 管理接口演进

   • 兼容新增字段；删除或改名字段必须走迁移期、适配层或双写/双读策略。
   • 用 schema、类型生成物或 contract test 捕捉破坏性变更。
   • 对前后端协作项记录状态码、错误码、幂等性、重试语义和时区/金额/枚举规则。

5. 处理鉴权刷新

   • Access token 生命周期短，refresh 优先放在 httpOnly cookie 或服务端会话。
   • 401 后只允许单次刷新队列，避免多个请求同时刷新。
   • 刷新失败要清理本地身份状态并跳转登录。
   • 不把 bearer token 放在 URL、localStorage 或日志里。

6. 选择上传与实时方案

   • 小文件可用 multipart；大文件优先预签名直传或分片上传。
   • 只需要服务端推送时用 SSE；双向协作、聊天或多人状态用 WebSocket。
   • 简单状态刷新、低频任务进度可用 polling，并设置停止条件。
   • 上传和实时连接都需要取消、重连、超时和错误 UI。

7. 验证集成质量

   • 检查 loading、empty、error、unauthorized、offline、retrying 状态。
   • 用浏览器网络面板确认 base URL、credentials、CORS 和状态码行为。
   • 用 mock 或测试服务覆盖 401、403、422、500、断网和取消请求。
   • 确认客户端 bundle 不包含私密环境变量、服务端密钥或内部地址。
   • 对关键 API client 行为补最小测试，证明超时、取消、错误映射和刷新队列可预期。
   • 验证错误边界与请求层协作：渲染异常进 Error Boundary，请求失败进可恢复 UI，不互相吞掉。

约束

• 不在页面组件中直接管理 token refresh、错误格式解析或重试策略。
• 不对 4xx 业务错误做盲目自动重试。
• 不把后端异常栈、内部错误码或原始 SQL/服务名暴露给用户。
• 不用 localStorage 存储高价值 token；若遗留系统无法避免，必须联动安全审查。
• 不用 WebSocket 替代简单轮询，也不用轮询实现高频双向协作。
• 不让上传经过 API 服务器转发大文件，除非有明确合规或扫描需求。
• 不在公共接口里直接暴露临时字段、数据库字段名或后端内部错误结构。

预期输出

输出应包含 API client 边界、接口类型来源、错误映射、鉴权刷新策略、上传/实时方案和验证结果。完成后组件不散落请求细节，用户状态完整，失败场景可恢复，客户端不会泄露服务端密钥。