统一语言与术语表规范

领域术语共建、机器可读术语表、代码命名映射与 CI 校验

定义与价值

规则：统一语言（Ubiquitous Language）是业务方与研发方在同一限界上下文内共同使用、无歧义的领域词汇集合。它是否成立只有一个判定标准：同一个业务概念在需求、代码、数据库、接口四处是否用同一个词。

[Requirement] 同一限界上下文内，一个业务概念只允许一个名称；禁止同义词并存（如”客户/用户/会员”指同一实体）。

[Requirement] 统一语言必须书面化并纳入版本库，禁止仅停留在口头共识或个别成员记忆中。

[Standard] 统一语言以「术语表」为物理载体，与代码同仓、同版本演进。

[Caution] 本规范定义”业务概念叫什么”，与命名与代码风格（“标识符怎么拼写”）互补且不重叠：前者是词汇决策，后者是格式决策。

为什么它属于需求阶段产物：

维度	说明
诞生时机	需求澄清阶段，与领域专家共同确定，早于架构设计
首要消费者	PRD 编写者、架构师、开发、测试
长期消费者	代码（类名/方法名）、数据库（表/字段）、API（路径/参数）
失守后果	一个概念多个名字 → 沟通歧义、重复建模、AI 生成代码用词漂移

建立流程

规则：统一语言由业务方与研发方共建，研发方主导结构化，业务方主导定义准确性与最终确认。

[Requirement] 每个限界上下文在领域建模启动前，必须完成一轮术语共建，产出该上下文的术语表初稿。

[Standard] 共建流程五步：

步骤	动作	产物
1. 收集	从 PRD、访谈、现有表结构中提取候选词	候选词清单
2. 澄清	与领域专家逐词确认含义，剔除同义词、识别歧义词	词义定义
3. 命名	为每个术语确定唯一中文名 + 英文标识符	术语表初稿
4. 落库	写入术语表文件并提交版本库	术语表 v1
5. 校验	CI 校验代码/DB/API 命名与术语表一致性	校验报告

[Suggestion] 术语共建会议建议业务方与研发方各出 1-2 人，单次不超过 90 分钟，聚焦争议词。

反模式：

❌ 研发方闭门造词，业务方事后不认。
❌ 只建一次就不维护，术语表在版本库里腐烂。
❌ 只在文档里统一，代码里照旧各写各的。

术语表结构

规则：术语表必须是机器可读的结构化文件，便于人工查阅、工具校验与 AI 消费。

[Requirement] 术语表至少包含以下字段：

字段	说明	必填
术语 ID	稳定唯一标识，如 `TERM-ORDER-001`	是
中文术语	业务方使用的中文名	是
英文标识符	代码/DB/API 使用的英文名（如 `Order`）	是
定义	一句话精确定义，含边界	是
限界上下文	该术语归属的上下文	是
禁用同义词	明确不让用的词（如”订单/单子/单据”）	是
示例	正例或反例，用于消歧	否
负责人	词义争议的仲裁人	是

[Standard] 术语表默认以 Markdown 表格维护，规模超 200 条时改用 YAML/CSV 以便工具处理。

示例（YAML 形态）：

- id: TERM-ORDER-001
  zh: 订单
  en: Order
  definition: 用户提交并完成支付的交易凭证；支付前称"购物车"，支付后称"订单"
  context: 交易
  forbidden: [单子, 工单, 单据]
  owner: 张三

示例（Markdown 形态）：

术语 ID	中文术语	英文标识符	定义	限界上下文	禁用同义词
TERM-ORDER-001	订单	Order	已支付的交易凭证	交易	单子、工单
TERM-USER-001	客户	Customer	下单主体，含个人与企业	客户	用户、会员

落地：命名映射与消费方

规则：术语表只有在被”引用”和”校验”时才有价值。

[Requirement] 代码标识符、数据库表/字段名、API 路径与参数名，必须与术语表的英文标识符一致，或为其规范派生（复数、snake_case 等）。

[Standard] 派生规则示例（以术语 Order 为例）：

层	命名	派生规则
领域类	`Order`	保持原词
方法	`createOrder`	动词 + 术语
数据库表	`t_order`	前缀 + snake_case
数据库字段	`order_id`	snake_case
API 路径	`/orders`	复数小写
API 字段	`orderId`	camelCase

[Standard] 消费方清单：

消费方	引用方式
命名与代码风格	标识符词源取自术语表
数据库表结构设计规范	表/字段名与术语表对齐
REST_API设计规范	资源名与术语表对齐
架构设计规范	限界上下文划分依据术语归属
文档编写规范	术语章节的数据源

作为 AI 上下文的术语源

规则：AI 不会自发遵守未声明的词汇约定，术语表必须显式注入。

[Standard] 在 AI 辅助开发中，术语表须作为上下文注入，确保 AI 生成代码使用一致词汇。

[Standard] 可将术语表导出为精简版（仅中文术语 / 英文标识符 / 定义），随任务分发给 AI。

[Suggestion] 在生成代码前的 Prompt 中声明：请严格遵守以下领域术语表，不得使用同义词或自造词：...

[Caution] 不注入术语表时，AI 倾向于为同一概念生成多个名字（如 User/Member/Customer 混用），导致后续重构成本上升。

维护与演化

规则：统一语言随领域演化，但变更必须受控。

[Requirement] 术语的新增、改名、作废必须经术语负责人确认，并同步更新术语表。

[Requirement] 术语改名必须同步更新所有消费方（代码/DB/API/文档），禁止只改一处。

[Standard] 词义冲突处理：

情况	处理
同一词在不同上下文含义不同	拆到各自限界上下文，各自定义
不同词指同一概念	保留一个，其余列入禁用同义词
术语作废	标记 `deprecated` 并保留映射，不物理删除

[Standard] CI 校验项：

校验	手段
代码标识符与术语表一致	静态扫描 + 白名单
DB 表/字段与术语表一致	迁移脚本校验
新增术语未登记	PR 检查术语表 diff

反模式：

❌ 术语改名只改文档不改代码。
❌ 不同限界上下文共用一个全局术语表却不区分词义。
❌ 直接删除历史术语，丢失溯源信息。

限界上下文边界

规则：统一语言的作用范围是限界上下文，不是全系统。

[Requirement] 跨上下文的同名术语若含义不同，必须分别定义并标注所属上下文。

[Standard] 上下文之间通过 Context Map 描述关系，术语翻译在映射层完成，不污染各上下文的内部术语。

[Suggestion] 上下文数量与团队规模匹配，避免划分过细导致术语维护成本超过收益。

反模式

反模式	问题	正确做法
术语表只建在文档里	代码不遵守，形同虚设	机器可读 + CI 校验
同义词长期并存	沟通与建模歧义	维护禁用同义词清单
术语无负责人	争议无人仲裁	每词指定 owner
术语表与代码脱节	AI 与新人被误导	同仓同版本 + 定期校验
全局单一术语表	跨上下文词义打架	按限界上下文分表