TypeScript 精确字符串类型

技能文档

---
name: marius-townhouse-precise-string-types
title: TypeScript 精确字符串类型
category: 开发工具
description: 用字符串字面量联合类型、keyof 与模板字面量类型替代宽泛的 string 类型，获得编译期拼写检查、自动补全与自文档化收益。定义取值有限的属性、编写接受特定字符串的函数参数、review 出「字符串类型化」坏味道代码时使用。当用户提到 TypeScript 类型安全、字符串联合类型、keyof、模板字面量类型、string 太宽泛时触发。触发词：TypeScript、字符串类型、keyof、字面量联合、类型安全。
---

# 优先使用更精确的字符串类型替代

**string 类型的取值范围巨大。能用更窄的类型就不要用宽类型。**

字符串字面量联合、模板字面量类型与 keyof 比裸 string 更安全、自动补全更友好、自带文档。

## 适用场景

- 定义合法取值有限的属性
- 编写只接受特定字符串的函数参数
- 处理对象键名或属性名
- 发现「字符串类型化」（stringly typed）代码
- string 参数没有任何自动补全提示

## 技能工作流

### 步骤1：识别「字符串类型化」坏味道

如果某个 string 只可能取特定几个值，就要把这个事实显式表达出来。

```typescript
// ❌ 违规：太宽泛，任何字符串都接受
interface Album {
  artist: string;
  title: string;
  releaseDate: string;     // 什么格式？任何字符串都合法！
  recordingType: string;   // "live" 或 "studio"……但 "banana" 也过得去
}

// 以下全都合法但都是错的：
const album: Album = {
  artist: 'Miles Davis',
  title: 'Kind of Blue',
  releaseDate: 'August 17th, 1959',  // 格式错了
  recordingType: 'Studio',            // 大小写错了
};
```

### 步骤2：改用字符串字面量联合

```typescript
// ✅ 正确：精确类型
type RecordingType = 'studio' | 'live';

interface Album {
  artist: string;
  title: string;
  releaseDate: Date;         // 用 Date，不用 string
  recordingType: RecordingType;
}

const album: Album = {
  artist: 'Miles Davis',
  title: 'Kind of Blue',
  releaseDate: new Date('1959-08-17'),
  recordingType: 'Studio',
  //             ~~~~~~~~ 类型 '"Studio"' 不能赋给 'RecordingType'
};
```

精确类型的三重收益：

```typescript
// 1. 抓拼写错误
type Direction = 'north' | 'south' | 'east' | 'west';
function move(direction: Direction) { /* ... */ }
move('nroth');  // 报错：你是不是想写 'north'？

// 2. 自动补全
function move(direction: Direction) { }
move('|')  // 提示：north, south, east, west

// 3. 类型即文档
/** 这段录音是在什么环境下录制的？ */
type RecordingType = 'live' | 'studio';
function getAlbums(type: RecordingType) { }
// IDE 显示：(parameter) type: "live" | "studio"
```

### 步骤3：对象键用 keyof

```typescript
// ❌ 差：任何字符串都接受
function pluck(records: any[], key: string): any[] {
  return records.map(r => r[key]);
}

// ✅ 好：只接受合法键名
function pluck<T>(records: T[], key: keyof T): T[keyof T][] {
  return records.map(r => r[key]);
}

pluck(albums, 'artist');     // OK，返回 string[]
pluck(albums, 'artits');     // 报错：你是不是想写 'artist'？
```

更进一步，泛型键参数可获得精确返回类型：

```typescript
function pluck<T, K extends keyof T>(records: T[], key: K): T[K][] {
  return records.map(r => r[key]);
}

const dates = pluck(albums, 'releaseDate');
//    ^? const dates: Date[]  // 精确返回类型！

const artists = pluck(albums, 'artist');
//    ^? const artists: string[]
```

### 步骤4：模式字符串用模板字面量类型

```typescript
// 匹配 "GET /users" 或 "POST /items" 形态的字符串
type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
type ApiRoute = `${HttpMethod} /${string}`;

function handleRoute(route: ApiRoute) { }

handleRoute('GET /users');     // OK
handleRoute('POST /items');    // OK
handleRoute('PATCH /users');   // 报错：不是合法 HttpMethod
handleRoute('GET users');      // 报错：缺少 /
```

### 步骤5：判断 string 何时才是合理选择

```typescript
interface Album {
  // 这些确实可以是任意字符串：
  artist: string;   // "Miles Davis"、"Queen"……
  title: string;    // 无限可能

  // 这些不应该是 string：
  recordingType: RecordingType;  // 取值有限
  genre: Genre;                   // 取值有限
}
```

## 常见反对意见与回应

**1.「以后可能会加新值」**

先定义当前已知值，将来加值时往联合类型里补，TypeScript 会自动标出所有需要处理新值的位置。

**2.「用户输入可能是任意字符串」**

在边界处校验，内部用精确类型。解析/校验用户输入后，再转入精确类型的领域模型。

**3.「为这点事建 enum 太重了」**

字符串字面量联合比 enum 更轻且同样精确：用 `type X = 'a' | 'b' | 'c'` 替代 enum。

## 红旗信号——停下来重新审视

- 注释里解释某字符串的合法取值
- 对 string 参数做运行时校验
- switch 字符串分支的 default 写着「不应该走到这里」
- string 参数没有任何自动补全
- 因字符串拼写错误引发的 bug

## 常见借口速查（全部不成立）

| 借口 | 真相 |
|--------|---------|
| 「它就是个字符串」 | 它是取值有限的字符串，把这个事实表达出来 |
| 「以后再校验」 | 边界校验，内部用类型 |
| 「取值太多了」 | 有限就可枚举，TypeScript 扛得住 |
| 「enum 太丑」 | 用字符串字面量联合替代 |

## 速查表

| 你现在写的 | 应改为 |
|----------|-------------|
| 有 N 个合法值的 `string` | `'value1' \| 'value2' \| ...` |
| 对象键参数 | `keyof T` |
| 有固定模式的字符串 | 模板字面量类型 |
| 用 string 存日期 | `Date` |
| 用 string 存 URL | 考虑 branded type |

## 迁移步骤

```typescript
// 第 1 步：找到取值有限的 string
interface Config {
  environment: string;  // "dev", "staging", "prod"
}

// 第 2 步：定义联合类型
type Environment = 'development' | 'staging' | 'production';

// 第 3 步：替换字段类型
interface Config {
  environment: Environment;
}

// 第 4 步：修完所有报错（这正是目的！）
const config: Config = { environment: 'dev' };
//                                    ~~~~~ 你是不是想写 'development'？
```

## 核心结论

**string 就是字符串类型里的 any。**

取值有限就表达出这个限制：有限集合用字面量联合，对象键用 keyof，固定模式用模板字面量类型。代码更安全，IDE 更懂你。

## 参考资料

- 《Effective TypeScript》（Dan Vanderkam）第 35 条：Prefer More Precise Alternatives to String Types

使用说明

# TypeScript 精确字符串类型

用字面量联合、keyof、模板字面量类型替代宽泛 string，换取编译期拼写检查、自动补全与自文档化。

## 使用

```text
帮我检查这个 TS 项目里有哪些该改成字面量联合的 string 字段
```

```text
这个函数的 type 参数只接受几个固定值，帮我改成精确类型
```

## 工作原理

按「识别字符串类型化坏味道 → 定义字面量联合 → 对象键改 keyof → 模式串用模板字面量类型 → 边界校验兜底」五步改造，提供迁移四步法与常见借口反驳清单，配速查表（string→联合、键参数→keyof、日期→Date 等）。

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。