TypeScript模板字面量类型与联合类型的组合使用

TypeScript的模板字面量类型和联合类型是两种强大的类型工具。当它们组合使用时，可以创建出高度动态和类型安全的字符串类型，适用于API路径构建、CSS类名生成、状态机定义等多种场景。本文将手把手教你如何将这两种类型结合，构建更健壮的TypeScript代码。

基础概念回顾

在深入组合之前，先快速理解这两个核心概念。

联合类型：表示一个值可以是几种类型中的一种。使用 | 分隔。

type Status = 'success' | 'error' | 'pending';

Status 类型现在可以是这三个字符串中的任意一个。

模板字面量类型：允许你基于字符串字面量创建新类型。使用反引号 ` 包裹，并可以嵌入其他类型。

type Greeting = `Hello, ${string}`;
```
`Greeting` 类型现在匹配任何以 "Hello, " 开头，后跟任意字符串的模式。

---

## 场景一：构建类型安全的API路径

这是模板字面量与联合类型组合最经典的用例。你可以定义一个基础URL和一组可能的路径段，然后自动生成完整的、类型安全的API端点。

**1. 定义基础URL和路径段联合类型。**
首先，定义你的API根路径和一个包含所有可能路径段的联合类型。

```ts
const API_BASE_URL = 'https://api.example.com/v1';

type PathSegment = 'users' | 'posts' | 'comments';
```

**2. 使用模板字面量组合它们。**
接下来，创建一个类型，它将 `PathSegment` 联合类型作为模板的一部分，并拼接上基础URL。

```ts
type ApiPath = `${typeof API_BASE_URL}/${PathSegment}`;
```

**3. 查看生成的类型。**
TypeScript会自动推导出 `ApiPath` 的具体类型，它是一个联合类型，包含了所有可能的组合。

```ts
// ApiPath 的实际类型是:
// "https://api.example.com/v1/users" | "https://api.example.com/v1/posts" | "https://api.example.com/v1/comments"
```

**4. 在函数中使用该类型确保安全性。**
现在，你可以创建一个函数，其参数必须是一个 `ApiPath` 类型的值，从而在编译时确保你只能传入有效的API路径。

```ts
function fetchData(path: ApiPath) {
  console.log(`Fetching data from: ${path}`);
  // 这里可以调用实际的fetch API
}

// 正确用法
fetchData('https://api.example.com/v1/users');

// 错误用法：TypeScript会在编译时报错
// fetchData('https://api.example.com/v1/products'); // 类型不匹配

场景二：动态生成CSS类名

在React或Vue等框架中，动态生成CSS类名很常见。使用模板字面量和联合类型可以确保你组合的类名始终是有效的。

1. 定义基础类名和动态部分。
假设你有一个基础类名，并且需要根据某个状态动态添加另一个类名。

type BaseClass = 'button';
type StateModifier = 'primary' | 'secondary' | 'disabled';

2. 创建一个安全的类名生成函数。
使用模板字面量组合基础类名和状态修饰符，创建一个安全的类名生成函数。

function getClassName(base: BaseClass, state: StateModifier): `.${BaseClass}--${StateModifier}` {
  return `.${base}--${state}`;
}

// 正确用法
const primaryButtonClass = getClassName('button', 'primary'); // 结果: ".button--primary"

// 错误用法：TypeScript会在编译时报错
// getClassName('button', 'danger'); // 'danger' 不在 StateModifier 联合类型中

3. 扩展以支持可选的修饰符。
你也可以创建更复杂的类型，例如，一个类名可以包含可选的修饰符。

type ClassName = `.${BaseClass}${StateModifier extends never ? '' : `--${StateModifier}`}`;

function getOptionalClassName(base: BaseClass, state?: StateModifier): ClassName {
  if (state) {
    return `.${base}--${state}`;
  }
  return `.${base}`;
}

// 正确用法
const buttonClass = getOptionalClassName('button'); // 结果: ".button"
const primaryButtonClass = getOptionalClassName('button', 'primary'); // 结果: ".button--primary"

场景三：结合条件类型实现更复杂的逻辑

当需要根据联合类型的值来动态改变模板字面量的结果时，可以结合条件类型。

1. 定义一个包含不同实体的联合类型。
假设我们有一个联合类型，代表不同的实体，如 'user' 或 'post'。

type Entity = 'user' | 'post';

2. 使用条件类型和模板字面量生成不同的路径。
我们可以创建一个类型，根据 Entity 的值，生成不同的URL路径结构。

type GetEntityPath<T extends Entity> = T extends 'user'
  ? `/api/users/${string}`
  : `/api/posts/${string}`;

// 使用示例
type UserPath = GetEntityPath<'user'>; // 类型: "/api/users/${string}"
type PostPath = GetEntityPath<'post'>; // 类型: "/api/posts/${string}"

3. 在函数中应用。
这个类型可以用在函数中，确保传入的路径符合特定实体的规范。

function getEntityData<T extends Entity>(path: GetEntityPath<T>) {
  console.log(`Fetching ${T} data from: ${path}`);
}

// 正确用法
getEntityData('/api/users/123'); // T 被推断为 'user'
getEntityData('/api/posts/456'); // T 被推断为 'post'

// 错误用法：TypeScript会在编译时报错
// getEntityData('/api/comments/789'); // 路径不符合 'user' 或 'post' 的规范

注意事项与最佳实践

1. 可读性：虽然模板字面量类型非常强大，但过度复杂的组合可能会降低代码的可读性。在团队协作中，确保关键类型有清晰的注释。
2. 类型推断限制：当模板字面量变得非常复杂时，TypeScript可能无法精确推断出所有细节，导致类型变得“过于宽泛”。在这种情况下，你可能需要使用 as const 或显式类型注解来帮助TypeScript。
3. 性能：在极少数情况下，极其复杂的类型运算可能会对编译速度产生轻微影响。但对于绝大多数应用来说，这种影响可以忽略不计。
4. 避免过度工程：不要为了使用而使用。只在确实需要类型安全且能带来明显收益的场景下使用这种高级类型技巧。对于简单的字符串拼接，传统的JavaScript或简单的TypeScript类型可能已经足够。