TypeScript Branded Types 实战：提升类型安全，防止意外赋值错误

TypeScript 作为一门静态类型语言，其强大的类型系统能有效提升代码质量并预防许多潜在错误。然而，其内置的结构性类型系统（structural typing）存在一个固有的局限性：只要两个类型的结构（即拥有的属性和方法）相似，它们就被视为兼容。这种设计在带来灵活性的同时，也可能导致意外的赋值或函数调用，引发逻辑错误。

为了应对这类问题，我们可以使用 Branded Types（品牌类型） 技术。这是一种在 TypeScript 的结构化类型系统之上，模拟名义类型系统（nominal typing）特性的方法，能够有效区分那些结构相似但语义完全不同的类型。

本文将深入探讨结构性类型系统带来的问题，并详细介绍如何使用 Branded Types 来增强你的 TypeScript 代码的类型安全性。

理解 TypeScript 的结构性类型系统

TypeScript 的类型兼容性判断基于类型的结构而非名称，这与 Java、C# 等语言的“命名型系统”截然不同。在结构型系统中，只要一个值的“形状”与目标类型匹配，它就被认为是兼容的。

例如下面的代码：

interface Point {
  x: number;
  y: number;
}

function plotPoint(point: Point) {
  console.log(`Plotting at x: ${point.x}, y: ${point.y}`);
}

const mousePosition = { x: 100, y: 200 };
plotPoint(mousePosition); // 编译通过

变量 mousePosition 并未显式声明为 Point 类型，但由于其结构（拥有 x 和 y 属性）与 Point 一致，因此可以安全地传递给 plotPoint 函数。这种“鸭子类型”的特性让开发更加灵活。

结构性类型系统引发的潜在问题

然而，这种灵活性是一把双刃剑。最常见的问题便是“无意的类型兼容性”。请看下面的例子：

interface UserCredentials {
  id: string;
  password: string;
}

interface DatabaseConfig {
  id: string;
  password: string;
}

function connectToDatabase(config: DatabaseConfig) {
  // 连接数据库...
}

const userCredentials: UserCredentials = {
  id: "user123",
  password: "secretPassword",
};

connectToDatabase(userCredentials); // 编译通过，但存在安全风险！

UserCredentials（用户凭证）和 DatabaseConfig（数据库配置）在结构上完全相同，因此 TypeScript 不会报错。但显然，这是两种语义截然不同的类型，将用户密码直接传递给数据库连接函数可能导致严重的安全隐患或逻辑错误。

一个更具体的例子：坐标与颜色的混淆

让我们看一个更直观的例子，考虑 3D 坐标和 RGB 颜色值：

interface Point3D {
  x: number;
  y: number;
  z: number;
}

interface Color {
  r: number;
  g: number;
  b: number;
}

function calculateDistance(point: Point3D): number {
  return Math.sqrt(point.x ** 2 + point.y ** 2 + point.z ** 2);
}

const color = { r: 255, g: 0, b: 0 };
// 假设我们不小心把颜色对象的属性名写成了 x, y, z
const colorAsPoint = { x: 255, y: 0, z: 0 };

calculateDistance(colorAsPoint); // 编译通过，但计算“颜色的距离”毫无意义

尽管在数学计算上 colorAsPoint 可以被视为一个 Point3D，但这在业务逻辑上是完全错误的。这类问题在处理大量同构数值数据（如 ID、金额、时间、距离单位）时尤其容易发生。

Branded Types 的核心概念与实现

Branded Types 的核心思想是给现有的基础类型（如 string, number）附加一个独特的“品牌标记”，从而在类型层面将它们区分开来，即使它们的运行时结构完全一致。

基础实现模式

最简单的方式是使用交叉类型（&）为类型添加一个独特的字面量属性：

type UserId = string & { readonly __brand: “userId“ };
type OrderId = string & { readonly __brand: “orderId“ };

function createUserId(id: string): UserId {
  return id as UserId;
}

function createOrderId(id: string): OrderId {
  return id as OrderId;
}

const userId = createUserId(“user-123“);
const orderId = createOrderId(“order-456“);

function processUser(id: UserId) {
  console.log(`Processing user: ${id}`);
}

processUser(userId); // OK
processUser(orderId); // 编译错误：类型“OrderId”的参数不能赋给类型“UserId”的参数。

这里，UserId 和 OrderId 在运行时都是普通的字符串，但在编译时，TypeScript 会因它们拥有不同的 __brand 标记而将其视为不同的类型，从而阻止误用。

使用泛型构建可复用工具类型

为了提高代码的复用性，我们可以定义一个通用的 Branded 工具类型：

type Branded<T, Brand> = T & { readonly __brand: Brand };

type Meters = Branded<number, “meters“>;
type Seconds = Branded<number, “seconds“>;

function meters(value: number): Meters {
  return value as Meters;
}

function seconds(value: number): Seconds {
  return value as Seconds;
}

const distance = meters(100);
const time = seconds(60);

function calculateSpeed(distance: Meters, time: Seconds): number {
  return distance / time;
}

calculateSpeed(distance, time); // OK
calculateSpeed(time, distance); // 编译错误：参数顺序错误，类型不匹配

这种方式在处理带单位的数值时非常有用，能确保物理计算的正确性，并大幅提升代码的可读性和安全性。这种通过添加“标记”来区分类型的思想，与一些 Java 中通过封装类来保证类型安全的模式有异曲同工之妙。

总结与适用场景

Branded Types 是一种强大而轻量的技术，它通过在编译期添加类型“指纹”，巧妙地弥补了 TypeScript 结构性类型系统的不足。它尤其适用于以下场景：

• 区分不同含义的 ID：如用户ID、订单ID、产品ID等，防止在操作 数据库 时传递错误的ID。
• 强化单位类型：如米、秒、美元、百分比等，确保数值运算在语义上的正确性。
• 标记已验证数据：如“已校验的邮箱地址”、“已排序的数组”等，在类型系统中传递业务规则的状态。

通过引入 Branded Types，你可以在不牺牲 TypeScript 灵活性的前提下，为项目注入更强的类型约束和领域表达能力，从根本上杜绝一大类因类型混淆而产生的错误。