TypeScript自定义带可选参数的类型及枚举约束问题

问题背景 #

我正在为自研包创建TypeScript自定义类型辅助验证逻辑，目标是通过类型提示引导用户遵循正确的验证格式。基础功能已实现，但处理可选参数时遇到阻碍——并非所有参数都是必填项。

原实现 #

最初的类型定义方式如下：

const _string = '';

export type ValidationRules = {
  `between:${typeof _string},${typeof _string}`
}

可选参数的痛点 #

针对类似required_if:{name},{value | operator},{value?}的规则（末尾value为可选参数），如果沿用原方式实现：

const _string = '';

export type ValidationRules = {
  `required_if:${typeof _string},${typeof _string},${typeof _string}`
}

得到的类型提示是required_if:,,，但实际需要支持required_if:,（双参数）和required_if:,,（三参数）两种格式。我知道可以复制不含末尾参数的类型来解决，但想找更简便的实现方式，同时询问文档层面如何提示用户正确填充内容。

更新后的实现 #

后来我调整了实现方式，引入枚举约束操作符：

export enum Operator {
    Equals = 'eq',
    GreaterThan = 'gt',
    LessThan = 'lt'
}

export type ValidationRules = 
    `required_if:${string},${string}` |
    `required_if:${Operator}(${string},${string})`

const valid: ValidationRules = 'required_if:name,exampleName'; // Pass
const valid2: ValidationRules = 'required_if:eq(name,exampleName)'; // Pass

const invalid: ValidationRules = 'required_if:name,exampleName,exampleName'; // Fail
const invalid2: ValidationRules = 'required_if:invalid(name,exampleName)'; // Fail

疑问解答 #

1. 更简便的可选参数实现方式 #

TypeScript模板字面量本身不支持直接标记某个参数为可选，目前最简便且类型安全的方案就是用联合类型枚举所有合法的参数组合，也就是你现在采用的A | B形式。

如果后续规则数量增多，可通过拆分基础类型来提升可维护性：

// 拆分基础规则模板
type RequiredIfBase = `required_if:${string}`;
// 双参数格式
type RequiredIfTwoArgs = `${RequiredIfBase},${string}`;
// 三参数格式（可选）
type RequiredIfThreeArgs = `${RequiredIfTwoArgs},${string}`;

export type ValidationRules = RequiredIfTwoArgs | RequiredIfThreeArgs;

这种方式后续新增参数组合时只需扩展联合类型即可，结构更清晰。

2. 强制用户使用Operator枚举值 #

你当前的实现已经通过${Operator}约束了操作符必须是枚举中的值，invalid2报错就是因为使用了枚举外的invalid。如果要进一步强化约束：

• 若name有固定可选值，可替换string为枚举或字面量类型，进一步缩小合法输入范围；
• 给枚举添加注释，引导用户优先使用枚举而非直接输入字符串：

/** 验证规则操作符，仅支持以下枚举值，禁止直接输入字符串 */
export enum Operator {
    /** 等于判断 */
    Equals = 'eq',
    /** 大于判断 */
    GreaterThan = 'gt',
    /** 小于判断 */
    LessThan = 'lt'
}

3. 文档层面提示用户填充内容 #

• JSDoc注释：给ValidationRules类型添加详细说明，用户在IDE中悬浮类型时就能看到规则格式和参数含义：

/**
 * 验证规则类型，支持两种格式：
 * 1. `required_if:{字段名},{匹配值}`：当指定字段等于匹配值时，当前字段必填
 * 2. `required_if:{操作符}({字段名},{匹配值})`：通过操作符判断字段值，操作符仅支持eq/gt/lt
 */
export type ValidationRules = 
    `required_if:${string},${string}` |
    `required_if:${Operator}(${string},${string})`;

• 示例代码：在类型定义附近添加更多合法/非法示例，直观展示正确用法；
• 包文档：在自研包的README或文档站点中，专门列出所有验证规则的格式、参数说明和示例，配合类型提示形成双重引导。

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