我把订单 ID 当成用户 ID 传进了函数,TypeScript 却一声不吭:结构化类型系统给我上的那一课

这个 bug,藏在一个我以为"类型系统会帮我兜底"的地方,结果它没兜住,还让我栽了个跟头。我的代码里,有 用户ID 和 订单ID 两种 ID,它们在业务上是完全不同的东西——用户 ID 用来查用户,订单 ID 用来查订单。我用 TypeScript 给它们都定义了类型,自以为类型系统会帮我守好"别把订单 ID 当用户 ID 用"这条线。可有一次,我在一个查询用户的函数里,手滑把一个订单 ID 传了进去——而 TypeScript,从头到尾,一声不吭,编译顺利通过。直到运行时,这个函数拿着订单 ID 去用户表里查,查了个寂寞,引发了一连串下游的 bug,我才发现了这个问题。

我当时很困惑,也有点失望:我明明给它们定义了不同的类型啊,TypeScript 怎么会允许我把订单 ID 传给一个期望用户 ID 的参数?它不是号称"类型安全"吗?直到我深入理解了 TypeScript 类型系统的一个根本特性,才恍然大悟——原来,我对 TypeScript "如何判断两个类型是否兼容",有一个根本性的误解:TypeScript 用的是"结构化类型(structural typing)"——它判断两个类型是否兼容,看的是它们的"结构(有哪些字段、字段是什么类型)"是否匹配,而完全不看它们的"名字"。而我的 用户ID 和 订单ID,虽然名字不同、业务含义天差地别,但它们的"结构"——都是 { value: string }——是完全相同的!所以在 TypeScript 眼里,它们就是同一种类型,可以随意互换,它当然不会报错。

故障现场:两个"不同"的类型,却被当成了一种

我把出问题的代码,简化一下。你会看到,两个"不同"的 ID 类型,被毫无障碍地互换了:

// 我定义了两种 ID 类型, 想用类型区分用户ID和订单ID
interface UserId {
  value: string;
}
interface OrderId {
  value: string;
}
// 注意: 它们的"结构"完全一样, 都是 { value: string } !

function getUser(id: UserId) {
  // ... 用 id.value 去用户表查用户 ...
  console.log("查询用户:", id.value);
}

const orderId: OrderId = { value: "ORDER-12345" };

getUser(orderId);   // ← 我手滑把订单ID传给了 getUser!
//   我期望: TypeScript 报错 "OrderId 不能赋值给 UserId"
//   实际上: TypeScript 一声不吭, 编译通过! 😱
//   → 因为 UserId 和 OrderId 的"结构"完全相同, TS 认为它们兼容!
//   → 运行时: 拿着 "ORDER-12345" 去用户表查, 查不到, 引发下游 bug!

看清这一点,我才明白 TypeScript 为什么"没拦住"我。问题的核心是:我以为给两个 ID "起了不同的名字(UserId 和 OrderId)",TypeScript 就会把它们当成两种不同的、不能互换的类型。可 TypeScript 根本不看名字——它判断两个类型兼不兼容,看的是它们的"结构":有哪些属性、每个属性是什么类型。而我的 UserId 和 OrderId,结构是一模一样的——都只有一个 value: string 属性。在 TypeScript 的"结构化"眼光里,这两个类型,就是同一种类型,完全可以互相赋值、互相传递。所以,当我把一个 OrderId 传给期望 UserId 的 getUser 时,TypeScript 一看:"哦,你传的这个东西,有一个 value: string 属性,符合 UserId 的结构要求,那就是合法的呀!"——于是,它愉快地放行了。我精心起的两个不同的"名字",在结构化类型系统面前,毫无作用;它们俩,从一开始,就被 TypeScript 当成了同一种类型。

第一件事:搞懂"结构化类型" vs "名义类型"

定位到根源,我必须搞懂 TypeScript 这个"结构化类型"到底是怎么回事,以及它和另一种类型系统的区别:类型系统判断"两个类型是否相同/兼容",大体有两种流派。一种是"名义类型(nominal typing)"——看"名字":两个类型,只有名字相同(或有明确的继承关系),才算兼容,Java、C# 等大多采用这种。另一种是"结构化类型(structural typing)"——看"结构":两个类型,只要结构(成员)匹配,就算兼容,哪怕名字完全不同,TypeScript、Go 的接口等采用这种。

// 两种类型系统的根本区别:

// 名义类型(nominal, 如 Java/C#): 看"名字", 名字不同就不兼容
//   class UserId {...}  class OrderId {...}
//   就算结构一样, UserId 和 OrderId 也是【不同】的类型, 不能互换。
//   (Java 里把 OrderId 传给要 UserId 的方法 → 编译报错)

// 结构化类型(structural, TypeScript): 看"结构", 结构匹配就兼容
interface UserId { value: string; }
interface OrderId { value: string; }
//   结构相同 → TS 认为它们【完全兼容】, 可以互换! (我的坑)

// TypeScript 结构化类型的更多体现:
interface Point { x: number; y: number; }
function draw(p: Point) {}
// 即使一个对象不是"声明为 Point"的, 只要结构匹配, 就能传:
draw({ x: 1, y: 2 });                          // ✓ 字面量, 结构匹配
const vec = { x: 1, y: 2, z: 3 };
draw(vec);                                      // ✓ 多个属性也行(只要包含所需的)
class Vector2D { constructor(public x: number, public y: number) {} }
draw(new Vector2D(1, 2));                        // ✓ class 实例, 结构匹配也行!

// 这就是 TS 的"鸭子类型": 长得像鸭子(结构匹配), 就当成鸭子, 不管它"叫什么"。

原理终于清晰了。类型系统判断"两个类型兼不兼容",有两大流派。"名义类型"(Java、C# 等)看的是"名字"——两个类型,名字不同(且无继承关系),就是不同的类型,绝不能互换,哪怕它们结构一模一样。"结构化类型"(TypeScript、Go 接口等)看的是"结构"——两个类型,只要结构(有哪些成员、成员是什么类型)匹配,就兼容、就能互换,完全不管它们叫什么名字。TypeScript,采用的正是"结构化类型"。这也是为什么 TypeScript 里,一个"没被声明为 Point"的对象字面量 {x:1, y:2}、甚至一个 Vector2D 类的实例,只要结构符合 Point,就能传给一个期望 Point 的函数——这就是俗称的"鸭子类型(duck typing)":如果一个东西走起来像鸭子、叫起来像鸭子(结构像鸭子),那就把它当鸭子,根本不在乎它"自称"是什么。而我的坑,正是这个特性的"阴暗面":我的 UserId 和 OrderId 结构相同,所以在结构化类型系统看来,它们就是"同一种鸭子",可以随意互换——TypeScript 帮我做了它"认为正确"的事,却没能帮我守住那条我真正想要的、"按业务含义区分"的界线。

第二件事:正解——用"品牌类型(branded type)"模拟名义类型

搞懂了根因——"结构相同的类型,在结构化类型系统里被视为同一种"——正解就清晰了:既然 TypeScript 看结构、不看名字,那我就人为地给它们的结构,制造一点差异,让它们的结构不再相同——加一个独一无二的、用来"标记身份"的属性。这就是"品牌类型(branded type)"或"名义类型模拟"的技巧。

// 正解: 用"品牌(brand)"给类型加一个独一无二的标记, 让结构不再相同
type UserId = string & { readonly __brand: "UserId" };   // 加个"品牌"标记
type OrderId = string & { readonly __brand: "OrderId" };  // 不同的"品牌"

// 现在, UserId 和 OrderId 的"结构"不同了(品牌标记不同),
// TypeScript 就会把它们当成【不同】的类型, 不能互换!

function getUser(id: UserId) { /* ... */ }

// 创建品牌类型的值, 需要一个"构造/断言"函数:
function asUserId(id: string): UserId { return id as UserId; }
function asOrderId(id: string): OrderId { return id as OrderId; }

const userId = asUserId("USER-1");
const orderId = asOrderId("ORDER-12345");

getUser(userId);    // ✓ 正确
getUser(orderId);   // ✗ 编译报错! "OrderId 不能赋值给 UserId" —— 终于拦住了!

// 原理: __brand 这个属性, 实际上"不存在"于运行时(只是类型层面的标记),
//   它的唯一作用, 就是让 UserId 和 OrderId 在【类型结构】上不同,
//   从而骗过结构化类型系统, 实现"名义类型"般的区分。

// 更优雅的写法(用泛型封装):
declare const brand: unique symbol;
type Brand = T & { readonly [brand]: B };
type UserId2 = Brand;
type OrderId2 = Brand;

这个正解的核心,是用一个"品牌标记"属性,人为地给两个本来结构相同的类型,制造出结构上的差异,从而让结构化类型系统把它们识别为不同的类型。我给 UserId 加上 { __brand: "UserId" }、给 OrderId 加上 { __brand: "OrderId" }——这两个 __brand 的字面量类型不同,于是 UserId 和 OrderId 的整体结构就不再相同了。这样,TypeScript 就会把它们当成两种不同的类型,我再想把 OrderId 传给期望 UserId 的函数,它就会报错了——我终于得到了我想要的、"按业务含义区分"的类型安全。这里有个巧妙之处:那个 __brand 属性,在运行时根本不存在(它只是个类型层面的标记,通过 as 断言"凭空"赋予)——它不增加任何运行时开销,唯一的作用,就是在类型层面,给两个类型制造出"结构差异",从而"骗过"结构化类型系统、实现"名义类型"般的、按名字(品牌)区分的效果。这个"品牌类型"技巧,是 TypeScript 里在需要严格区分'结构相同、但语义不同'的类型时,一个非常实用的模式。

下面这张图,对比了"普通类型"和"品牌类型"在区分 ID 上的表现:

这张图的对比很清楚:左边红色那条,用普通 interface,两个类型结构相同、被结构化类型系统视为同一种,传错 ID 不报错、运行时引发 bug;右边绿色那条,用品牌类型给各自加上不同的 brand 标记,两个类型结构不再相同、被 TS 视为不同类型,传错 ID 编译就报错、拦住了。两条路的根本分野,在于你有没有用"品牌"给结构相同的类型,制造出结构上的差异。

第三件事:结构化类型,何时是福、何时是祸?

填平了这个坑,我没有简单地把结构化类型当成"坏东西"。深入思考后,我发现它其实是一把"双刃剑"——在很多场景下,它的"灵活",恰恰是巨大的优点;只有在少数需要"严格区分语义"的场景,它才会变成坑:

// 结构化类型的"福"(它的优点, 大多数时候很爽):

// 福1: 灵活, 不必显式声明"实现了某接口"
interface Logger { log(msg: string): void; }
function useLogger(l: Logger) {}
// 任何"恰好有 log 方法"的对象都能传, 不用显式 implements:
useLogger({ log: (m) => console.log(m) });      // ✓ 直接传, 很方便
useLogger(console);                              // ✓ console 恰好有 log, 直接用!

// 福2: 鸭子类型让"对接第三方/旧代码"更轻松
//   你不需要让别人的类型"继承"你的接口, 只要结构匹配就能用。

// 福3: 处理"数据形状"时非常自然(尤其前端处理 JSON)
function render(user: { name: string; age: number }) {}
render(apiResponse);   // 只要 apiResponse 结构匹配, 直接用, 不用转换

// 结构化类型的"祸"(它的坑, 少数时候很疼):

// 祸1: 结构相同、语义不同的类型, 被混用 (本文的坑: UserId vs OrderId)
// 祸2: 一些"恰好结构相同"的无关类型, 被意外当成兼容
type Celsius = number;   // 摄氏度
type Fahrenheit = number; // 华氏度
function setTemp(c: Celsius) {}
setTemp(100 as Fahrenheit);   // 不报错! 但 100 华氏度 != 100 摄氏度, 语义错了!
//   → 这类"单位/语义"的混淆, 也要靠品牌类型来区分

这一思考,让我对结构化类型,有了辩证、不偏激的认识。它绝不是一个"设计失误",而是一把双刃剑——在绝大多数场景下,它的"灵活"是巨大的优点;只在少数需要"严格区分语义"的场景,它才会变成坑。它的"福":结构化类型让你不必显式地 implements 某个接口,任何"恰好结构匹配"的对象都能用(console 恰好有 log 方法,就能当 Logger 用),这让对接第三方代码、处理 JSON 数据,变得无比轻松自然——这种"鸭子类型"的灵活,正是 TypeScript 用起来"爽"的重要原因。它的"祸":则集中在"结构恰好相同、但语义截然不同"的类型上——除了我这次的 UserId vs OrderId,还有更典型的"单位混淆":Celsius(摄氏度)和 Fahrenheit(华氏度)都是 number,结构完全相同,结构化类型会允许你把华氏度传给期望摄氏度的函数,而 100 华氏度根本不等于 100 摄氏度——这种"语义/单位"的混淆,后果可能很严重。所以,正确的态度,不是'否定结构化类型',而是'理解它的双刃剑特性':享受它在绝大多数场景下的灵活,同时,在那些'结构相同但语义/单位必须严格区分'的少数关键场景,主动地用品牌类型,去补上它'不看名字'的短板。

第四件事:什么时候该用品牌类型?——别滥用

学会了品牌类型这个利器,我也提醒自己:别走极端、到处滥用它。我梳理了一下"哪些场景值得用品牌类型、哪些场景不必",免得为了"类型安全"而牺牲了代码的简洁:

// 哪些场景"值得"用品牌类型(收益 > 成本):

// 场景1: 多种"结构相同、但绝不能混淆"的 ID
type UserId = Brand;
type OrderId = Brand;
type ProductId = Brand;
//   → 系统里 ID 多, 又都是 string, 极易传错 → 品牌类型价值大

// 场景2: 带"单位/语义"的数值, 混淆后果严重
type Meters = Brand;
type Feet = Brand;
type Milliseconds = Brand;
type Seconds = Brand;
//   → 单位混淆(如 NASA 火星探测器因单位错误坠毁) → 品牌类型能救命

// 场景3: 经过"校验"的值, 用类型标记"已校验"
type ValidatedEmail = Brand;
function validateEmail(s: string): ValidatedEmail | null { /* 校验 */ }
function sendEmail(to: ValidatedEmail) {}  // 只接受"已校验"的邮箱, 强制先校验!

// 哪些场景"不必"用品牌类型(成本 > 收益):

// 不必1: 类型只在很小范围内用, 不易传错 → 普通类型就够了
// 不必2: 临时的、内部的数据结构 → 别为它套品牌, 增加心智负担
// 不必3: 团队不熟悉这个模式 → 滥用会让代码难懂, 要权衡

// 核心: 品牌类型是"成本(代码啰嗦一点)换安全"的工具,
//   在"传错的风险高、传错的后果重"的地方用它, 才划算。

这一梳理,让我对品牌类型这个工具,有了"用在刀刃上"的判断。品牌类型不是免费的——它会让代码啰嗦一点(需要构造函数、需要 as 断言),增加一点心智负担。所以它是一个"用成本换安全"的工具,应该用在"传错的风险高、且传错的后果严重"的地方,才划算。值得用的场景:系统里有多种结构相同的 ID(UserId/OrderId/ProductId,极易传错);带单位的数值(Meters/Feet、Milliseconds/Seconds,单位混淆后果可能很严重——著名的 NASA 火星气候探测者号,就是因为单位混淆而坠毁的);以及"经过校验的值"(用 ValidatedEmail 标记"这个 string 已经校验过了",强制调用方先校验)。不必用的场景:类型只在很小范围内用、不易传错;临时的内部数据结构;团队不熟悉这个模式时(滥用会让代码难懂)。所以,品牌类型的使用,本身也是一个'权衡'——在'类型安全的收益'和'代码复杂度的成本'之间,根据具体场景做判断。在'高风险、高后果'的地方果断用它,在'低风险'的地方则保持简洁,这才是成熟的用法。把"该不该用品牌类型"的判断整理成一张表:

第五件事:理解类型系统的"哲学",才能真正用好它

这次踩坑,让我把对 TypeScript 的理解,从"会写类型注解",提升到了"理解它类型系统的哲学"。我意识到,要真正用好一个类型系统,关键是理解它"如何判断类型、它的设计取舍是什么":

理解一个类型系统, 要理解它的几个核心"取舍":

# 取舍1: 结构化 vs 名义 (本文)
#   - 结构化(TS): 灵活、鸭子类型友好, 但结构相同就混用
#   - 名义(Java): 严格、按名字区分, 但啰嗦、对接不灵活
#   → TS 选了结构化, 因为它要和 JS 的"动态、灵活"哲学相符。

# 取舍2: 编译时 vs 运行时
#   - TS 类型只在编译时存在, 运行时擦除 (所以外部数据要运行时校验)
#   → TS 选了"零运行时开销", 代价是管不了运行时。

# 取舍3: 严格 vs 宽松 (可配置)
#   - strict 模式: 更严格、更安全, 但更"烦"
#   - 非 strict: 更宽松、更易上手, 但漏洞多
#   → TS 让你自己选(配置), 给了灵活性。

# 取舍4: 类型推断 vs 显式标注
#   - TS 有强大的类型推断, 能少写很多注解
#   → 但推断有局限, 关键处仍需显式标注。

核心: 每个类型系统, 都是一系列"设计取舍"的结果;
  理解了这些取舍("它为什么这样设计、它牺牲了什么"),
  你才能既用足它的长处, 又主动补上它的短处(如用品牌类型补结构化的短)。

这个升华,让我对"用好类型系统"这件事,有了更高的认识。它的关键,不在于'记住更多的类型语法',而在于'理解这个类型系统背后的哲学与取舍'。TypeScript 的类型系统,是一系列有意为之的设计取舍的结果:取舍1(结构化 vs 名义)——它选了结构化,因为这和 JavaScript "动态、灵活、鸭子类型"的哲学相符,代价是"结构相同就混用"(我的坑)。取舍2(编译时 vs 运行时)——它选了"类型只在编译时存在、零运行时开销",代价是管不了运行时的外部数据。取舍3(严格 vs 宽松)——它把"多严格"做成了可配置的(strict 模式),把选择权交给你。取舍4(推断 vs 标注)——它有强大的类型推断,但关键处仍需你显式标注。理解了这些取舍,你就不会再天真地以为'TypeScript 会帮我兜住一切类型问题',而是会清醒地知道:它在哪些地方强(且为什么强)、在哪些地方有意识地'放手了'(且为什么放手)——然后,在它'放手'、而你又需要严格的地方(比如结构相同的 ID),主动地用它提供的其它工具(如品牌类型),去补上那块短板。'理解一个系统的设计哲学与取舍,从而既用足它的长处、又主动补上它的短处'——这才是真正用好任何一个工具、任何一个系统的、最高层次的境界。把这几个核心取舍和它们的影响整理成一张表:

一张"要不要用品牌类型严格区分"的决策图

把这次踩坑沉淀成一张图。每当你定义结构相同、语义不同的类型时,照着它判断:

这张图的核心判断:有多个"结构相同、语义不同"的类型,且它们被传错的风险高、后果重(如多种 ID、带单位的数值),就用品牌类型强制区分;否则,结构化类型已经够用,别过度设计。把"结构相同但绝不能混的,用品牌区分"变成本能,那个"传错 ID 不报错"的坑就再也碰不到你。

我立下的几条 TypeScript 类型使用规矩

这次"订单 ID 当用户 ID 传、TS 不报错"的事故后,我给自己立了几条规矩:

1. 记住 TS 是结构化类型:时刻清楚 TS 按"结构"而非"名字"判断类型兼容,别指望"起了不同名字"就能区分。
2. 关键 ID/单位用品牌类型:多种结构相同、却绝不能混的 ID 或带单位数值,用品牌类型强制区分。
3. 已校验的值用类型标记:用品牌类型标记"已校验"的值(如 ValidatedEmail),强制调用方先校验。
4. 别滥用品牌类型:只在"传错风险高、后果重"的地方用,低风险场景保持简洁,别过度设计。
5. 理解类型系统的取舍:理解 TS 结构化/编译时擦除/可配置严格度等取舍,知道它强在哪、放手在哪。
6. 在 TS 放手处主动设防:TS 管不到的地方(结构相同的语义区分、运行时外部数据),主动用品牌类型/运行时校验补上。
7. 开 strict 模式:打开 strict,让 TS 的类型保护尽可能强。

这几条里,第一条"记住 TS 是结构化类型"是认知的根基,第二条"关键 ID 用品牌类型"是直接的解法。而贯穿所有规矩的那条主线,是对"工具如何理解世界"的理解。我这次栽跟头,根子上是我用"我以为的方式(按名字区分)",去揣度 TypeScript "实际的方式(按结构区分)"——我和这个工具,对"两个类型是否相同"这件事,有着不同的理解,而我却想当然地以为它和我想的一样。每一个工具,都有它自己'理解世界、做出判断'的一套'内在逻辑';而我们用工具时,常常会下意识地、用'我们自己的逻辑'去揣测'工具的逻辑',以为它会像我们一样思考、一样判断。可一旦工具的内在逻辑,和我们的预期不一致(比如 TS 按结构判断、而我以为它按名字判断),这种'认知的错位',就会让我们对工具的行为产生误判,从而栽跟头。真正用好一个工具的前提,是放下'它会像我一样想'的想当然,去真正理解'它实际是怎么想、怎么判断的'。

写在最后:别用"你以为的逻辑",去揣测"工具的逻辑"

这次被 TypeScript 结构化类型教育的经历,给我一个超越 TypeScript 本身的、深刻的启示:我们和工具之间,常常存在一种隐蔽的'认知错位'——我们用'人类的、直觉的逻辑'去揣测工具,以为它会像我们一样思考、判断;可工具,有它自己的、可能和我们的直觉截然不同的'内在逻辑'。而当我们误以为'工具和我想的一样',却没去核实'它实际是怎么想的'时,就会在这种错位里,被它'出乎意料'的行为坑到。我直觉地以为,"给两个类型起了不同的名字,它们就是不同的类型"(这是人类按"名字"区分事物的、很自然的逻辑);可 TypeScript 的逻辑,是按"结构"区分——它和我的直觉,在这个根本点上,是错位的。而我没有意识到这种错位、没去核实 TS "实际是怎么判断类型的",就想当然地依赖它,于是栽了跟头。

想通这一点,我对待每一个工具的"行为",都多了一份"它实际是怎么想的"的审慎,而非"它应该会像我想的那样"的想当然。这个世界上的每一个工具、每一个系统、每一套规则,都有它自己的'内在逻辑'——它如何判断、如何取舍、如何对输入做出反应,背后都有一套属于它自己的、未必符合我们人类直觉的'道理'。而我们和工具打交道时,最危险的,莫过于'用自己的直觉,去替工具做判断',以为'它会和我想的一样',却从不去核实'它实际是怎么想的'。这种'想当然的代入',是无数'工具行为出乎意料'的坑的共同根源。真正成熟的工具使用者,会有一种可贵的谦逊——他不假设工具会按自己的直觉行事,而是带着好奇,去真正搞清楚'这个工具,它实际是按什么逻辑在判断、在工作的';然后,基于工具'真实的逻辑'(而非'我以为的逻辑')去使用它、去预判它的行为。放下'它会像我一样想'的傲慢,去理解'它实际是怎么想的'真相——这是和一切工具、系统打交道时,一份重要的清醒。

所以,如果你也想真正用好、用对手中的各种工具,我想把这次踩坑最想说的话送给你:别用'你以为的逻辑',去揣测'工具的逻辑';而要花力气,去搞清楚'这个工具,它实际是怎么思考、怎么判断的'。它判断类型,是按名字还是按结构?它处理空值,是宽容还是严格?它执行查询,是立即还是延迟?它比较对象,是比值还是比引用?——对这些'工具如何做判断'的问题,别想当然地代入你的直觉,而要去真正地搞清楚它'实际的逻辑'。因为工具有它自己的逻辑,而这个逻辑,未必和你的直觉一致;只有当你真正理解了工具'实际是怎么想的',你才能准确地预判它的行为、用对它、并在它的逻辑和你的需求不一致的地方,主动地想办法弥补。而很多让人措手不及的坑,追根溯源,都是因为我们用'自己的逻辑',替工具'想当然'了,却忘了去问一句:它,实际上是怎么想的?那个把订单 ID 当用户 ID 放行的 TypeScript,最终教给我的,正是这份'去理解工具真实逻辑'的清醒——它让我懂得,和工具相处,不能靠'我以为它会怎样'的一厢情愿,而要靠'我搞清楚了它实际会怎样'的扎实理解;唯有看清了工具内在逻辑的真相,你才能真正地驾驭它,而不是被它出乎你意料的行为,反复地、莫名其妙地坑到。

—— 别看了 · 2026