API 集成
适用于前端与后端边界的类型、错误、鉴权、上传、实时通信和用户状态设计。需要具体代码模式时加载 integration-patterns.md。
Purpose
规范前端 API 集成边界，让请求、错误、鉴权和实时数据可维护。
Procedure
-
明确接口所有权
- 同团队 TypeScript 全栈可考虑 tRPC 或共享 schema。
- 多语言或多消费者 API 优先 OpenAPI/GraphQL codegen。
- 小型内部应用可用 typed fetch wrapper，但类型必须集中维护。
- 不在组件里散落
fetch、URL、header、错误解析和 token 逻辑。 - 公共接口需要明确版本、兼容窗口、废弃字段策略和调用方范围。
-
建立客户端边界
- 用一个 API client 处理 base URL、credentials、JSON 解析、超时、取消和统一错误。
- 环境变量只读取公开前缀，私密 token 不进入客户端 bundle。
- 组件只消费 domain 函数或 query/mutation hook，不直接拼接接口路径。
- 204、空响应、非 JSON 错误和网络断开要有明确行为。
- TypeScript contract 必须覆盖请求、响应、错误形状和分页/游标元数据。
-
映射用户可理解的错误
- 401：刷新失败后引导登录。
- 403：说明权限不足，不重复重试。
- 404：展示缺失状态或返回上级入口。
- 409：提示冲突和下一步操作。
- 422：映射字段级错误。
- 429/5xx/网络错误：允许退避重试或展示稍后再试。
- 未识别错误要落到统一 fallback，不把原始后端异常暴露给用户。
- 所有错误都应归一到用户可恢复动作：重试、重新登录、修改输入、返回上级、联系支持或稍后再试。
- 错误对象要保留面向日志的 trace id / request id，但 UI 不暴露内部堆栈、SQL、服务名或敏感字段。
-
管理接口演进
- 兼容新增字段；删除或改名字段必须走迁移期、适配层或双写/双读策略。
- 用 schema、类型生成物或 contract test 捕捉破坏性变更。
- 对前后端协作项记录状态码、错误码、幂等性、重试语义和时区/金额/枚举规则。
-
处理鉴权刷新
- Access token 生命周期短，refresh 优先放在 httpOnly cookie 或服务端会话。
- 401 后只允许单次刷新队列，避免多个请求同时刷新。
- 刷新失败要清理本地身份状态并跳转登录。
- 不把 bearer token 放在 URL、localStorage 或日志里。
-
选择上传与实时方案
- 小文件可用 multipart；大文件优先预签名直传或分片上传。
- 只需要服务端推送时用 SSE；双向协作、聊天或多人状态用 WebSocket。
- 简单状态刷新、低频任务进度可用 polling，并设置停止条件。
- 上传和实时连接都需要取消、重连、超时和错误 UI。
-
验证集成质量
- 检查 loading、empty、error、unauthorized、offline、retrying 状态。
- 用浏览器网络面板确认 base URL、credentials、CORS 和状态码行为。
- 用 mock 或测试服务覆盖 401、403、422、500、断网和取消请求。
- 确认客户端 bundle 不包含私密环境变量、服务端密钥或内部地址。
- 对关键 API client 行为补最小测试，证明超时、取消、错误映射和刷新队列可预期。
- 验证错误边界与请求层协作：渲染异常进 Error Boundary，请求失败进可恢复 UI，不互相吞掉。
Constraints
- 不在页面组件中直接管理 token refresh、错误格式解析或重试策略。
- 不对 4xx 业务错误做盲目自动重试。
- 不把后端异常栈、内部错误码或原始 SQL/服务名暴露给用户。
- 不用 localStorage 存储高价值 token；若遗留系统无法避免，必须联动安全审查。
- 不用 WebSocket 替代简单轮询，也不用轮询实现高频双向协作。
- 不让上传经过 API 服务器转发大文件，除非有明确合规或扫描需求。
- 不在公共接口里直接暴露临时字段、数据库字段名或后端内部错误结构。
Expected Output
输出应包含 API client 边界、接口类型来源、错误映射、鉴权刷新策略、上传/实时方案和验证结果。完成后组件不散落请求细节，用户状态完整，失败场景可恢复，客户端不会泄露服务端密钥。