fec-api-integrationlisted

# API 集成 适用于前端与后端边界的类型、错误、鉴权、上传、实时通信和用户状态设计。需要具体代码模式时加载 [integration-patterns.md](references/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、offl