React / 系统课时
接口响应类型
接口响应类型
前端最常见的类型漏洞不是组件属性,而是把接口返回值直接当成可信对象使用。本课将分页数据、成功响应、错误响应和领域模型分层建模,并用可判别联合与运行时检查减少字段误用。
学习目标
- 区分领域模型、分页结构与传输响应的职责
- 使用可判别联合安全处理成功和失败结果
- 理解 TypeScript 类型声明不能替代运行时数据校验
建立分层响应模型
领域模型只描述业务对象,例如用户的编号、名称和状态;分页结构负责承载列表、页码和总数;响应结构再包装成功数据、错误信息与追踪编号。分层后,同一个 PageData<T> 可以复用于用户、订单和商品接口。
成功与失败响应应共享一个可判别字段,例如 success: true | false。代码判断 response.success 后,TypeScript 会自动收窄联合类型:成功分支只能访问 data,失败分支只能访问 error,从源头阻止把错误响应当业务数据读取。

用可判别联合安全消费
下面是一个可直接运行的 TypeScript 示例。接口原始数据先保持为 unknown,解析函数确认结构后才返回业务可用的联合类型。
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}`);
}预期输出
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 定义为字符串字面量联合,但不要把所有后端错误码硬编码进一个巨大类型。前端只需为可处理的错误提供明确分支,未知错误仍保留通用兜底。