TypeScript领域建模实战：基于斯坦福本体论七步法构建健壮数据模型

1. 项目概述

如果你和我一样，在TypeScript项目里摸爬滚打了几年，肯定遇到过这样的场景：面对一个全新的业务领域，老板让你“设计一下数据模型”，你打开一个空白的types.ts文件，光标闪烁，大脑一片空白。是先定义User还是Product？status字段用枚举还是字符串字面量？一堆布尔标志位isActive、isDeleted、isPremium到底该怎么组织？最后往往是凭直觉和过往经验，堆出一个勉强能跑的接口，然后在后续的迭代中，看着它逐渐膨胀成一个无人敢动的“上帝接口”（God Interface），里面塞满了可选的（?）字段和意义模糊的字符串类型。这背后的根本问题，其实不是我们代码写得不好，而是缺少一套系统化的、可重复的领域建模方法论。我们缺的不是语法，是“图纸”。

今天要聊的这个claude-ontology-skill，就是一张来自斯坦福的、现成的“领域建模图纸”。它不是什么新框架，而是一个将斯坦福知识系统实验室（KSL）沉淀了三十多年的“本体论”（Ontology）工程方法，适配到我们日常TypeScript开发工作流中的技能包。简单说，它把学术界的严谨方法论，变成了AI编码助手（如Claude Code、Cursor）能理解并辅助我们执行的步骤。核心就是那套著名的“本体论开发101”七步法，但它的输出不是晦涩的学术论文，而是你立刻就能用的TypeScript接口、Zod验证模式和SQL建表语句。

这个技能适合所有正在被复杂业务模型折磨的中高级开发者，尤其是那些深感“设计模式会了，但面对业务还是一团乱麻”的朋友。它帮你把模糊的领域知识，通过一系列有章可循的提问和决策，转化为清晰、可扩展、类型安全的数据架构。接下来，我会带你深入这套方法论的每一个步骤，结合真实的电商场景，看看它是如何把“凭感觉”变成“按流程”的。

2. 核心思路：从哲学概念到类型代码

在深入七步法之前，我们得先搞清楚“本体论”到底是什么，以及它凭什么能指导我们写代码。很多人第一次听到这个词，会联想到哲学里“研究存在本身”的形而上学，感觉离编程十万八千里。但在计算机科学，特别是知识工程领域，本体论被定义为“对概念化的显式规范”。这是斯坦福的Thomas Gruber在1993年提出的经典定义。你可以把它理解为一套给某个领域（比如“电商”、“医疗”）建立“词汇表”和“关系说明书”的严格方法。这套“说明书”要明确：这个领域里有哪些核心概念（类）、这些概念之间是什么关系（继承、组合）、每个概念有哪些属性、这些属性要遵守什么规则。

那么，这套“说明书”怎么变成TypeScript代码呢？claude-ontology-skill的核心价值就在于建立了一套清晰的映射关系。当我们说“类”（Class），对应到代码里就是一个interface或type定义。当说“子类”（Subclass）关系，对应的是TypeScript的联合类型（Discriminated Union）或继承（extends）。一个“属性”（Property）就是接口里的一个字段。而“约束”（Facet）则通过Zod Schema或TypeScript的字面量类型、泛型来实现。这个映射不是随意的，它确保了我们在思维层面进行的领域分析，能够无损地、一一对应地转化为类型系统的约束，从而在编译时就能捕获大量潜在的错误，而不是等到运行时才暴露问题。

这套方法之所以有效，是因为它强迫我们在写第一行代码之前，先回答一系列“能力问题”（Competency Questions）。比如，设计一个电商系统，我们不是直接想“我需要一个Product接口”，而是先问：“用户如何找到产品？”（这暗示了分类和搜索属性）“一个产品可以有不同颜色和尺寸吗？”（这指向了变体模型）“价格会变动吗？”（这指向了价格历史记录）。这些问题把模糊的需求转化为了具体的数据结构要求，从源头上避免了设计遗漏。

3. 七步建模法深度拆解与实操要点

3.1 第一步：确定领域与范围（从问题到验收标准）

这一步是整个建模的基石，目标是划定边界并明确成功标准。具体产出物是一份“能力问题”清单，这份清单后续会直接成为我们编写测试用例的验收标准（Acceptance Criteria）。

实操要点：

• 如何提问：问题必须是具体的、可验证的。避免“系统要好用”这种模糊表述。应该问：“作为一个买家，我如何根据商品属性（颜色、尺寸）筛选SKU？”、“后台管理员如何查看一个商品的上架和下架历史？”
• 谁参与：理想情况下，应该和产品经理、业务专家一起进行。如果只有开发者，那就把自己代入典型用户角色（买家、卖家、运营）进行提问。
• 记录形式：直接用代码注释或Markdown记录在项目文档中。例如，在domain/questions.md里写下：

  ## 电商产品目录领域 - 能力问题 1. Q: 一个产品可以属于多个分类吗？ A: 是，一个产品可关联多个分类标签。 -> 暗示：`Product`应有`categoryIds: CategoryId[]`字段。 2. Q: 产品下架后，已生成的订单如何处理？ A: 订单信息保持不变，但前端不再展示该产品。 -> 暗示：`Product`需要`status: 'draft' | 'published' | 'archived'`状态，且`OrderItem`应存储产品快照。

• 常见陷阱：问题过于庞大或技术化。例如，“系统如何保证高并发？”这不是领域建模问题，是架构问题。保持问题聚焦在数据、状态和关系上。

3.2 第二步：考虑复用现有本体（站在巨人肩上）

不要重新发明轮子。在定义自己的术语前，先看看行业内外有没有现成的标准或优秀的开源类型定义可以复用或参考。

实操要点：

• 搜索什么：
  • npm包：搜索@types/相关的领域包，例如@types/express对于Web服务器，或schema.org的TypeScript定义。
  • 行业标准：JSON Schema、OpenAPI规范、微服务社区的共享契约（如Protobuf定义）。
  • 公司内部：其他项目组是否已经定义了类似的User或Product接口？是否有统一的ID类型定义？
• 如何评估：复用不代表照搬。评估现有模型是否满足你的“能力问题”。不满足的部分是扩展还是另起炉灶？扩展时要注意遵循其设计哲学，避免破坏性修改。
• 实例：在设计电商Money类型时，不要自己简单定义为number。应该参考dinero.js或@shopify/money这样的库，它们处理了货币单位、小数点精度和运算舍入等复杂问题。直接复用或借鉴其接口设计，能避免未来巨大的重构成本。

3.3 第三步：枚举重要术语（名词、形容词、动词）

这一步是把领域语言翻译成代码词汇的关键。召集一次头脑风暴，列出领域中的所有重要术语。

实操要点：

• 分类整理：
  • 名词 -> 类/实体：Product（产品）、Category（分类）、Order（订单）、Inventory（库存）。这些将成为你的核心interface或type。
  • 形容词 -> 属性：available（可用的）、discounted（打折的）、virtual（虚拟的）。这些将成为类的属性字段，如isAvailable: boolean。
  • 动词 -> 方法/关系：belongs_to（属于）、has_many（拥有多个）、calculates（计算）。动词通常转化为类之间的关系（外键）或类的方法。例如，Productbelongs_toCategory意味着Product接口里有categoryId: CategoryId。
• 工具辅助：可以使用Miro、Excalidraw等白板工具，或者简单的表格来整理。目标是在进入具体设计前，先有一份完整的词汇表。
• 避坑指南：警惕同义词和歧义词。比如“用户”在系统中可能指“买家”（Customer）和“管理员”（Admin），它们属性差异很大，应该被枚举为两个不同的术语，并在后续步骤中决定是做成一个类的不同状态，还是两个独立的类。

3.4 第四步：定义类与继承体系（构建类型骨架）

这是将术语转化为类型结构的一步。决定哪些名词是类，它们之间如何组织（是继承关系，还是组合关系）。

实操要点：

• 继承（extends） vs 联合类型（Union Types）：这是最容易出错的地方。一个简单的决策树是：
  • 如果子类型完全拥有父类型的所有属性，并且是一种“是一个（is-a）”的关系，且关系稳定，考虑extends。例如，AdminUser extends User，因为管理员首先是一个用户，拥有用户的所有基础属性。
  • 如果子类型只是父类型在特定场景下的形态，且形态可能动态变化或互斥，使用可辨识联合。例如，CatalogItem可以是SimpleProduct或ProductBundle。它们虽然都叫“商品”，但属性结构差异很大，且一个商品在生命周期内不会从一种形态变成另一种。

  // 使用可辨识联合（Discriminated Union）处理互斥的类型变体 type CatalogItem = | { kind: 'simple'; price: Money; sku: string } | { kind: 'bundle'; componentSkus: string[]; bundlePrice: Money };

• 避免过深的继承链：继承层次过深会降低代码的清晰度和灵活性。优先考虑组合（Composition over Inheritance）。例如，与其让DigitalProduct和PhysicalProduct都继承Product并添加各自字段，不如在Product里有一个productType字段，以及一个可选的shippingInfo对象，该对象仅对物理产品存在。
• 画出草图：在定义代码前，用图形工具或纸笔画一个简单的类图。理清has-a（拥有）和is-a（是）的关系，这对后续定义属性至关重要。

3.5 第五步：定义属性（内在 vs 外在）

为每个类添加具体的字段。这里需要区分“内在属性”和“外在属性”。

实操要点：

• 内在属性：描述实体本质特征的属性，即使脱离与其他实体的关系也存在。例如，Product的name、description、basePrice。
• 外在属性（关系）：描述实体与其他实体关联的属性。这通常通过ID引用来实现。例如，Product的categoryId（关联到Category表），OrderItem的productId（关联到Product表）。

  // 使用品牌类型（Branded Type）强化ID语义，避免原始string的混淆 type ProductId = string & { readonly __brand: 'ProductId' }; type CategoryId = string & { readonly __brand: 'CategoryId' }; interface Product { id: ProductId; name: string; categoryId: CategoryId; // 外在属性：关联到Category }

• 属性命名：保持一致性。例如，所有外键ID后缀都用Id，所有布尔标志用is或has开头，所有日期时间用At结尾（如createdAt,updatedAt）。
• 谨慎使用可选属性（?）：一个满是?的接口是“上帝接口”的温床。每添加一个可选属性，都要问：这个属性是真的在某些情况下不存在，还是它应该属于另一个更专门的子类型或关联对象？

3.6 第六步：定义约束（三层一致性）

这是将设计严谨化的核心步骤。约束要在三个层面保持一致性：编译时（TypeScript）、运行时（Zod）、持久化时（SQL）。

实操要点：

• TypeScript层（编译时）：使用最精确的类型。用字符串字面量联合类型代替string，用number的范围（通过工具类型）或品牌类型来区分不同的数字语义。

  // 糟糕的：类型过于宽泛 type UserRole = string; // 良好的：约束明确 type UserRole = 'admin' | 'editor' | 'viewer'; // 使用工具类型或库来约束数值范围（示例使用`zod`） import { z } from 'zod'; const PercentageSchema = z.number().min(0).max(100); type Percentage = z.infer<typeof PercentageSchema>;

• Zod层（运行时验证）：TypeScript在编译后类型信息会擦除，Zod用于在运行时（如API请求、数据入库前）验证数据符合形状和约束。它应与TS类型同步。

  import { z } from 'zod'; // 从Zod Schema推断TypeScript类型，保证两者一致 const ProductSchema = z.object({ id: z.string().uuid(), name: z.string().min(1).max(200), price: z.number().positive(), status: z.enum(['draft', 'published', 'archived']), }); type Product = z.infer<typeof ProductSchema>; // 自动获得正确的TS类型

• SQL层（数据完整性）：数据库约束是最后一道防线。DDL语句应反映类型的约束。

  CREATE TABLE products ( id UUID PRIMARY KEY, name VARCHAR(200) NOT NULL, -- 对应 Zod 的 .min(1).max(200) price DECIMAL(10, 2) CHECK (price > 0), -- 对应 Zod 的 .positive() status TEXT NOT NULL CHECK (status IN ('draft', 'published', 'archived')) -- 对应枚举 );

• 同步策略：理想情况下，应该有一个单一的事实来源。可以使用zod的z.infer从Schema生成TS类型，或者使用drizzle-kit、prisma这类ORM工具，从数据模型定义同时生成TS类型和数据库迁移文件。

3.7 第七步：创建实例（验证模型）

用真实或模拟的数据实例来测试你的模型。这能帮你发现设计中的矛盾或不切实际之处。

实操要点：

• 创建种子数据：编写一个包含各种边界情况的数组或对象。

  const testProducts: Product[] = [ { id: 'prod_1' as ProductId, name: 'T-Shirt', price: 19.99, status: 'published' }, { id: 'prod_2' as ProductId, name: 'Mug', price: 9.99, status: 'draft' }, // 测试边界：空字符串名？负价格？无效状态？ // { id: 'prod_3', name: '', price: -5, status: 'invalid' } // 这行应该导致类型错误或Zod验证失败 ];

• 编写验证脚本：用Zod Schema去解析这些实例，确保它们能通过验证。同时，尝试用这些数据模拟一些业务操作，比如“计算订单总价”、“过滤已发布商品”，看看你的类型是否支持得顺畅。
• 发现设计缺陷：在创建实例时，你可能会发现某些字段组合起来很奇怪，或者缺少某个必要字段来支持业务操作。这时就回到前面的步骤进行迭代调整。

4. 实战：从零设计一个博客文章领域模型

让我们抛开电商，用一个更常见的例子——博客系统，来完整走一遍七步法。假设我们要为个人博客站点的“文章”核心域建模。

4.1 第一步：确定领域与范围

能力问题清单：

1. 内容状态：一篇文章有哪些生命周期状态？（草稿、已发布、已归档？）
2. 内容组织：文章如何被分类或打标签？一篇文章可以属于多个分类吗？
3. 元信息：文章除了标题正文，还需要哪些元数据？（作者、发布时间、更新时间、封面图、摘要？）
4. 内容格式：文章正文是纯文本、Markdown还是富文本HTML？是否需要支持版本历史？
5. 访问控制：文章可以有私有的吗？还是全部公开？
6. 关联内容：文章之间可以相互引用或关联吗？（比如“相关文章”）

4.2 第二步：考虑复用现有本体

搜索@types/下的博客相关包可能不多，但可以参考成熟开源博客系统（如Ghost、WordPress）的数据库Schema或API设计。更重要的是，可以复用一些通用概念，比如Timestamps（创建/更新时间）、Author、Slug（用于生成URL的字符串）等。

4.3 第三步：枚举重要术语

• 名词/类：Article（文章）、Category（分类）、Tag（标签）、Author（作者）、Comment（评论，暂不深入）。
• 形容词/属性：published（已发布）、featured（精选）、pinned（置顶）。
• 动词/关系：belongs_to（属于，文章属于分类）、has_many（拥有多个，文章有多个标签）、authored_by（由...创作）。

4.4 第四步：定义类与继承体系

在这个简单模型中，继承关系不复杂。Article是核心类。Category和Tag是独立的分类体系。一个关键决策：Article的状态是用一个status字段，还是用不同的类型（如DraftArticle,PublishedArticle）？

考虑到文章状态（草稿、发布、归档）是文章的一个属性，且文章可以在这些状态间转换，使用一个status字段比用联合类型更合适。但如果草稿和已发布文章的结构差异极大（例如，草稿有额外的修订备注字段），则联合类型更好。这里我们假设差异不大，使用字段。

// 使用品牌类型强化语义 type ArticleId = string & { readonly __brand: 'ArticleId' }; type CategoryId = string & { readonly __brand: 'CategoryId' }; type TagId = string & { readonly __brand: 'TagId' }; type AuthorId = string & { readonly __brand: 'AuthorId' }; type Slug = string & { readonly __brand: 'Slug' }; // 核心文章接口 interface Article { id: ArticleId; slug: Slug; // 用于生成URL title: string; // 内容格式：我们决定支持Markdown作为源格式，渲染后的HTML可缓存 contentMarkdown: string; contentHtml?: string; // 可选，可缓存渲染结果 excerpt?: string; // 摘要 coverImageUrl?: string; // 封面图 // 元信息 authorId: AuthorId; status: 'draft' | 'published' | 'archived'; isFeatured: boolean; isPinned: boolean; // 时间戳 createdAt: Date; updatedAt: Date; publishedAt?: Date; // 仅当status为'published'时有值 // 外在属性/关系 categoryIds: CategoryId[]; tagIds: TagId[]; } // 分类和标签接口相对简单 interface Category { id: CategoryId; name: string; slug: Slug; description?: string; } interface Tag { id: TagId; name: string; slug: Slug; }

4.5 第五步与第六步：定义属性与约束（结合Zod）

现在我们用Zod Schema来定义运行时约束，并从中导出TypeScript类型。

import { z } from 'zod'; // 先定义一些基础Schema const NonEmptyStringSchema = z.string().min(1); const SlugSchema = z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/); // 简单的slug正则 // 品牌类型辅助函数（运行时无法真正创建品牌类型，但可辅助验证） const createBrandedSchema = <T extends string>(schema: z.ZodSchema<string>, brand: T) => schema.transform((val) => val as string & { __brand: T }); const ArticleIdSchema = createBrandedSchema(z.string().uuid(), 'ArticleId'); const SlugSchemaBranded = createBrandedSchema(SlugSchema, 'Slug'); // Article Zod Schema const ArticleSchema = z.object({ id: ArticleIdSchema, slug: SlugSchemaBranded, title: NonEmptyStringSchema.max(200), contentMarkdown: NonEmptyStringSchema, contentHtml: z.string().optional(), excerpt: z.string().max(500).optional(), coverImageUrl: z.string().url().optional(), authorId: z.string().uuid(), // 简单处理，实际也应是品牌类型 status: z.enum(['draft', 'published', 'archived']), isFeatured: z.boolean(), isPinned: z.boolean(), createdAt: z.date().or(z.string().datetime()).pipe(z.coerce.date()), // 支持Date对象或ISO字符串 updatedAt: z.date().or(z.string().datetime()).pipe(z.coerce.date()), publishedAt: z.date().or(z.string().datetime()).pipe(z.coerce.date()).optional(), categoryIds: z.array(z.string().uuid()).min(0), // 至少0个 tagIds: z.array(z.string().uuid()).min(0), }); // 从Schema推断TypeScript类型 type Article = z.infer<typeof ArticleSchema>; // 注意：由于品牌类型在运行时是透明转换，z.infer得到的类型可能不包含品牌标记。 // 对于需要强品牌类型的场景，可能需要手动声明接口，并确保数据通过Schema解析后赋值。 // 手动声明一个更精确的接口，与Schema意图保持一致 interface Article { id: ArticleId; slug: Slug; title: string; // ... 其他字段 } // 使用 `ArticleSchema.parse(data)` 验证数据，然后将结果断言为 `Article` 接口。

4.6 第七步：创建实例与验证

// 创建测试实例 const validArticleInput = { id: '123e4567-e89b-12d3-a456-426614174000', slug: 'my-first-article', title: 'Getting Started with Ontology', contentMarkdown: '# Hello World\nThis is **markdown**.', authorId: 'author-1-uuid', status: 'draft' as const, isFeatured: false, isPinned: false, createdAt: new Date().toISOString(), updatedAt: new Date().toISOString(), categoryIds: ['cat-1-uuid'], tagIds: ['tag-1-uuid', 'tag-2-uuid'], }; try { const parsedArticle: Article = ArticleSchema.parse(validArticleInput) as Article; console.log('Article validated successfully:', parsedArticle); // 测试无效数据 const invalidArticleInput = { ...validArticleInput, title: '' }; // 空标题 ArticleSchema.parse(invalidArticleInput); // 这里会抛出ZodError } catch (error) { console.error('Validation failed:', error.errors); }

通过这个流程，我们得到了一个结构清晰、约束明确的Article模型。它回答了第一步的所有能力问题，并且在TypeScript、Zod和未来的SQL层（你可以根据这些约束编写CHECK语句）保持了一致性。

5. 常见问题与排查技巧实录

在实际应用这套方法论时，你肯定会遇到一些困惑和挑战。下面是我在多个项目中实践后总结的一些常见问题和解决思路。

5.1 问题：领域边界模糊，不知道从哪里开始第一步

症状：面对一个庞大的系统，感觉千头万绪，无法列出清晰的能力问题。排查与解决：

• 缩小范围：不要试图一次性建模整个系统。使用“限界上下文”（Domain-Driven Design的概念）来划分领域。例如，将“用户账户”、“商品目录”、“订单履约”视为不同的子域，分别进行建模。
• 从用例/用户故事出发：不要抽象地思考“产品有什么属性”。而是思考“用户下单”这个具体场景需要哪些数据。用户故事能自然地引导出能力问题，例如：“作为买家，我想查看商品详情” -> 需要哪些商品属性？“作为卖家，我想管理库存” -> 需要哪些库存属性？
• 先粗后细：先进行高阶的术语枚举（第三步），不追求完美。列出所有你能想到的名词、动词，然后再去梳理它们之间的关系，边界会逐渐清晰。

5.2 问题：联合类型（Union）与继承（Extends）选择困难

症状：不确定两个相似的概念应该用{ kind: 'a'; ... } | { kind: 'b'; ... }还是interface B extends A。决策树（重温并细化）：

1. 关系是否稳定？一个Admin永远是一个User，这种“是一个”的关系非常稳定，适合extends。而一个PaymentMethod可能是CreditCard或PayPal，虽然都是支付方式，但它们的属性结构差异大，且未来可能新增Crypto支付，这种“是一种”但形态多变的关系，适合联合类型。
2. 属性重叠度：如果两个概念共享大量核心属性（超过70%），且差异是附加的，考虑extends并在子类添加特有字段。如果重叠属性少，各自有大量独特字段，用联合类型更清晰。
3. 行为多态：如果需要根据不同类型执行不同逻辑，联合类型配合kind判别式在TypeScript中能获得极佳的类型收窄支持，实现类型安全的分支处理。继承则需要依赖instanceof或类方法重写。
4. 实战技巧：当你犹豫时，可以先写成联合类型。因为从联合类型重构到继承通常比反过来更容易。联合类型更灵活，约束更少。

5.3 问题：Zod Schema与TypeScript类型重复，难以维护

症状：定义了一个接口，又写了一个几乎一样的Zod Schema，任何修改都要在两个地方同步，容易出错。解决方案：

• 模式：Schema作为唯一真相源：这是最推荐的方式。只定义Zod Schema，然后使用z.infer<typeof YourSchema>来提取TypeScript类型。这样，约束只在一处定义。

  const UserSchema = z.object({ id: z.string().uuid(), email: z.string().email(), name: z.string().min(1), }); type User = z.infer<typeof UserSchema>; // 自动同步

• 反向生成（不推荐）：如果已有庞大的TypeScript接口代码库，可以考虑使用ts-to-zod或typescript-json-schema等工具从TypeScript类型生成Zod Schema初稿，但后续维护仍需以一方为主。
• 品牌类型处理：z.infer可能无法完美推断出品牌类型。对于UserId这种品牌类型，可以这样处理：

  const UserIdSchema = z.string().uuid().transform((val) => val as UserId); const UserSchema = z.object({ id: UserIdSchema, // ... }); // 此时 z.infer<typeof UserSchema> 的 id 类型会是 `string`，而不是 `UserId`。 // 如果需要强类型，可以手动声明接口，或使用一个辅助类型 type User = z.infer<typeof UserSchema> & { id: UserId }; // 更好的方式是，在从外部数据解析后，进行一个安全的类型断言。 const rawData = { id: '...', ... }; const parsed = UserSchema.parse(rawData); // parsed.id 在运行时是字符串 const user: User = { ...parsed, id: parsed.id as UserId }; // 安全断言

5.4 问题：数据库枚举与TypeScript枚举不同步

症状：在TypeScript中定义了status的联合类型，在数据库中也定义了CHECK约束或枚举类型，但新增一个状态时需要同时修改两处。解决方案：

• 由数据库驱动：如果数据库是核心，可以使用像drizzle-orm或prisma这样的ORM，它们可以从数据库Schema生成TypeScript类型定义。
• 由代码驱动：如果业务逻辑是核心，可以维护一个TypeScript的常量数组作为唯一来源，并用它来生成数据库迁移脚本。

  // 在共享的 constants.ts 或 domain.ts 中 export const PRODUCT_STATUSES = ['draft', 'published', 'archived'] as const; export type ProductStatus = typeof PRODUCT_STATUSES[number]; // 得到 'draft' | 'published' | 'archived' // 在数据库种子脚本或迁移中 const sql = ` CREATE TYPE product_status AS ENUM (${PRODUCT_STATUSES.map(s => `'${s}'`).join(', ')}); CREATE TABLE products ( -- ... status product_status NOT NULL DEFAULT 'draft' ); `;

• 使用迁移工具链：将上述常量数组集成到你的数据库迁移流程中，确保每次修改状态列表都会生成相应的ALTER TYPE ... ADD VALUE迁移。

5.5 问题：模型变得臃肿，又回到了“上帝接口”

症状：即使遵循了流程，随着需求增加，核心接口还是不断被塞入可选字段。应对策略：

• 定期重构：将七步法作为重构的指南。定期使用/ontology analyze（如果使用该技能）或手动审查核心接口。
• 提取值对象：将一组紧密相关的属性提取成一个单独的对象。例如，将street、city、postalCode提取为Address值对象。将price、currency提取为Money值对象。
• 使用组合替代继承：考虑将一些可选特性建模为独立的“特征”接口，然后通过组合的方式附加到主体上。例如，Taggable、Publishable、Timestamped作为可混合的接口。
• 审视能力问题：回顾第一步。新加的字段是否真的服务于最初定义的核心能力？如果不是，它可能属于另一个限界上下文，应该被分离出去。

6. 将方法论融入开发工作流

掌握了七步法和问题排查技巧后，关键在于如何让它成为团队的习惯，而不是一次性的设计活动。

1. 设计评审会的新标准：在评审数据模型或API设计时，不要只说“我觉得这里不好”。引用Gruber的五原则（清晰性、一致性、可扩展性、最小编码偏好、最小本体论承诺）作为讨论框架。提问：“这个string类型足够清晰吗？我们是否承诺了不必要的约束？”

2. 编写领域设计文档：为每个核心领域创建一个DOMAIN.md文件。里面不直接放最终接口代码，而是记录： * 第一步的能力问题。 * 第三步的术语表。 * 第四步的类图草图（可以用Mermaid语法）。 * 重要的设计决策及其理由（比如为什么用联合类型而不是继承）。 * 最后附上生成的TypeScript和Zod代码。 这份文档是新成员理解系统核心设计最快的方式。

3. 与AI结对编程：这正是claude-ontology-skill的用武之地。当你对AI助手（如Claude Code、Cursor）说“为通知系统设计一个数据模型”，它可以引导你走过这七步，提出你没想到的能力问题，并根据模式建议类型结构。它能将方法论从书本知识转化为交互式的设计会话。

4. 建立团队共享的类型库：将通用的值对象（Money、Email、URL）、ID品牌类型、状态枚举等提取到独立的shared-types或domain包中。确保所有微服务或模块都使用同一套核心类型定义，从根源上保证一致性。

这套源自斯坦福的本体论方法，其力量不在于提供了某个具体的“正确”答案，而是提供了一个系统化的思考框架和决策流程。它把领域建模从一门“艺术”变成了更多可遵循“工艺”。最开始应用时会觉得步骤繁琐，但一旦形成肌肉记忆，它就能极大地提升你设计出的系统健壮性、可维护性和团队协作效率。下次当你再面对一个复杂的业务领域时，不妨试着抛开直觉，拿起这七步法作为你的罗盘，一步步将混沌的需求，绘制成清晰可靠的类型疆域。