Vue / 系统课时
接口类型与分页模型
接口类型与分页模型
企业接口层最容易失控的地方,不是请求能否发出,而是参数、分页数据和业务错误缺少统一约束。本课将建立一组可复用的 TypeScript 类型,并通过完整示例演示如何安全读取成功结果与错误信息。
学习目标
- 定义请求参数、实体数据和统一响应类型
- 使用泛型构建可复用的分页模型
- 通过可辨识联合类型收窄业务错误
统一建模请求、分页与错误
接口类型应先描述“前后端约定”,再服务页面代码。请求参数只包含服务端真正支持的字段;响应模型则区分成功数据和业务失败,避免把所有结果都声明成 any。
分页接口通常包含三层信息:查询条件、分页元数据和当前页记录。将这三层拆开后,同一套分页结构就能复用于用户、订单和商品等不同实体。
下面示例可保存为 pagination-demo.ts,使用 TypeScript 编译后运行。ApiResponse<T> 通过 success 字段形成可辨识联合类型,进入不同分支后,编辑器会自动推断可访问字段。
interface PageQuery {
page: number;
pageSize: number;
}
interface PageResult<T> {
list: T[];
page: number;
pageSize: number;
total: number;
}
interface User {
id: number;
name: string;
status: "enabled" | "disabled";
}
interface UserQuery extends PageQuery {
keyword?: string;
status?: User["status"];
}
interface ApiSuccess<T> {
success: true;
data: T;
}
interface ApiFailure {
success: false;
error: {
code: string;
message: string;
};
}
type ApiResponse<T> = ApiSuccess<T> | ApiFailure;
async function fetchUsers(
query: UserQuery
): Promise<ApiResponse<PageResult<User>>> {
if (query.page < 1 || query.pageSize < 1) {
return {
success: false,
error: {
code: "INVALID_PAGE",
message: "页码和每页条数必须大于 0"
}
};
}
const allUsers: User[] = [
{ id: 1, name: "Alice", status: "enabled" },
{ id: 2, name: "Bob", status: "disabled" }
];
const filtered = query.keyword
? allUsers.filter((user) => user.name.includes(query.keyword!))
: allUsers;
return {
success: true,
data: {
list: filtered,
page: query.page,
pageSize: query.pageSize,
total: filtered.length
}
};
}
async function main(): Promise<void> {
const response = await fetchUsers({
page: 1,
pageSize: 10,
keyword: "A"
});
if (response.success) {
console.log(`共 ${response.data.total} 条`);
console.log(response.data.list[0]?.name ?? "暂无数据");
} else {
console.error(`${response.error.code}: ${response.error.message}`);
}
}
void main();预期输出
共 1 条
Alice示例中的 PageResult<T> 不关心记录的具体类型,只约束分页字段;UserQuery 则继承基础分页参数并增加业务筛选条件。这样既保留统一结构,也不会把无关字段塞进所有请求。
分页字段的边界约定
页码必须明确从 1 还是 0 开始,前后端不能各自猜测。本课示例采用从 1 开始;当没有记录时,成功响应仍应返回空数组和 total: 0,而不是把“无数据”当作业务错误。
pageSize 应由接口限制最大值,前端类型只能表达“这是数字”,不能替代运行时校验。对于可选筛选项,未填写时优先省略字段;只有接口明确区分“未传”和“传空值”时才使用 null。
业务错误与传输错误
业务错误表示请求已经到达服务端,但操作因规则不满足而失败,例如参数非法或权限不足;它适合放进 ApiFailure。网络中断、超时和非预期 HTTP 状态属于传输错误,应由请求封装层通过异常统一处理,不要伪装成业务数据。
使用 success: true | false 后,分支判断本身就是类型守卫。成功分支只能读取 data,失败分支只能读取 error,从源头减少空值判断和错误字段误用。
本课总结
- 请求参数、分页数据和业务错误应分别建模,再通过泛型组合
PageResult<T>统一分页结构,同时保留实体类型信息- 可辨识联合类型能让成功与失败分支获得可靠的类型收窄
下一课预告
下一课将处理搜索、切页和组件卸载时的过期请求,避免较早返回的响应覆盖最新页面状态。