用于数据库关系的 Mermaid ER 图

实体关系图用于表达数据结构和基数。它可以帮助 schema 设计和新人上手，但不能替代可执行的迁移脚本。应把它看作对重要约束的解释，而把数据库定义视为最终事实来源。

建模实体和属性

erDiagram
  CUSTOMER ||--o{ ORDER : places
  ORDER ||--|{ ORDER_ITEM : contains
  PRODUCT ||--o{ ORDER_ITEM : appears_in

  CUSTOMER {
    uuid id PK
    string email UK
    datetime created_at
  }
  ORDER {
    uuid id PK
    uuid customer_id FK
    string status
  }
  ORDER_ITEM {
    uuid order_id FK
    uuid product_id FK
    int quantity
  }
  PRODUCT {
    uuid id PK
    string name
    decimal price
  }

ER 图里的属性类型只是描述性的。可以使用团队习惯的词汇，但不要以为图能强制数据库特定的精度、索引、默认值或检查约束。

从两端读取基数

CUSTOMER ||--o{ ORDER 表示每个订单都属于且只属于一个客户，而一个客户可以有零个或多个订单。把两端都读清楚，才能避免“客户有订单”这种模糊说法掩盖可选性。

关系标签可以用 places 或 contains 这种更自然的动词。标签是文档，不是外键名。

只展示需要的 schema

完整的生产数据库通常还会包含审计列、技术索引、集成字段和连接表，过多细节会把总览淹没。应该先做一张领域级 ER 图，只保留理解关系所需的键和属性；更详细的内容再链接到 migration 或生成的 schema 文档。

如果是 schema 变更的 Pull Request，只有概念模型变化时才更新图。新增一个可空的 telemetry 列，通常不属于总览；新增一个所有权关系，通常就应该更新。

用数据库验证假设

确认可选性、唯一性和关系方向是否真的和约束一致。图里写“必须唯一”但外键实际可空，会造成误导。逆向梳理旧 schema 时，如果某个关系不确定，应该在正文里标注，而不是把猜测写成强约束。

可以在 Mermaid 编辑器 里用 ER 模板验证语法，并导出可缩放的 SVG 作为架构文档。