用途:在前端网络边界建立类型安全纪律,让数据从网络进入应用时即成为可信的领域类型,失败则变成统一的类型化错误。可被 Claude Code、OpenCode、Codex、Cursor、Windsurf 等读取。
主要能力:1)一个客户端作为唯一 fetch 边界,组件与 hooks 不得直接调用 fetch/axios,可用 ESLint 规则强制;2)解析而非校验,在边界处把未知的 wire JSON 解析为领域类型,之后下游代码无需防御式判空;3)统一响应信封,成功为 { data },失败为 { error },由客户端解包并在错误时抛出;4)统一错误类型 ApiError,覆盖服务端错误信封、非 2xx 状态、畸形响应体、网络失败与中止,携带机器码、状态码与可选的逐字段错误;5)标识符品牌化,如 InvoiceId、CustomerId,编译期阻止混用,运行时成本为零。
目录结构:边界位于 src/shared/api-client/,包含 index.ts、client.ts、config.ts、error.ts、types.ts 与 client.test.ts;实体类型与 schema 放在各自功能模块的 types/ 或共享契约包中。
使用方式:在项目中创建 shared/api-client/,添加禁止在别处使用 fetch/axios 的 lint 规则,定义与后端一致的信封和错误码;新增实体时在功能模块定义 schema 与类型,在解析时品牌化 ID,并通过带类型的查询/变更 hooks 包装 apiClient,不在组件中直接调用客户端。库适配方面,TanStack Query 在 queryFn/mutationFn 调用客户端并在 onError 处理;RTK Query 用 baseQuery 包裹并配合 transformErrorResponse;SWR 用 fetcher 调用;React Native 不变,必要时把 credentials: "include" 换成 token 头。安装命令:npx skills add <org>/<repo> --skill "frontend-data-contracts"。
限制:该技能只描述网络边界纪律,不是状态库或样式系统;客户端保持框架无关,副作用(toast、重定向)放在查询层的 onError;不得从数据层 throw new Error(string),不得把 error.message 直接展示给用户,需经 messageKey 走 i18n;2xx 但响应体无法解析应抛契约违例错误而非静默返回 undefined。具体校验库可选 Zod、Valibot、ArkType、io-ts。关于收费、价格与平台支持等未在资料中提供。