TypeScript 类型安全API设计与实现

TypeScript 类型安全API设计与实现

概述

本文通过分析一个数据管理API的实现，展示如何在TypeScript中构建类型安全的API接口。该实现充分利用了TypeScript的高级类型特性，包括联合类型、映射类型和索引访问类型等。

核心类型定义

基础类型

export type HandleType = "add" | "approval" | "reject";
export type HandleState = "submit";

定义了操作类型和状态类型，使用字符串字面量类型确保类型安全。

基础参数接口

export interface BaseHandleParams {
  id?: number;
  status: HandleState;
  row: {
    customer_name: string;
    site_name: string;
  };
}

定义了通用的请求参数结构，使用可选属性id和必填的status及row对象。

类型映射与组合

参数类型映射

export type HandleParamsMap = {
  add: HandleAddParams;
  approval: HandleApprovalParams;
  reject: HandleRejectParams;
};

建立了操作类型与对应参数类型的映射关系，为后续高级类型组合奠定基础。

高级类型组合

export type HandleParams = {
  [K in keyof HandleParamsMap]: {
    type: K;
    data: HandleParamsMap[K];
  };
}[keyof HandleParamsMap];

这段代码展示了TypeScript强大的类型系统：

1. 使用映射类型遍历HandleParamsMap的所有键
2. 为每个键创建包含type和对应data的类型
3. 通过索引访问[keyof HandleParamsMap]将映射类型转换为联合类型

API实现

请求函数

export const handleRequest = (params: HandleParams) =>
  service.post("/bus/data/approval", params);

严格类型化的请求函数，确保传入参数必须匹配定义的HandleParams类型。

API封装

export const DataMgrApi = {
  handle: handleRequest,
};

将请求函数封装为API对象，便于统一管理和调用。

使用示例

DataMgrApi.handle({
  type: "approval",
  data: {
    status: "submit",
    row: {
      customer_name: "111",
      site_name: "222",
    },
  },
});

展示了类型安全API的调用方式，TypeScript会验证:

• type必须是HandleType定义的值
• data必须与type对应的参数类型匹配

设计优势

1. 类型安全：所有操作都有明确的类型约束
2. 可扩展性：新增操作类型只需扩展HandleType和HandleParamsMap
3. 自文档化：类型定义本身就是良好的文档
4. 开发体验：IDE可以提供精确的代码补全和类型提示

总结

通过合理运用TypeScript的类型系统，我们可以构建出既灵活又安全的API接口。这种模式特别适合需要处理多种相似但略有差异的操作场景，如CRUD操作、审批流程等。