TypeScript中如何为API包装器的数字过滤器添加语义注释？

方法一：使用枚举（Enum） #

枚举能直接把语义化名称和数字值绑定，代码可读性拉满，编辑器hover时还能看到注释：

enum ServerFilter {
  None = 0,    // 无过滤
  Minimal = 1, // 极简模式
  Status = 2   // 状态过滤
}

async getServerCount(filter?: ServerFilter) {
  // 你的实现逻辑
}

调用时可以直接传ServerFilter.None这类语义化值，也兼容直接传数字0/1/2。

方法二：带JSDoc注释的类型别名 #

给类型别名加上详细的JSDoc注释，编辑器会在hover参数或类型时显示完整说明：

/**
 * 服务器过滤器类型
 * @type 0 - 无过滤
 * @type 1 - 极简模式
 * @type 2 - 状态过滤
 */
type ServerFilter = 0 | 1 | 2;

async getServerCount(filter?: ServerFilter) {
  // 你的实现逻辑
}

方法三：对象映射+类型推导 #

这种方式兼顾语义化调用和类型安全，类型会自动推导为对应的数字联合类型：

const ServerFilter = {
  None: 0 as const,    // 无过滤
  Minimal: 1 as const, // 极简模式
  Status: 2 as const   // 状态过滤
};

type ServerFilter = typeof ServerFilter[keyof typeof ServerFilter];

async getServerCount(filter?: ServerFilter) {
  // 你的实现逻辑
}

内容的提问来源于stack exchange，提问作者Poulette