斯坦福本体论七步法 + Zod：解决 TypeScript 类型失控的领域建模实践

1. 为什么前端项目一到中期就“类型失控”

做 TypeScript 项目的人大概都有过这种体验：项目刚起步时，类型定义干净利落，一个interface User走天下。等到业务跑了半年，User变成了UserInfo、UserDetail、UserResponse、UserVO、UserDTO五六个版本，字段互相嵌套，可选属性满天飞，改一个字段要全局搜索半小时。更糟的是，后端接口悄悄加了个字段，前端编译照样通过，上线后页面白屏才发现数据对不上。

这不是 TypeScript 的问题，是领域建模缺失的问题。TypeScript 的类型系统足够强大，但大多数人只把它当成“给 JavaScript 加注解”的工具，而不是用来表达业务语义的建模语言。结果就是类型定义跟着接口文档走，接口一变类型就烂，类型和业务逻辑之间没有稳定的契约。

我最近在一个中型后台项目里系统性地用斯坦福本体论七步法（Stanford Ontology Development 101 的七步流程）重新梳理了领域模型，配合Zod做运行时校验，效果比预期好很多。这篇文章就把这套方法完整拆开讲清楚：七步法每一步在 TypeScript 里到底怎么落地、为什么这么设计、哪些地方容易翻车、Zod 在哪个环节介入最合适。

适合谁看？如果你写过半年以上 TypeScript，被类型维护折磨过，或者正在设计一个新项目的领域层，这篇内容应该能帮你少走不少弯路。不需要你有本体论背景，我会用业务场景把每个概念讲透。

2. 斯坦福本体论七步法到底是什么，为什么适合 TypeScript

2.1 七步法的原始流程与核心思想

斯坦福本体论七步法出自 Noy 和 McGuinness 的那篇经典文档，原本是给知识图谱和语义网领域用的，用来定义某个领域内的概念、属性、关系和约束。七步分别是：

1. 确定本体的领域和范围
2. 考虑复用现有本体
3. 列举领域中的重要术语
4. 定义类和类的层级结构
5. 定义类的属性
6. 定义属性的约束（值域、基数、类型）
7. 创建实例

这套流程的核心思想是：先搞清楚“这个领域里有哪些东西”，再搞清楚“这些东西之间什么关系”，最后才落到具体数据。它强迫你在写代码之前先想清楚业务语义，而不是边写边改。

2.2 为什么它和 TypeScript 天然契合

TypeScript 的类型系统本质上就是一个轻量级的本体描述语言。interface和type定义类，联合类型定义值域，可选属性定义基数，泛型定义参数化关系。你平时写的类型定义，其实就是在做本体建模，只是大多数人做得不系统。

七步法给了一套结构化的思考顺序，正好补上“不系统”这个短板。它让你从业务术语出发，而不是从接口字段出发。这个顺序的差别很关键：从接口出发，类型是后端的镜像；从业务术语出发，类型是你自己领域的资产，后端接口只是它的一种序列化形式。

2.3 和常见“接口对齐”做法的本质区别

大多数团队的做法是：后端出接口文档，前端照着写 interface。这叫数据建模，不叫领域建模。区别在哪？

数据建模关心的是“数据长什么样”，领域建模关心的是“业务里有什么概念、它们怎么协作”。举个例子，电商场景里order.status是个字符串，数据建模就写status: string，领域建模会问：订单状态有哪几种？它们之间能怎么流转？哪些状态是终态？这些问题想清楚了，类型自然就是type OrderStatus = 'pending' | 'paid' | 'shipped' | 'completed' | 'cancelled'，而且你能顺手写出状态机的校验逻辑。

领域建模的产物不只是类型，还有约束和行为边界。这就是为什么它比单纯对齐接口更抗变化。

3. 第一步到第三步：从业务术语到候选类清单

3.1 确定领域范围：别一上来就想建大模型

七步法第一步是确定领域和范围。这一步在 TypeScript 项目里经常被跳过，直接导致后面类型越写越多、边界越来越模糊。我的做法是：先划定一个 bounded context（限界上下文），只建模这一个上下文内的概念。

比如一个 SaaS 后台，不要试图一次性建模“用户、订单、权限、报表、通知”所有东西。先挑一个最核心的上下文，比如“订阅计费”，只在这个范围内列举术语。范围外的概念，哪怕相关，也先标记为“外部引用”，用最小接口占位。

这一步的产出是一句话：“本模型描述的是 XX 上下文内的 YY 业务，不包含 ZZ。”写下来贴在文件顶部注释里，后面每次想加类型都对照一下，能挡掉大量“顺手加一个”的冲动。

3.2 复用现有本体：TypeScript 生态里能复用什么

第二步是考虑复用。TypeScript 世界里可复用的“本体”主要有几类：

• 标准库类型：Date、Map、Set、Promise这些不用自己造
• 社区类型包：比如@types/node、各种 SDK 自带的类型
• 项目内已有的领域类型：跨上下文共享的值对象，比如Money、UserId
• Zod schema：如果你用 Zod，schema 本身就是可复用的本体描述

复用的判断标准很简单：这个概念在你的领域里有特殊语义吗？没有就直接用现成的。比如金额，如果你只是展示，用number够了；但如果你要做多币种计算、精度处理，那就得自己定义Money值对象，因为number表达不了“币种 + 金额”这个业务概念。

3.3 列举术语：怎么从需求文档里挖出真正的领域概念

第三步是列举重要术语。这一步最容易被做成“把名词抄一遍”，那样没意义。我的经验是分三层挖：

第一层：业务方嘴里反复出现的词。产品经理说“用户订阅了套餐，套餐有周期，周期到了要续费”，这里的术语是“订阅”“套餐”“周期”“续费”。这些是核心概念。

第二层：状态和动作。“订阅”有哪些状态？“续费”是个动作还是状态？动作往往对应方法，状态对应联合类型。

第三层：约束和规则。“一个用户同一时间只能有一个生效订阅”——这是基数约束，直接对应类型设计。

挖完之后做一次去重和归类，把同义词合并（“套餐”和“计划”是不是一回事？），把歧义词拆开（“账户”有时候指登录账号，有时候指计费账户，必须拆成两个概念）。这一步的产出是一张术语表，每个术语配一句话定义。

提示：术语表不要写在代码注释里就完事，单独建一个domain-glossary.md，团队一起维护。类型定义和术语表对不上的时候，以术语表为准。

4. 第四步到第六步：把术语翻译成 TypeScript 类型系统

4.1 定义类与层级：interface 还是 type，继承还是组合

第四步定义类和层级。TypeScript 里表达“类”有两种方式：interface和type。我的选择标准是：

• 需要被 implements、需要声明合并、需要表达对象形状：用interface
• 需要联合类型、交叉类型、映射类型、条件类型：用type

领域模型里，实体（有唯一标识、有生命周期）通常用interface，值对象（不可变、靠值相等）通常用type加readonly。

层级关系要特别小心。很多人喜欢用继承表达“is-a”，比如AdminUser extends User。但在领域建模里，继承往往是个陷阱，因为业务上的“是一种”经常是角色而不是类型。管理员和普通用户可能共享 90% 的字段，但他们的行为完全不同。这时候用组合更好：User有一个roles: Role[]属性，而不是AdminUser继承User。

判断标准：如果两个概念的字段高度重合但行为不同，用组合；如果字段和行为都是包含关系，才考虑继承。实践中，领域模型里继承用得越少越好。

4.2 定义属性：字段命名背后的语义一致性

第五步定义属性。这一步的坑不在技术，在命名。同一个概念在不同类型里叫不同名字，是类型失控的重灾区。比如“创建时间”，有的地方叫createdAt，有的叫createTime，有的叫ctime。

我的做法是定一套命名规约，写进项目规范：

命名统一之后，类型之间的关系会清晰很多，重构也好做。

4.3 定义约束：用联合类型、品牌类型和 Zod 表达业务规则

第六步定义约束，这是七步法里最有价值的一步，也是 TypeScript 类型系统真正发挥威力的地方。约束分几类：

值域约束用联合类型：type Plan = 'free' | 'pro' | 'enterprise'。

格式约束用品牌类型（branded type）：

type UserId = string & { readonly __brand: 'UserId' }; type OrderId = string & { readonly __brand: 'OrderId' }; function getUser(id: UserId) { /* ... */ }

这样getUser(orderId)直接编译报错，避免把订单 ID 当用户 ID 传。品牌类型是零运行时开销的，纯编译期约束。

基数约束用可选属性和数组：primaryEmail: string表示必有一个，secondaryEmails: string[]表示零到多个。

跨字段约束用 Zod 的refine：

import { z } from 'zod'; const SubscriptionSchema = z.object({ plan: z.enum(['free', 'pro', 'enterprise']), startedAt: z.date(), expiresAt: z.date(), }).refine( (data) => data.expiresAt > data.startedAt, { message: '过期时间必须晚于开始时间' } );

TypeScript 类型管编译期，Zod 管运行时，两者配合才能覆盖完整。类型定义用z.infer从 schema 推导，保证单一数据源：

type Subscription = z.infer<typeof SubscriptionSchema>;

这样 schema 改了，类型自动跟着变，不会出现类型和校验逻辑不一致的情况。

5. 第七步：实例化与 Zod 运行时校验的衔接

5.1 类型只在编译期存在，运行时靠什么兜底

第七步创建实例。在纯 TypeScript 里，这一步就是const sub: Subscription = {...}。但问题来了：从后端拿到的 JSON 是unknown，直接断言成Subscription是自欺欺人。编译期类型在运行时全部擦除，接口返回个null你照样崩。

这就是 Zod 的用武之地。Zod 让你把类型定义变成可执行的校验逻辑，运行时真正检查数据。流程是：

1. 用 Zod 定义 schema（对应第四到六步的类、属性、约束）
2. 用z.infer推导 TypeScript 类型
3. 接口数据先用schema.parse()校验，通过后再当领域对象用

const raw = await fetch('/api/subscription').then(r => r.json()); const subscription = SubscriptionSchema.parse(raw); // 到这里 subscription 才是真正的 Subscription 类型

5.2 用 z.infer 反向生成类型，保证单一数据源

很多人先写 interface 再写 Zod schema，两边手动同步，迟早对不上。正确做法是只写 schema，类型从 schema 推导：

const UserSchema = z.object({ id: z.string().brand<'UserId'>(), email: z.string().email(), name: z.string().min(1), createdAt: z.coerce.date(), }); type User = z.infer<typeof UserSchema>;

z.infer会自动处理可选、联合、品牌等所有细节，推导出的类型和 schema 永远一致。这是我在项目里最推荐的一条实践，能省掉大量“类型和校验不同步”的 bug。

5.3 解析失败的处理：错误信息如何映射到业务提示

parse()失败会抛ZodError，直接抛给用户看是灾难。我的做法是封装一层：

function parseOrThrow<T>(schema: z.ZodSchema<T>, data: unknown): T { const result = schema.safeParse(data); if (!result.success) { const issues = result.error.issues.map(i => ({ path: i.path.join('.'), message: i.message, })); throw new DomainValidationError(issues); } return result.data; }

DomainValidationError是自定义错误类，携带结构化的错误信息，上层可以决定是展示给用户还是记日志。这样校验失败不再是“一个看不懂的报错”，而是可处理的业务事件。

6. 实战踩坑：品牌类型、Zod 与类型推导的配合细节

6.1 品牌类型在 Zod 里的正确写法

品牌类型和 Zod 配合有个坑：z.string().brand<'UserId'>()推导出的类型是string & z.BRAND<'UserId'>，和手写的string & { readonly __brand: 'UserId' }不完全一样。如果你混用两种写法，类型会不兼容。

我的建议是统一用 Zod 的 brand，手写品牌类型只在没有 Zod 的场景用。如果必须互操作，用类型断言桥接，但尽量别这么干。

另一个坑是品牌类型在序列化时会丢失。JSON.stringify之后品牌信息没了，反序列化要重新走 schema 校验才能恢复。所以品牌类型只适合在领域层内部流转，跨层传输时用原始类型。

6.2 循环引用与递归 schema 的处理

领域模型里经常有递归结构，比如“分类有子分类”。Zod 处理递归要用z.lazy：

type Category = { id: string; name: string; children: Category[]; }; const CategorySchema: z.ZodType<Category> = z.lazy(() => z.object({ id: z.string(), name: z.string(), children: z.array(CategorySchema), }) );

注意这里必须显式标注z.ZodType<Category>，否则 TypeScript 会报“隐式 any”或者推导出无限递归类型。这是 Zod 递归场景的标准写法，记住就行。

6.3 类型推导的性能陷阱：什么时候该手写类型

z.infer很方便，但不是所有场景都适合。当 schema 特别大、嵌套特别深的时候，z.infer的推导会拖慢编辑器响应，甚至触发 TypeScript 的“类型实例化过深”错误。

我的经验阈值是：单个 schema 超过 30 个字段，或者嵌套超过 5 层，就考虑手写类型 + 单独维护 schema。手写类型虽然要同步，但编辑器体验好很多。折中方案是把大 schema 拆成几个小 schema，用.merge()或.extend()组合，推导压力会小很多。

另外，z.infer推导出的类型在 IDE 里 hover 时经常显示成一坨，可读性差。如果团队里有人抱怨“看不懂类型”，可以在关键类型上手写一份带注释的 interface，用satisfies做一致性检查：

const _check: User = {} as z.infer<typeof UserSchema>;

这样既保留了 schema 的单一数据源，又有了可读的类型定义。

7. 从模型到代码：目录组织与团队协作建议

7.1 领域模型的目录结构

领域模型不要和组件、工具函数混在一起。我的目录结构是这样的：

src/ domain/ subscription/ schema.ts // Zod schema，单一数据源 types.ts // 从 schema 推导的类型，或手写类型 rules.ts // 业务规则、状态机、跨字段约束 glossary.md // 术语表 index.ts // 对外导出 shared/ money.ts // 跨上下文的值对象 ids.ts // 品牌类型定义

每个限界上下文一个目录，上下文之间通过shared里的值对象通信，不直接互相 import 内部类型。这样边界清晰，重构影响面可控。

7.2 类型变更的评审流程

领域类型的变更比普通代码变更影响大，应该走单独的评审。我的做法是：

• 类型文件（schema.ts、types.ts）的改动必须至少一人 review
• 删除或重命名字段必须在 PR 描述里说明影响范围
• 新增可选字段要问一句“为什么不是必填”，避免可选属性泛滥
• 品牌类型的改动要检查所有使用点

这套流程听起来重，但比上线后才发现类型不兼容要轻得多。

7.3 和前端框架类型工具的兼容问题

最近社区里有个高频问题：某些前端框架的类型工具和 TypeScript 新版本不兼容，比如baseUrl选项被标记弃用。这类问题的根源是框架的类型工具往往滞后于 TypeScript 官方版本。

我的应对策略是：领域模型层不依赖任何框架的类型工具。domain/目录只用纯 TypeScript 和 Zod，不引入框架特定的类型增强。这样即使框架工具升级滞后，领域层照样能编译。框架相关的类型问题隔离在components/或views/层，升级时影响面小。

另外，tsconfig.json里的baseUrl弃用问题，建议尽早迁移到paths配置，别等到 TypeScript 7.0 真的移除才动手。迁移本身不难，难的是项目里到处是相对路径导入，改起来量大。早改早轻松。

8. 我在实际项目里踩过的几个真实坑

第一个坑是过早抽象。项目初期我兴致勃勃地建了一堆值对象和品牌类型，结果业务还没稳定，类型天天改，维护成本比收益还高。后来学乖了：领域模型跟着业务成熟度走。业务稳定的模块才做完整建模，还在探索的模块先用简单类型，等需求稳定了再重构。

第二个坑是Zod schema 和数据库模型混淆。我一度想用一套 schema 同时管数据库、API 和领域层，结果三边的约束不一样，schema 越写越复杂。正确做法是分层：数据库有自己的 schema，API 有自己的 DTO schema，领域层有自己的领域 schema，层与层之间用映射函数转换。多写几个映射函数，比维护一个万能 schema 简单得多。

第三个坑是品牌类型用过头。我给每个 ID 都加了品牌，结果写测试的时候到处要as UserId，烦不胜烦。后来只在容易混淆的 ID 之间加品牌，比如UserId和OrderId，其他不混的地方不加。品牌类型是防错的，不是用来炫技的。

最后一个坑是术语表没人维护。一开始大家还看看，后来术语表和代码脱节，反而误导人。解决办法是把术语表检查加进 CI：类型定义里的每个核心概念，术语表里必须有对应条目，没有就报错。强制维护虽然烦，但比术语表腐烂强。

这套七步法 + Zod 的组合，我在两个项目里完整跑过，类型相关的线上 bug 明显减少，重构时的信心也足了很多。它不是银弹，但确实把“类型失控”这个慢性病控制住了。如果你也在被类型维护折磨，不妨挑一个模块试试，从术语表开始，一步步来，别贪快。