跳转至

GLOSSARY.md 格式

结构

# {上下文名称}

{一两句话说明这个上下文是什么、为什么存在。}

## 术语

**订单（Order）**：
{一两句话描述这个术语}
_避免_：购买、交易

**发票（Invoice）**：
交货后发给客户的付款请求。
_避免_：账单、付款请求

**客户（Customer）**：
下订单的个人或组织。
_避免_：主顾、买家、账户

规矩

  • 要有主见。 同一个概念有多个叫法时，挑最好的那个，其余列在 _避免_ 下。
  • 定义要紧。 最多一两句。定义它是什么，不是它做什么。
  • 只收本项目上下文特有的术语。 通用编程概念（超时、错误类型、工具函数模式）即使项目里大量使用也不收。加一个术语之前先问：这是本上下文独有的概念，还是通用编程概念？只有前者该收。
  • 自然成簇时用小标题分组。 所有术语都属于同一个内聚的领域，平铺列表就行。

单上下文与多上下文仓库

单上下文（大多数仓库）： 仓库根目录一个 GLOSSARY.md。

多上下文： 仓库根目录放一个 GLOSSARY-MAP.md，列出各个上下文、它们在哪、彼此什么关系：

# 术语表地图

## 上下文

- [Ordering](./src/ordering/GLOSSARY.md)：接收并跟踪客户订单
- [Billing](./src/billing/GLOSSARY.md)：生成发票、处理付款
- [Fulfillment](./src/fulfillment/GLOSSARY.md)：管理仓库拣货和发货

## 关系

- **Ordering → Fulfillment**：Ordering 发出 `OrderPlaced` 事件；Fulfillment 消费它，开始拣货
- **Fulfillment → Billing**：Fulfillment 发出 `ShipmentDispatched` 事件；Billing 消费它，生成发票
- **Ordering ↔ Billing**：共享 `CustomerId` 和 `Money` 类型

按下面推断适用哪种结构：

  • 有 GLOSSARY-MAP.md，读它找到各个上下文
  • 只有根目录一个 GLOSSARY.md，就是单上下文
  • 两个都没有，在第一个术语定下来时，按需在根目录建 GLOSSARY.md

有多个上下文时，推断当前话题属于哪一个。拿不准就问。