JavaScript / TypeScript / 系统课时

设计 API 数据类型

设计 API 数据类型

API 类型设计的目标不是给每个 JSON 字段机械加类型,而是把请求参数、成功响应、失败响应和分页元数据拆成稳定、可复用的边界模型。这样接口变化时能快速定位影响范围,调用方也能依赖类型收窄而不是到处写断言。

学习目标

  • 为请求参数、成功响应、失败响应和分页结构建立独立类型
  • 使用泛型复用分页与响应外壳,避免复制字段
  • 通过可辨识联合让调用方安全区分成功与失败

从接口边界拆出四类模型

先按 HTTP 协议中的职责拆类型,而不是按页面组件拆。请求参数描述“客户端可以传什么”,业务数据描述“成功时得到什么”,错误对象描述“失败时得到什么”,分页结构只负责承载列表和页码信息。

把这些职责分开后,同一个 User 可以出现在详情接口、分页列表和其他组合响应中;分页壳也可以复用于订单、日志等列表接口,而不需要复制 page、pageSize、total。

用泛型复用响应和分页结构

下面的示例把成功与失败响应建模为以 ok 为判别字段的联合类型,并让分页结构只关心“元素是什么类型”。

ts
interface User {
  id: string;
  name: string;
}

interface ListUsersParams {
  page: number;
  pageSize: number;
  keyword?: string;
}

interface ApiError {
  code: string;
  message: string;
}

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

type ApiSuccess<T> = {
  ok: true;
  data: T;
};

type ApiFailure = {
  ok: false;
  error: ApiError;
};

type ApiResult<T> = ApiSuccess<T> | ApiFailure;

function describe(result: ApiResult<Page<User>>): string {
  if (!result.ok) {
    return `ERROR ${result.error.code}: ${result.error.message}`;
  }

  const first = result.data.items[0];
  return `${result.data.items.length}/${result.data.total}: ${first?.name ?? "empty"}`;
}

const sample: ApiResult<Page<User>> = {
  ok: true,
  data: {
    items: [{ id: "u-1", name: "Ada" }],
    page: 1,
    pageSize: 20,
    total: 1
  }
};

console.log(describe(sample));

预期输出:

text
1/1: Ada

Page<T> 只负责分页,ApiResult<T> 只负责成功或失败,真正的业务数据由 T 注入。调用方判断 result.ok 后,TypeScript 会自动把联合类型收窄到对应分支,因此无需使用 as 强制断言。

明确可选、为空与缺失的语义

keyword?: string 表示调用方可以完全不传这个字段;keyword: string | null 表示字段必须存在,但值可以为空。两者在序列化、校验和后端语义上并不相同,不能为了“省事”统一写成可选。

错误响应也不要直接写成 string。至少保留稳定的机器码 code 和给人阅读的 message,这样界面可以按错误码决定重试、登录或提示,而不是解析自然语言。

让模型保持可演进

接口类型应贴近线上协议,但不要把页面状态、按钮文案或组件专用字段塞进 API 模型。页面需要的派生状态可以在拿到响应后再转换,否则一个视图调整就可能迫使底层接口类型一起变化。

当多个接口共享分页、错误结构或响应外壳时使用泛型;当字段只是“看起来相似”但语义不同,不要为了复用强行合并。好的 API 类型模型应让协议边界清晰,同时把变化限制在最小范围内。

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

目录与阅读设置

阅读设置

17

记录一个想法

设计 API 数据类型

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

登录哪都通