# Fec API Integration

> 用于设计、实现或审查前后端 API 集成、类型化 API client、REST/tRPC/OpenAPI 客户端选型、认证刷新、API 错误映射、上传流程、SSE/WebSocket/轮询选择、CORS 相关前端行为或跨边界 loading/error 状态。不要用于纯后端服务架构或仅 TanStack Query 缓存策略；中文触发词包括 API 集成、前后端联调、typed API client、接口错误处理、SSE、WebSocket。

- Skill: `majiayu000/fec-api-integration-2` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add majiayu000/fec-api-integration-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/fec-api-integration-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/majiayu000/fec-api-integration-2

---


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