前端数据契约（类型化网络边界）

在需要可移植、与框架无关的类型安全方法来处理任何 React 或 React Native 应用的网络边缘时，使用此技能。建立一个类型化的 API 客户端作为唯一的 fetch 边界，一个解析而非验证的规则，将网络 JSON 转换为受信任的域类型，然后再进入应用，一个单一的...

目标：当数据从网络传入应用程序的那一刻，它就不再是 any 形状的线了

JSON 并变成一个可信的、类型化的域值——或者变成一个单一的、类型化的错误。

这种转换正好发生在一个地方，且没有未类型化的东西会从中逃逸。

边界是 shared/ 中的一个文件夹（根据前端架构技能）。

src/shared/api-client/
├── index.ts        ← barrel: apiClient, ApiError, types
├── client.ts       ← the fetch wrapper: buildUrl, headers, parse, verbs
├── config.ts       ← base URL resolution, default headers
├── error.ts        ← the ApiError class + code→message-key mapping
├── types.ts        ← envelope types, HttpMethod, RequestOptions, field errors
└── client.test.ts  ← boundary behavior tests (envelope, errors, network)

域实体类型及其模式与其功能模块一起存在

(modules/{feature}/types/) 或一个共享的契约包；客户端是针对 T 的通用型。

2. 一个客户端，唯一的获取边界

每个动词都会返回调用者类型化的未包装 data 有效载荷，并且抛出一个

任何失败都会返回 ApiError。组件从未见过信封或原始响应。

// shared/api-client/client.ts (essence)
export const apiClient = {
  get<T>(path: string, options?: RequestOptions): Promise<T> {
    return request<T>("GET", path, undefined, options);
  },
  post<T>(path: string, body?: unknown, options?: RequestOptions): Promise<T> {
    return request<T>("POST", path, body, options);
  },
  patch<T>(path: string, body?: unknown, options?: RequestOptions): Promise<T> {
    /* … */
  },
  put<T>(path: string, body?: unknown, options?: RequestOptions): Promise<T> {
    /* … */
  },
  delete<T>(path: string, options?: RequestOptions): Promise<T> {
    /* … */
  },
} as const;

export type ApiClient = typeof apiClient;

// CORRECT — a feature hook wraps the client, typed by the caller
const invoice = await apiClient.get<Invoice>(`/invoices/${id}`, { signal });

// WRONG — a raw fetch in a component bypasses the boundary entirely
const res = await fetch(`/api/invoices/${id}`); // untyped, unhandled errors, no envelope

3. 解析，不要验证（边界变换）

“Validate” 给你相同的无类型值和一个布尔值。 “Parse” 返回一个新的，有类型的

value — 因此下游代码由类型系统保证是正确的。在以下位置运行模式解析

界限；在那之后，数值被信任。

// modules/invoice/types/invoice.schema.ts
import { z } from "zod";

export const invoiceSchema = z.object({
  id: z.string().transform(toInvoiceId), // brand it (see §5)
  number: z.string(),
  status: z.nativeEnum(InvoiceStatus),
  total: z.number().int(), // minor units — never float money
  issuedAt: z.string().datetime(),
});
export type Invoice = z.infer<typeof invoiceSchema>;

// the client (or a thin per-entity wrapper) parses at the edge
const raw = await apiClient.get<unknown>(`/invoices/${id}`, { signal });
return invoiceSchema.parse(raw); // throws on contract drift → surfaces as a typed failure

为什么这很重要： 一个重命名字段或发送不该为 null 的后端会在 时被发现

边界，出现明显错误，而不是在三个组件深度处产生 undefined

堆栈跟踪毫无用处。下游组件从不防御性地写 invoice?.total ?? 0。

在客户端镜像后端的单个信封并解开它一次。

// shared/api-client/types.ts
export interface ApiSuccessEnvelope<T> {
  data: T;
}
export interface ApiErrorEnvelope {
  error: ApiErrorBody;
}
export type ApiEnvelope<T> = ApiSuccessEnvelope<T> | ApiErrorEnvelope;

export function isApiErrorEnvelope<T>(
  e: ApiEnvelope<T>,
): e is ApiErrorEnvelope {
  return typeof e === "object" && e !== null && "error" in e;
}

export interface ApiErrorBody {
  code: ServerErrorCode; // machine-readable, stable
  message: string; // server message (NOT shown to users directly)
  fields?: Record<string, string[]>; // per-field validation errors
}

解析步骤处理每种情况：204 No Content → undefined; { error } → 抛出异常; 非 2xx

没有格式良好的信封 → 综合一个错误；{ data } → 返回 data。调用者只

曾经看到过类型化的有效负载或抛出。

字符串是可以互换的；域 ID 不能互换。给它们加上标记，这样编译器就会阻止你传递一个

// shared/types/id.ts
declare const brand: unique symbol;
export type Brand<T, B extends string> = T & { readonly [brand]: B };

export type InvoiceId = Brand<string, "InvoiceId">;
export type CustomerId = Brand<string, "CustomerId">;

export const toInvoiceId = (s: string): InvoiceId => s as InvoiceId;
export const toCustomerId = (s: string): CustomerId => s as CustomerId;

function loadInvoice(id: InvoiceId) {
  /* … */
}
loadInvoice(customerId); // ❌ compile error — exactly the bug you want caught
loadInvoice(invoiceId); // ✅

在解析边界处的品牌 ID (§3)，因此应用中的每个 ID 已经是名义上的。运行时成本是

将每种失败模式合并为一个 ApiError，以便调用者处理一种形式。它包含一个

机器代码，HTTP 状态，可选的每字段错误，以及用于本地化的稳定键

消息（它不会本地化——这是用户界面的工作）。

// shared/api-client/error.ts (essence)
export class ApiError extends Error {
  readonly code: ServerErrorCode;
  readonly status: number; // 0 when no response (network/abort)
  readonly fields?: Record<string, string[]>;

  get isNetworkError() {
    return this.status === 0;
  }
  get hasFieldErrors() {
    return !!this.fields && Object.keys(this.fields).length > 0;
  }
  /** Stable key under an `errors` i18n namespace — never a raw server string. */
  get messageKey() {
    if (this.isNetworkError) return "network";
    return ERROR_CODE_MESSAGE_KEYS[this.code] ?? "generic";
  }

  static fromEnvelope(body: ApiErrorBody, status: number) {
    /* server { error } */
  }
  static fromNetwork(cause: unknown) {
    /* offline / CORS / abort → status 0 */
  }
}

客户端发出请求；查询层决定用户看到什么。避免在其中放置提示信息/重定向

// a TanStack Query mutation maps the typed error to a localized toast
useMutation({
  mutationFn: (input) => apiClient.post<Invoice>("/invoices", input),
  onError: (error: ApiError) => notifyError(error), // looks up error.messageKey in i18n
});

服务器验证（fields）直接映射到表单字段错误——一个地方，类型化。

if (error.hasFieldErrors) {
  for (const [field, messages] of Object.entries(error.fields!)) {
    form.setError(field as Path<FormValues>, { message: messages[0] });
  }
}

这个规则是恒定的；数据获取库只会在 onError/解析挂起的地方有所变化。

Library Where the client is called Where ApiError is handled

TanStack Query queryFn/mutationFn call apiClient.* onError per query/mutation, or a global QueryCache/MutationCache onError

RTK Query baseQuery wraps apiClient, parses + returns { data } or { error } transformErrorResponse → ApiError; handle in component or middleware

SWR fetcher = (key) => apiClient.get(key) onError in SWRConfig or per-hook

Plain fetch hooks (RN) a useAsync wrapper calls apiClient.* try/catch sets a typed error state

对于 React Native，客户端没有改变——fetch 和 AbortController 在 RN 中存在。仅

credentials: "include"（cookie 认证）可能需要根据你的认证情况更换为令牌头。

8. 规范检查清单（在审查中执行）

将边界添加到项目： 创建 shared/api-client/，包含 client.ts、error.ts，

types.ts，config.ts。在其他地方添加禁止使用 fetch/axios 的 lint 规则。定义你的 envelope

以匹配后端，以及你的 ApiError 代码。

添加新实体： 在功能模块中定义其架构（Zod/Valibot）和 z.infer 类型，

在解析时为其 ID 打上品牌，并将 apiClient 包装在类型化的查询/变更钩子中——绝不要调用

调试“未定义的三层组件”：添加/修复边界解析以防止契约漂移

在边缘处大声失败并显示类型错误，而不是向下游泄漏 undefined。

审查数据层： 根据第§8节运行清单。最有价值的发现是原始的 fetch

组件（边界绕过）和数据层中的 throw new Error(string)（未类型化的失败）。

此技能遵循 Anthropic 的 SKILL.md 格式，并且可以在各个代理之间移植。

Frontend Data Contracts 实用指南

A portable, framework-agnostic discipline for type safety at the network edge of any React or React Native app. Establishes one typed API client as the single fetch boundary, a parse-don't-validate rule that turns wire JSON into trusted domain types before it enters the app, a single...

前端

本文提供前端数据契约实用指南，定义类型化网络边界。核心规则：单一apiClient封装fetch、边界解析而非验证、统一响应信封、标准化ApiError错误类型及品牌化标识符。通过共享api-client目录实现可移植、框架无关的类型安全方案，适用于React及React Native应用，支持TanStack Query等主流库。

数据转换

React Native

服务器

路由器

编译器

路由

GitHub

Agent

ReAct 

JSON

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

本文提供前端数据契约实用指南，定义类型化网络边界。核心规则：单一apiClient封装fetch、边界解析而非验证、统一响应信封、标准化ApiError错误类型及品牌化标识符。通过共享api-client目录实现可移植、框架无关的类型安全方案，适用于React及React Native应用，支持TanStack Que...

Frontend Data Contracts 实用指南

Frontend Data Contracts 实用指南

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐