JavaScript / TypeScript / 系统课时
设计 API 数据类型
设计 API 数据类型
API 类型设计的目标不是给每个 JSON 字段机械加类型,而是把请求参数、成功响应、失败响应和分页元数据拆成稳定、可复用的边界模型。这样接口变化时能快速定位影响范围,调用方也能依赖类型收窄而不是到处写断言。
学习目标
- 为请求参数、成功响应、失败响应和分页结构建立独立类型
- 使用泛型复用分页与响应外壳,避免复制字段
- 通过可辨识联合让调用方安全区分成功与失败
从接口边界拆出四类模型
先按 HTTP 协议中的职责拆类型,而不是按页面组件拆。请求参数描述“客户端可以传什么”,业务数据描述“成功时得到什么”,错误对象描述“失败时得到什么”,分页结构只负责承载列表和页码信息。
把这些职责分开后,同一个 User 可以出现在详情接口、分页列表和其他组合响应中;分页壳也可以复用于订单、日志等列表接口,而不需要复制 page、pageSize、total。
用泛型复用响应和分页结构
下面的示例把成功与失败响应建模为以 ok 为判别字段的联合类型,并让分页结构只关心“元素是什么类型”。
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));预期输出:
1/1: AdaPage<T> 只负责分页,ApiResult<T> 只负责成功或失败,真正的业务数据由 T 注入。调用方判断 result.ok 后,TypeScript 会自动把联合类型收窄到对应分支,因此无需使用 as 强制断言。
明确可选、为空与缺失的语义
keyword?: string 表示调用方可以完全不传这个字段;keyword: string | null 表示字段必须存在,但值可以为空。两者在序列化、校验和后端语义上并不相同,不能为了“省事”统一写成可选。
错误响应也不要直接写成 string。至少保留稳定的机器码 code 和给人阅读的 message,这样界面可以按错误码决定重试、登录或提示,而不是解析自然语言。
让模型保持可演进
接口类型应贴近线上协议,但不要把页面状态、按钮文案或组件专用字段塞进 API 模型。页面需要的派生状态可以在拿到响应后再转换,否则一个视图调整就可能迫使底层接口类型一起变化。
当多个接口共享分页、错误结构或响应外壳时使用泛型;当字段只是“看起来相似”但语义不同,不要为了复用强行合并。好的 API 类型模型应让协议边界清晰,同时把变化限制在最小范围内。