React / 系统课时

接口响应类型

接口响应类型

前端最常见的类型漏洞不是组件属性,而是把接口返回值直接当成可信对象使用。本课将分页数据、成功响应、错误响应和领域模型分层建模,并用可判别联合与运行时检查减少字段误用。

学习目标

  • 区分领域模型、分页结构与传输响应的职责
  • 使用可判别联合安全处理成功和失败结果
  • 理解 TypeScript 类型声明不能替代运行时数据校验

建立分层响应模型

领域模型只描述业务对象,例如用户的编号、名称和状态;分页结构负责承载列表、页码和总数;响应结构再包装成功数据、错误信息与追踪编号。分层后,同一个 PageData<T> 可以复用于用户、订单和商品接口。

成功与失败响应应共享一个可判别字段,例如 success: true | false。代码判断 response.success 后,TypeScript 会自动收窄联合类型:成功分支只能访问 data,失败分支只能访问 error,从源头阻止把错误响应当业务数据读取。

接口响应类型的分层与收窄过程

用可判别联合安全消费

下面是一个可直接运行的 TypeScript 示例。接口原始数据先保持为 unknown,解析函数确认结构后才返回业务可用的联合类型。

ts
interface User {
  id: number;
  name: string;
  status: "ACTIVE" | "DISABLED";
}

interface PageData<T> {
  items: T[];
  page: number;
  pageSize: number;
  total: number;
}

interface ApiSuccess<T> {
  success: true;
  data: T;
  traceId: string;
}

interface ApiError {
  success: false;
  error: {
    code: string;
    message: string;
  };
  traceId: string;
}

type ApiResponse<T> = ApiSuccess<T> | ApiError;
type JsonRecord = Record<string, unknown>;

function isRecord(value: unknown): value is JsonRecord {
  return typeof value === "object" && value !== null;
}

function isUser(value: unknown): value is User {
  return (
    isRecord(value) &&
    typeof value.id === "number" &&
    typeof value.name === "string" &&
    (value.status === "ACTIVE" || value.status === "DISABLED")
  );
}

function parseUsers(value: unknown): User[] {
  if (!Array.isArray(value) || !value.every(isUser)) {
    throw new Error("用户列表结构无效");
  }
  return value;
}

function parseUserPageResponse(
  value: unknown,
): ApiResponse<PageData<User>> {
  if (
    !isRecord(value) ||
    typeof value.success !== "boolean" ||
    typeof value.traceId !== "string"
  ) {
    throw new Error("响应外层结构无效");
  }

  if (value.success === false) {
    if (
      !isRecord(value.error) ||
      typeof value.error.code !== "string" ||
      typeof value.error.message !== "string"
    ) {
      throw new Error("错误响应结构无效");
    }

    return {
      success: false,
      error: {
        code: value.error.code,
        message: value.error.message,
      },
      traceId: value.traceId,
    };
  }

  if (
    !isRecord(value.data) ||
    typeof value.data.page !== "number" ||
    typeof value.data.pageSize !== "number" ||
    typeof value.data.total !== "number"
  ) {
    throw new Error("分页数据结构无效");
  }

  return {
    success: true,
    data: {
      items: parseUsers(value.data.items),
      page: value.data.page,
      pageSize: value.data.pageSize,
      total: value.data.total,
    },
    traceId: value.traceId,
  };
}

const rawResponse: unknown = {
  success: true,
  data: {
    items: [{ id: 1, name: "Ada", status: "ACTIVE" }],
    page: 1,
    pageSize: 20,
    total: 1,
  },
  traceId: "<TRACE_ID>",
};

const response = parseUserPageResponse(rawResponse);

if (response.success) {
  const firstUser = response.data.items[0];
  console.log(
    `${firstUser.name}, total=${response.data.total}, trace=${response.traceId}`,
  );
} else {
  console.error(`${response.error.code}: ${response.error.message}`);
}

预期输出

text
Ada, total=1, trace=<TRACE_ID>

<TRACE_ID> 表示后端生成的动态追踪编号,实际运行时可能不同。若把 items 中的 id 改成字符串,解析函数会抛出“用户列表结构无效”,错误数据不会进入组件状态。

守住网络边界

fetch 的响应体来自网络,即使函数声明为 Promise<ApiResponse<User>>,TypeScript 也不会检查真实 JSON。直接执行类型断言只是在编译期“相信”数据,不会修复字段缺失、类型错误或后端版本不一致。

更稳妥的顺序是:先把 response.json() 的结果保留为 unknown,再交给解析函数或模式校验库,最后把验证后的 ApiResponse<T> 写入状态。组件内部只处理已经验证的数据,加载状态、业务错误和结构错误也应分别记录。

分页字段要统一语义。page 是从 0 还是从 1 开始、total 表示总条数还是总页数,都应由接口契约明确规定;不要仅凭字段名猜测。领域模型也应只保留前端真正使用的字段,避免把整个后端实体原样复制到页面层。

当错误类型较多时,可以继续把 error.code 定义为字符串字面量联合,但不要把所有后端错误码硬编码进一个巨大类型。前端只需为可处理的错误提供明确分支,未知错误仍保留通用兜底。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

接口响应类型

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通