api-integration

api-integration 技能为后端 OpenAPI 规格与 React 前端架构之间提供了一个强大的桥梁。通过利用 apidog-mcp-server，它为 API 定义建立了单一事实来源，确保 AI 代理程序生成准确且类型安全的代码，并与后端保持同步。此技能专为优先考虑可维护性并希望消除编写 HTTP 请求、类型定义与复杂数据获取逻辑之琐碎工作（boilerplate）的工程团队而设计。

• 自动化类型生成：与 openapi-typescript 和 orval 整合，直接从 OpenAPI 3.0/3.1 规格产生精确的 TypeScript 接口，减少执行时期错误与 schema 不匹配的情况。

• 查询层编排：使用 TanStack Query 钩子实现结构化的文件夹模式（queries/mutations），包含查询键（query key）工厂、缓存配置与 stale time 管理，以优化数据获取效率。

• 韧性 HTTP 客户端：配置基于 axios 的客户端，包含用于自动 JWT/Bearer Token 管理与 Token 更新流程的拦截器（interceptors），可妥善处理 401 错误以维持会话持久性。

• 基于 MCP 的配置：通过 .claude/mcp.json 支持动态配置，使代理程序能够读取基于本地文件的规格或远程 URL，并通过平行的 MCP 服务器定义支持多 API 项目。

• 设置项目时，请在 MCP 配置中定义 API 规格来源（URL 或本地路径），以确保代理程序拥有对 schema 的读取权限。

• 依照建议的 types.ts、client.ts 以及基于功能的 query/mutation 文件模式，在 /src/api 目录中组织 API 相关代码。

• 结合 Zod schemas 与 OpenAPI 定义，为来自后端的数据提供执行时期的验证。

• 代理程序能够适应各种身份验证策略；请确保客户端拦截器已针对您的特定身份验证中间件需求进行调整。

• 对于大型 API，请依赖 orval 等自动化代码生成工具，而非手写类型，以最大程度减少 API 合约与前端实现之间的落差。