Vue / 系统课时

接口类型与分页模型

接口类型与分页模型

企业接口层最容易失控的地方,不是请求能否发出,而是参数、分页数据和业务错误缺少统一约束。本课将建立一组可复用的 TypeScript 类型,并通过完整示例演示如何安全读取成功结果与错误信息。

学习目标

  • 定义请求参数、实体数据和统一响应类型
  • 使用泛型构建可复用的分页模型
  • 通过可辨识联合类型收窄业务错误

统一建模请求、分页与错误

接口类型应先描述“前后端约定”,再服务页面代码。请求参数只包含服务端真正支持的字段;响应模型则区分成功数据和业务失败,避免把所有结果都声明成 any。

分页接口通常包含三层信息:查询条件、分页元数据和当前页记录。将这三层拆开后,同一套分页结构就能复用于用户、订单和商品等不同实体。

下面示例可保存为 pagination-demo.ts,使用 TypeScript 编译后运行。ApiResponse<T> 通过 success 字段形成可辨识联合类型,进入不同分支后,编辑器会自动推断可访问字段。

ts
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();

预期输出

text
共 1 条
Alice

示例中的 PageResult<T> 不关心记录的具体类型,只约束分页字段;UserQuery 则继承基础分页参数并增加业务筛选条件。这样既保留统一结构,也不会把无关字段塞进所有请求。

分页字段的边界约定

页码必须明确从 1 还是 0 开始,前后端不能各自猜测。本课示例采用从 1 开始;当没有记录时,成功响应仍应返回空数组和 total: 0,而不是把“无数据”当作业务错误。

pageSize 应由接口限制最大值,前端类型只能表达“这是数字”,不能替代运行时校验。对于可选筛选项,未填写时优先省略字段;只有接口明确区分“未传”和“传空值”时才使用 null。

业务错误与传输错误

业务错误表示请求已经到达服务端,但操作因规则不满足而失败,例如参数非法或权限不足;它适合放进 ApiFailure。网络中断、超时和非预期 HTTP 状态属于传输错误,应由请求封装层通过异常统一处理,不要伪装成业务数据。

使用 success: true | false 后,分支判断本身就是类型守卫。成功分支只能读取 data,失败分支只能读取 error,从源头减少空值判断和错误字段误用。

本课总结

  • 请求参数、分页数据和业务错误应分别建模,再通过泛型组合
  • PageResult<T> 统一分页结构,同时保留实体类型信息
  • 可辨识联合类型能让成功与失败分支获得可靠的类型收窄

下一课预告

下一课将处理搜索、切页和组件卸载时的过期请求,避免较早返回的响应覆盖最新页面状态。

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

目录与阅读设置

阅读设置

17

记录一个想法

接口类型与分页模型

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

登录哪都通