我给两个含义完全不同的 ID 都用了 string 类型,结果把商品 ID 当成用户 ID 传了进去,TypeScript 却一声没吭,我排查了大半天才搞懂结构化类型的深度复盘

这是一个让我对 TypeScript "结构化类型"刻骨铭心的故事。我的系统里,有用户 ID,也有商品 ID——它们俩,含义完全不同,但底层,我都用了 string 类型来表示。我有一个函数 getUser(id: string),要传入用户 ID;某次写代码时,我手一滑,把一个商品 ID,传给了它。在我朴素的认知里,既然我用了 TypeScript——这个号称"类型安全"的语言——这种"把商品 ID 当用户 ID 用"的张冠李戴,它总该帮我拦下来吧?

可现实是:TypeScript,一声没吭!它没有任何报错、任何警告,顺顺利利地,就让我把商品 ID,传进了那个要用户 ID 的函数里。然后,这个 bug,带着错误的 ID,一路畅通无阻地跑下去,直到在很深的地方,因为"查不到这个用户"而出错——而那时,我早已忘了,问题的源头,是那次张冠李戴。我当时很困惑:我明明用了类型啊!一个是逻辑上的"用户 ID"、一个是逻辑上的"商品 ID",它俩含义天差地别,TypeScript 怎么会分不清、还允许我混用?直到我去深究 TypeScript 的类型系统,才恍然大悟,补上了关于它最根本的一课:原来,TypeScript 用的,是"结构化类型(structural typing)",而不是像 Java、C# 那样的"名义类型(nominal typing)"!这两者,有一个根本性的区别:名义类型,看的是"类型的名字/声明"——两个类型,只有名字相同(或有继承关系),才算兼容;而结构化类型,看的是"类型的结构/形状"——只要两个类型的结构(字段、形状)一样,它们就被认为是兼容的,不管它们叫什么名字、是不是同一个声明!这就是问题所在:我的"用户 ID"和"商品 ID",虽然在我心里,是两个含义截然不同的概念;可在 TypeScript 眼里,它们的结构,是完全一样的——都是 string!既然结构一样,TypeScript 就认为它们完全兼容、可以互换,于是,把商品 ID(一个 string)传给要用户 ID(也是 string)的函数,在它看来,天经地义,毫无问题。它根本不知道,我心里给这两个 string,赋予了"用户"和"商品"这两个不同的业务含义——因为,那个含义,只存在于我的脑子里,而没有体现在"类型的结构"上。我一直以为,我给它们"贴了不同的标签(用户 ID / 商品 ID)",TypeScript 就该按标签区分;可 TypeScript 根本不看标签,它只看结构——而它俩的结构,一模一样。

故障现场:结构相同,TS 就认为可以互换

我把这个"张冠李戴却不报错"的现场,用代码摊开给你看:

// ✗ 灾难: 两个含义不同的 ID, 底层都是 string
function getUser(userId: string) { /* ... */ }

const productId: string = "P-12345";
getUser(productId);   // ✗ 把商品 ID 传给了要用户 ID 的函数! TS 一声没吭!
//      ↑ 因为它俩都是 string, 结构一样, TS 认为完全兼容、可以互换。

// 更进一步: 即使用了 interface, 只要"结构一样", 也互换
interface Dog { name: string; }
interface Cat { name: string; }
function pet(dog: Dog) { /* ... */ }
const cat: Cat = { name: "咪咪" };
pet(cat);             // ✗ 把 Cat 传给要 Dog 的函数! TS 也不报错!
//      ↑ Dog 和 Cat 结构一样(都只有 name: string)→ TS 认为兼容!

// 为什么? TS 用"结构化类型(structural typing)":
//   - 看的是"类型的结构/形状", 不是"类型的名字/声明"。
//   - 结构(字段、形状)一样 → 就认为兼容、可互换, 不管叫什么名字。
//   - 这和 Java/C# 的"名义类型(nominal)"相反——那里, 名字不同就不兼容。

// 后果: "业务含义不同、但结构相同"的类型, 会被 TS 当成可互换 → 张冠李戴不报错。
//   - userId 和 productId(都 string)互传, 不报错。
//   - 不同含义的 {id: number}、不同单位的 number(米/英尺), 都可能混用。

// 根因: 我以为 TS 按"名字/标签"区分类型(名义类型的直觉),
//   但 TS 是"结构化类型"——只看结构。结构一样, 它就放行, 不管业务含义。
//   而"业务含义"只在我脑子里, 没体现在"类型结构"上 → TS 帮不了我。

看着这段代码,我才算真正理解了这个"张冠李戴却不报错"的根源。问题的核心,是 TypeScript 用的,是"结构化类型(structural typing)",而不是像 Java、C# 那样的"名义类型(nominal typing)"。这两者,有一个根本性的区别:名义类型,看的是"类型的名字/声明"——两个类型,只有名字相同(或有继承关系),才算兼容;而结构化类型,看的是"类型的结构/形状"——只要两个类型的结构(字段、形状)一样,它们就被认为是兼容的,不管它们叫什么名字、是不是同一个声明。这就是问题所在:我的"用户 ID"和"商品 ID",虽然在我心里,是两个含义截然不同的概念;可在 TypeScript 眼里,它们的结构,是完全一样的——都是 string!既然结构一样,TypeScript 就认为它们完全兼容、可以互换,于是,把商品 ID(一个 string)传给要用户 ID(也是 string)的函数,在它看来,天经地义,毫无问题。而这,不只对基础类型如此——即使我用了 interface:interface Dog { name: string } 和 interface Cat { name: string },只要它们的结构一样(都只有一个 name: string),TypeScript 就认为它们兼容,我把一个 Cat 传给要 Dog 的函数,它照样不报错!归根结底:我一直以为,我给这两个 ID"贴了不同的标签(用户 ID / 商品 ID)",TypeScript 就该按标签来区分;可 TypeScript 根本不看标签,它只看结构——而它俩的结构,一模一样。我心里给这两个 string,赋予的"用户"和"商品"这两个不同的业务含义,只存在于我的脑子里,而没有体现在"类型的结构"上;所以,TypeScript 根本无从知道它们的不同,也就帮不了我。这,是结构化类型,和我"按名字区分"的名义类型直觉之间,那道根本的鸿沟。

第一件事:搞懂结构化类型——看结构,不看名字

定位到根源,我必须把"结构化类型 vs 名义类型"的根本区别,彻底搞清楚:

结构化类型(TS) vs 名义类型(Java/C#)

# 名义类型(nominal typing): Java, C#, ...
#   - 类型兼容, 看"名字/声明": 名字相同(或有继承关系)才兼容。
#   - 两个字段完全一样、但名字不同的类, 不兼容(不能互传)。
#   - 直觉: "你是不是 User 类? 不是就不行"(认名分)。

# 结构化类型(structural typing): TypeScript, Go(部分), ...
#   - 类型兼容, 看"结构/形状": 结构一样就兼容, 不管名字。
#   - "鸭子类型": 走起来像鸭子、叫起来像鸭子, 它就是鸭子。
#   - 直觉: "你有没有 User 需要的那些字段? 有就行"(认实质)。

# TS 是结构化的, 所以:
#   - userId: string 和 productId: string → 结构一样(都 string)→ 可互换!
#   - interface Dog{name} 和 Cat{name} → 结构一样 → 可互换!
#   - 一个对象, 只要"有目标类型要求的字段"(可以多, 多的没事), 就兼容。

# 结构化类型的好处(它为什么这么设计):
#   - 灵活: 不用显式 implements/extends, 只要"长得对"就能用(鸭子类型)。
#   - 方便: 传个字面量对象、或来自别处的对象, 只要结构对就行。

# 结构化类型的"坑"(本文):
#   - "业务含义不同、但结构相同"的类型, 会被当成可互换 → 张冠李戴不报错。
#   - 它防的是"结构不对", 防不了"结构对、但语义错"。

# 关键认知: TS 看"形状", 不看"名字/你赋予的业务含义"。
#   想让"语义不同"的类型不可混用, 要主动给它们"结构上的区别"(下一节)。

# 核心: TS 是结构化类型——结构一样就兼容, 不管名字和业务含义。
#   它的灵活是优点; 但"结构相同、语义不同"会被混用, 是要警惕的坑。

原理终于清晰了。名义类型(nominal typing)(Java、C# 等):类型兼容,看的是"名字/声明"——名字相同(或有继承关系)才兼容;两个字段完全一样、但名字不同的类,是不兼容的;它的直觉是"你是不是 User 类?不是就不行"(认名分)。而 结构化类型(structural typing)(TypeScript、部分 Go 等):类型兼容,看的是"结构/形状"——结构一样就兼容,不管名字;这就是著名的"鸭子类型"——走起来像鸭子、叫起来像鸭子,它就是鸭子;它的直觉是"你有没有 User 需要的那些字段?有就行"(认实质)。所以,TS 是结构化的,就有了:userId: string 和 productId: string 结构一样(都 string)→ 可互换;Dog{name} 和 Cat{name} 结构一样 → 可互换;一个对象,只要"有目标类型要求的字段"(多了也没事),就兼容。结构化类型,有它的好处(它为什么这么设计):灵活(不用显式 implements/extends,只要"长得对"就能用)、方便(传个字面量对象、或来自别处的对象,只要结构对就行)。但它也有那个"坑"(本文):"业务含义不同、但结构相同"的类型,会被当成可互换,导致张冠李戴却不报错;它防的是"结构不对",却防不了"结构对、但语义错"。由此,我建立起一个关键认知:TS 看的是"形状",而不看"名字、以及你赋予它的业务含义";所以,想让"语义不同"的类型不可混用,你必须主动地,给它们一个"结构上的区别"(下一节)。归根结底:TS 是结构化类型——结构一样就兼容,不管名字和业务含义;它的灵活,是优点;但"结构相同、语义不同"会被它放行混用,是必须警惕的坑——这,是我用一次"商品 ID 当用户 ID、TS 却一声没吭"的事故,补上的、关于 TS 类型系统最根本的一课。

第二件事:正解——用"品牌类型(branded type)"给它结构上的区别

搞懂了根因——"结构相同就被当成可互换"——正解就清晰了:既然 TS 只看结构,那就给"语义不同"的类型,人为地制造一个"结构上的区别"——这就是"品牌/标称类型(branded / nominal type)"的技巧:用一个"幽灵标记"字段,让两个本来结构相同的类型,在结构上变得不同,从而 TS 就能区分、就不让它们互换了。

// 正解1: 品牌类型(branded type)——给类型加一个"幽灵标记"
// 用一个不存在于运行时、只为类型区分的标记, 让结构变得不同
type UserId = string & { readonly __brand: "UserId" };
type ProductId = string & { readonly __brand: "ProductId" };
//   ↑ UserId 和 ProductId 现在"结构不同"了(__brand 标记不同) → TS 能区分!

// 构造一个 UserId(需要断言, 因为运行时它就是 string)
function toUserId(s: string): UserId { return s as UserId; }

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

const productId = "P-123" as ProductId;
// getUser(productId);   // ✓ 现在 TS 报错了! ProductId 不能赋给 UserId
const userId = toUserId("U-456");
getUser(userId);          // ✓ 正确, 编译通过
// → 通过"幽灵标记"制造结构差异, 让语义不同的类型, 不能再混用!
// (__brand 只在编译期存在, 运行时 UserId 就是普通 string, 零开销)

// 正解2: 用"可辨识联合(discriminated union)"区分语义不同的对象
interface Dog { kind: "dog"; name: string; }   // 加一个 kind 标记字段
interface Cat { kind: "cat"; name: string; }    // 结构因 kind 而不同
function pet(dog: Dog) { /* ... */ }
const cat: Cat = { kind: "cat", name: "咪咪" };
// pet(cat);   // ✓ 报错! kind: "cat" 不能赋给 kind: "dog"
// → 给对象加一个"判别字段(kind/type)", 让结构上就能区分。

// 正解3: 接受结构化类型, 靠"测试 + 命名 + 评审"兜底
//   - 不是所有场景都值得上 branded type(它有点繁琐)。
//   - 简单场景: 靠清晰的命名、单元测试、code review 来减少张冠李戴。
//   - 高风险场景(钱、ID、单位): 才值得用 branded type 强约束。

// 核心: TS 只看结构, 那就"给语义不同的类型, 制造结构差异"——
//   品牌类型(幽灵标记)或判别字段。让 TS 能区分、不让它们混用。

这套正解,核心是顺着 TS"只看结构"的特性——给"语义不同"的类型,人为地制造一个"结构上的区别",让 TS 能区分它们。正解1(品牌类型/branded type):用一个"幽灵标记"字段(如 { readonly __brand: "UserId" }),和原类型做交叉(string & {...}),让 UserId 和 ProductId,在结构上变得不同(__brand 标记不同);这样,TS 就能区分它们了——把 ProductId 传给要 UserId 的函数,它就会报错了。(这个 __brand 标记,只在编译期存在,运行时 UserId 就是个普通 string,零运行时开销——它纯粹是给类型检查器看的。)正解2(可辨识联合/discriminated union):对于语义不同的对象,给它们各加一个"判别字段"(如 kind: "dog"/kind: "cat"),让它们的结构因这个字段而不同;这样,把 Cat 传给要 Dog 的函数,TS 也会报错了。正解3(接受结构化类型,靠工程兜底):不是所有场景都值得上 branded type(它确实有点繁琐)——简单场景,靠清晰的命名、单元测试、code review 来减少张冠李戴就够了;只有高风险场景(涉及钱、ID、单位换算),才值得用 branded type 做强约束。归根结底:TS 只看结构,那就"给语义不同的类型,制造结构差异"——用品牌类型(幽灵标记)、或判别字段,让 TS 能区分、不让它们混用。我那次的错误,是放任了"用户 ID"和"商品 ID"结构相同;而正解,就是给它们,一个结构上的、能让 TS 识别的区别。

下面这张图,对比了"裸用 string"和"品牌类型"两条路径:

这张图的对比很清楚:左边红色那条,两个语义不同的类型都用裸 string,结构相同、TS 认为可互换,商品 ID 传成用户 ID 也不报错,张冠李戴的 bug 溜过编译、到深处才爆;右边绿色那条,用品牌类型加"幽灵标记",让它们结构变得不同、TS 能区分,混用时编译就报错,bug 在编译期就被拦下。两条路的根本分野,在于你有没有给语义不同的类型,一个 TS 能识别的"结构差异"。

第三件事:结构化类型的其它表现

填平了"语义混用"这个坑,我系统排查了结构化类型,还有哪些值得知道的表现:

// 结构化类型的其它表现:

// 1. 语义不同、结构相同 → 可互换(本文): branded type 解决。

// 2. "多余字段"通常没事(子类型可赋给父类型)
interface Named { name: string; }
const obj = { name: "x", age: 5 };
const n: Named = obj;   // ✓ obj 有 name(还多了 age), 结构满足 Named → 兼容
// (TS 关心"有没有 Named 要的", 多的不管)

// 3. 但"对象字面量"有"多余属性检查(excess property check)"
const n2: Named = { name: "x", age: 5 };   // ✗ 报错! 字面量直接赋值时,
//                                  多余的 age 会被检查(防手滑写错字段名)
// → 注意: 这个检查只针对"字面量直接赋值", 经过变量中转就不查(如上面 #2)。

// 4. 函数类型也是结构化的(参数/返回值兼容即可)
type Fn = (x: number) => void;
const f: Fn = (x: number, y: number) => {};   // 参数少的可赋给参数多的? 反过来
// (函数参数有"逆变"等规则, 也是按结构判断兼容性)

// 5. class 也是结构化的! 两个字段一样的 class, 实例可互相赋值
//    (即使没有继承关系)——和 Java/C# 很不一样。

// 6. 空对象/any 的兼容性陷阱: {} 几乎和任何对象兼容, 要小心。

// 共同点: 都源于"TS 按结构判断兼容性, 不按名字"。
// 原则: 享受结构化的灵活; 但对"语义需严格区分"的(ID/钱/单位),
//   主动用 branded type / 判别字段, 制造结构差异来约束。

这一排查,让我对结构化类型的各种表现,有了全面的认识。除了"语义不同、结构相同可互换"(本文,用 branded type 解决),还有:"多余字段"通常没事(一个对象只要"有目标类型要的字段",多了也兼容——TS 关心"有没有",不管"多不多");但"对象字面量"有"多余属性检查"(直接用字面量赋值时,多余的字段会被检查报错,这是为了防你手滑写错字段名;但注意,这个检查只针对字面量直接赋值,经过变量中转就不查了);函数类型也是结构化的(参数/返回值兼容即可,且有逆变等规则);class 也是结构化的(两个字段一样的 class,实例可互相赋值,即使没有继承关系——这和 Java/C# 很不一样);空对象 {}/any 的兼容性陷阱({} 几乎和任何对象兼容,要小心)。这些表现的共同点,都源于"TS 按结构判断兼容性,而不按名字"。所以,核心原则就是:享受结构化类型带来的灵活;但对那些"语义需要严格区分"的类型(ID、钱、单位换算),要主动用 branded type 或判别字段,制造出结构上的差异,来加以约束。理解了结构化类型这个根本特性,这些看似零散的表现,就都成了它的自然推论;而你,也就能既用好它的灵活、又防住它"语义混用"的坑。

第四件事:结构化 vs 名义,各自的取舍

这次踩坑,逼我把"结构化类型"和"名义类型"这两种设计,以及它们的取舍,系统地想清楚了:

结构化类型 vs 名义类型: 各有取舍, 没有绝对的好坏

# 结构化类型(TS/Go): 看结构
#   优点:
#   - 灵活: 不用显式声明"实现了某接口", 长得对就能用(鸭子类型)。
#   - 解耦: 一个类型不必"知道"它会被当成什么用; 调用方按结构要求即可。
#   - 方便: 传字面量、传第三方对象, 只要结构对就行, 少很多样板。
#   缺点:
#   - 语义混用: 结构相同、含义不同的类型, 会被当成可互换(本文)。
#   - "意外兼容": 两个本不相关的类型, 碰巧结构一样就兼容, 可能不是你想要的。

# 名义类型(Java/C#): 看名字
#   优点:
#   - 严格: 名字不同就不兼容, 语义不同的类型天然不会混。
#   - 明确: "你必须显式声明是这个类型/实现这个接口"。
#   缺点:
#   - 死板: 必须显式 implements/extends, 样板代码多。
#   - 耦合: 类型要"知道"自己实现了哪些接口。

# 它们不是"谁对谁错", 而是"不同的设计权衡":
#   - 结构化: 偏灵活, 适合 JS 那种动态、鸭子类型的生态。
#   - 名义: 偏严格, 适合大型、强约束的系统。
#   - TS 选了结构化(因为它要兼容 JS 的灵活), 但提供了 branded type
#     等手段, 让你在需要时"模拟名义类型"的严格。

# 用 TS 的智慧: 默认享受结构化的灵活;
#   在"语义必须严格区分"的地方(ID、钱、单位、状态), 用 branded type
#   局部地引入名义类型的严格。两者结合, 既灵活又安全。

# 核心: 结构化(灵活) vs 名义(严格), 各有取舍。
#   TS 是结构化的, 但能用 branded type 在需要处模拟名义类型。

这一思考,让我对这两种类型系统,有了不带偏见的、辩证的理解——它们没有绝对的好坏,而是不同的设计权衡。结构化类型(TS/Go,看结构)的优点:灵活(不用显式声明"实现了某接口",长得对就能用)、解耦(一个类型不必"知道"它会被当成什么用,调用方按结构要求即可)、方便(传字面量、传第三方对象,只要结构对就行,少很多样板代码);它的缺点:语义混用(结构相同、含义不同的类型被当成可互换,本文)、意外兼容(两个本不相关的类型,碰巧结构一样就兼容)。名义类型(Java/C#,看名字)的优点:严格(名字不同就不兼容,语义不同的类型天然不会混)、明确(你必须显式声明是这个类型);它的缺点:死板(必须显式 implements/extends,样板多)、耦合(类型要"知道"自己实现了哪些接口)。所以,它们不是"谁对谁错",而是不同的设计权衡:结构化偏灵活(适合 JS 那种动态、鸭子类型的生态)、名义偏严格(适合大型、强约束的系统);TS 选了结构化(因为它要兼容 JS 的灵活),但又提供了 branded type 等手段,让你在需要时"模拟名义类型"的严格。由此,我领悟到用 TS 的智慧:默认,享受结构化类型的灵活;而在"语义必须严格区分"的地方(ID、钱、单位、状态),用 branded type 局部地引入名义类型的严格——两者结合,既灵活、又安全。归根结底:结构化(灵活)和名义(严格),各有取舍;TS 是结构化的,但能用 branded type,在需要的地方,模拟名义类型的严格。理解了这一点,我就不再苛求 TS"像 Java 那样严格",而是学会了用对它的灵活、并在关键处补上它的严格。把两种类型系统的对比,整理成一张表:

第五件事:工具按"它的规则"工作,而非"你以为的规则"

这次踩坑,在认知层面给了我最大的纠偏——它让我警惕"用旧工具的直觉,去想象新工具"。我把这层反思,沉淀了下来:

认知纠偏: 工具按"它自己的规则"工作, 别用别处的直觉去想象它

# 我的误解(错误的):
#   我用"Java/C# 的类型靠名字区分"的直觉, 去想象 TS——
#   以为我"贴了不同的标签", TS 就会按标签区分。
#   → 我把另一个工具(名义类型)的规则, 想当然地, 套到了 TS(结构化)身上。

# 真相: 每个工具/语言, 有它"自己的"规则, 不是你"以为的"规则
#   - TS 的类型兼容规则是"结构化", 不是"名义"(尽管你可能习惯了名义)。
#   - 你脑子里那套"应该怎样"的直觉, 往往来自你熟悉的别的工具;
#     而新工具, 按它自己的规则运行, 不会迁就你的直觉。
#   - 用错误的"心智模型"去用一个工具, 就会对它的行为产生错误预期。

# 这是个普遍的坑: "用 A 的直觉, 去用 B"
#   - 从 Java 来的人, 以为 TS 类型按名字区分(其实按结构)。
#   - 从同步来的人, 以为 async 加上就并发(其实要 await 让出)。
#   - 从一种语言的变量来的人, 以为另一种也是值/引用(其实不同)。
#   → 跨工具/语言时, 最危险的, 是"想当然地迁移旧直觉"。

# 正确的习惯:
#   1. 用一个新工具/语言, 主动去学"它自己的核心规则"(别假设和你熟的一样)。
#   2. 行为反直觉时, 别怪工具"不对", 先问"它的规则到底是什么"。
#   3. 尤其对"看起来很像、其实规则不同"的(如类型系统、相等、作用域)要警惕。

核心: 工具按"它自己的规则"工作, 不按你"从别处带来的直觉"。
  用新工具前, 先搞懂它的规则——别用旧直觉, 去想象一个新世界。

这层反思,是这次踩坑给我最高维度的收获。复盘我的误解,根源是:我用"Java/C# 的类型靠名字区分"的直觉,去想象 TypeScript——以为我"贴了不同的标签",TS 就会按标签来区分。我把另一个工具(名义类型)的规则,想当然地,套到了 TS(结构化类型)身上。可真相是:每个工具/语言,都有它"自己的"规则,而不是你"以为的"规则——TS 的类型兼容规则是"结构化",而不是"名义"(尽管你可能早已习惯了名义);你脑子里那套"应该怎样"的直觉,往往来自你熟悉的别的工具,而新工具,会按它自己的规则运行,不会迁就你的直觉;用一个错误的"心智模型"去用一个工具,就会对它的行为,产生错误的预期。而这,是一个极其普遍的坑——"用 A 的直觉,去用 B":从 Java 来的人,以为 TS 类型按名字区分(其实按结构);从同步来的人,以为 async 加上就并发(其实要 await 让出);从一种语言的变量来的人,以为另一种也是同样的值/引用语义(其实不同)——跨工具、跨语言时,最危险的,就是"想当然地迁移旧直觉"。由此,我立下了几条习惯:第一,用一个新工具/语言,要主动去学"它自己的核心规则"(别假设它和你熟的那个一样);第二,行为反直觉时,别怪工具"不对",先问"它的规则到底是什么";第三,尤其对那些"看起来很像、其实规则不同"的东西(如类型系统、相等判断、作用域),要格外警惕。归根结底:工具,按"它自己的规则"工作,而不按你"从别处带来的直觉";用一个新工具之前,先搞懂它的规则——别用旧的直觉,去想象一个新的世界。我那次,正是用名义类型的旧直觉,误读了结构化类型的新世界。把"迁移旧直觉"和"学它的规则"对比成一张表:

一套"语义不同的类型该怎么定义"的决策流程

把这次踩坑的全部教训,我浓缩成了一张"定义语义不同的类型、怎么防混用"的决策图,贴在了团队的 TS 规范里:

这张图,把我"血泪换来"的整套方法论,串成了一条可执行的路径:定义类型,先问它们语义不同、但结构相同吗——结构本就不同的直接定义即可;结构相同(如 UserId/ProductId 都是 string)的,再看混用后果严不严重:严重的(ID/钱/单位)用 branded type 加幽灵标记强约束,一般的靠清晰命名+测试+评审兜底。而语义不同的对象,加判别字段(kind/type)、用可辨识联合。这条"按是否结构相同、按后果严重程度选约束手段"的决策链,现在是我们团队定义类型时的准则。

我立下的几条 TypeScript 类型规矩

这次"语义混用却不报错"的踩坑,让我把 TS 类型的注意事项,认真地立成了几条规矩:

1. 记牢 TS 是结构化类型。看结构不看名字,结构相同就兼容、可互换,不管业务含义。
2. 语义不同+结构相同要警惕。UserId/ProductId 都是 string、Dog/Cat 同形,TS 会放行混用。
3. 高风险类型用 branded type。ID/钱/单位等,加幽灵标记制造结构差异,让 TS 能区分;零运行时开销。
4. 语义不同的对象加判别字段。用 kind/type 做可辨识联合,结构上就能区分。
5. 一般场景靠工程兜底。清晰命名、单元测试、code review,别处处上 branded type。
6. 享受结构化的灵活。它的鸭子类型、少样板是优点,只在需要严格处补名义约束。
7. 别用旧语言直觉想象 TS。它的规则是结构化,不是 Java/C# 的名义;用新工具先学它自己的规则。

写在最后

这次"我把商品 ID 当用户 ID 传、TS 却一声没吭"的经历,是我在 TypeScript 路上,一次很经典、也很受用的成长。它教给我的,远不止"用 branded type 区分 ID"这一条具体的技术经验,更是一个关于使用工具的根本态度——每个工具,都按"它自己的规则"工作,而不是按"你从别处带来的直觉"。我那次的张冠李戴,根源就在于,我揣着"类型靠名字区分"的名义类型直觉(那来自 Java/C#),去想象一个本质上是"结构化类型"的 TypeScript;我以为我贴的"用户 ID / 商品 ID"的标签会被它认得,可它只看结构,而那两个标签下的结构,一模一样。

所以,当你上手一门新语言、一个新工具时,请别想当然地,把你熟悉的旧工具的规则,套到它身上——而要主动地、专门地,去搞懂它"自己的"核心规则:它的类型系统是结构化还是名义?它的相等怎么判断?它的变量是值还是引用?这些"看起来很像、实则规则不同"的地方,恰恰最容易让你栽跟头。就像 TS,你只要真正理解了"它是结构化类型、只看结构",就会在需要严格区分语义的地方,主动用上 branded type,绝不会再被那种"语义混用却不报错"的诡异给坑到。从"用旧直觉想象新工具"到"学懂它自己的规则",从误读结构化类型到善用它的灵活、并在关键处补上严格,是从一个"会写 TS"的开发,走向一个"懂类型系统、用得精准"的工程师,必经的修炼。愿你用的每一个类型,都既享受了结构化的灵活、又守住了关键语义的边界;也愿你我,每进入一个新世界,都肯放下旧直觉,去读懂它,自己的法则。共勉。

—— 别看了 · 2026