数据字典规范

数据字典的编写与维护

字典结构

【Standard】数据字典以 Markdown 表格形式维护，按业务域分文件，包含库、表、字段三级信息。

1.1 目录结构

docs/
└── data-dictionary/
    ├── README.md              # 总览与索引
    ├── user/                  # 用户域
    │   └── sys_user.md
    ├── order/                 # 订单域
    │   ├── order_order.md
    │   └── order_order_item.md
    └── pay/                   # 支付域
        └── pay_payment.md

1.2 表级字典结构

每个表一个 Markdown 文件，结构如下：

# 表名：order_order
 
> 订单主表，存储订单核心信息
 
| 属性 | 值 |
|------|-----|
| 表名 | order_order |
| 所属库 | order_db |
| 业务域 | 订单 |
| 负责人 | @张三 |
| 创建时间 | 2024-01-01 |
| 最后更新 | 2024-06-01 |
 
## 字段说明
 
| 字段名 | 类型 | 可空 | 默认值 | 说明 | 枚举值 |
|--------|------|------|--------|------|--------|
| id | BIGINT | 否 | - | 主键ID(雪花) | - |
| order_no | VARCHAR(32) | 否 | '' | 订单号 | - |
| user_id | BIGINT | 否 | 0 | 用户ID | - |
| order_status | TINYINT | 否 | 0 | 订单状态 | 0-待支付 1-已支付 2-已发货 3-已完成 4-已取消 |
| total_amount | DECIMAL(18,2) | 否 | 0.00 | 订单总金额(元) | - |
| is_deleted | TINYINT(1) | 否 | 0 | 是否删除 | 0-否 1-是 |
| create_time | DATETIME(3) | 否 | CURRENT_TIMESTAMP | 创建时间 | - |
| update_time | DATETIME(3) | 否 | CURRENT_TIMESTAMP | 更新时间 | - |
 
## 索引
 
| 索引名 | 类型 | 字段 | 说明 |
|--------|------|------|------|
| PRIMARY | 主键 | id | - |
| uk_order_no | 唯一 | order_no | 订单号唯一 |
| idx_user_status | 普通 | user_id, order_status | 用户订单查询 |

1.3 必填属性

表级字典必须包含：表名、所属库、业务域、负责人、创建时间、最后更新时间。

字段说明

【Requirement】每个字段必须包含：字段名、类型、可空、默认值、说明；枚举/状态字段必须列出全部取值。

2.1 字段属性说明

属性	必填	说明
字段名	是	数据库实际字段名
类型	是	完整类型，含长度，如 `VARCHAR(32)`、`DECIMAL(18,2)`
可空	是	是/否
默认值	是	无默认值填 `-`
说明	是	业务含义，1-2 句话
枚举值	条件必填	状态/类型字段必须列出全部取值

2.2 枚举值格式

枚举字段必须穷举所有取值，格式：值-含义，用空格分隔：

0-待支付 1-已支付 2-已发货 3-已完成 4-已取消 5-已退款

2.3 特殊字段标注

字段类型	标注要求
主键	说明中标注 `主键ID` 及生成策略
外键	说明中标注关联表，如 `关联 sys_user.id`
金额	说明中标注单位，如 `订单总金额(元)`
时间	说明中标注时区，统一为 `UTC`
加密字段	说明中标注 `加密存储`，禁止写明文

维护流程

【Requirement】数据字典随数据库变更同步更新，DDL 变更的 PR 必须包含对应字典的修改。

3.1 变更流程

1. 开发提交 DDL 迁移脚本
2. 同步更新对应表的数据字典 Markdown
3. PR Review 时检查字典是否同步
4. CI 校验：DDL 变更必须包含字典文件改动
5. 合并后自动生成最新数据字典文档

3.2 自动生成

【Standard】使用工具从数据库元数据自动生成数据字典，人工补充业务说明。

# 使用 mysql-ddl-docs 生成
mysql-ddl-docs \
  --host localhost --user root --password secret \
  --database order_db \
  --output docs/data-dictionary/
 
# 或使用 schemaspy
java -jar schemaspy.jar -t mysql -db order_db \
  -u root -p secret -host localhost -o docs/data-dictionary/

3.3 责任人

每个业务域指定字典 Owner
Owner 负责本域字典的准确性与及时性
每季度由 DBA 组织一次字典与数据库的一致性校验

版本管理

【Standard】数据字典纳入 Git 管理，与代码同仓库；字典变更随 DDL 脚本同一 PR 提交。

4.1 版本号

数据字典版本跟随数据库 Schema 版本：

V1.0.0  初始版本
V1.0.1  新增 sys_user.phone 字段
V1.1.0  新增 order_order 表

4.2 变更记录

每个表的字典文件末尾维护变更记录：

## 变更记录
 
| 版本 | 日期 | 变更内容 | 操作人 |
|------|------|----------|--------|
| V1.0.0 | 2024-01-01 | 初始创建 | 张三 |
| V1.0.1 | 2024-03-15 | 新增 phone 字段 | 李四 |
| V1.1.0 | 2024-06-01 | 新增 order_status=5 已退款 | 王五 |

4.3 CI 校验

# .gitlab-ci.yml
data-dict-check:
  script:
    - |
      if git diff --name-only HEAD~1 | grep -q "db/migration"; then
        if ! git diff --name-only HEAD~1 | grep -q "docs/data-dictionary"; then
          echo "DDL 变更未同步更新数据字典"
          exit 1
        fi
      fi

示例

以下为完整的 order_order 表数据字典示例：

# 表名：order_order
 
> 订单主表，存储订单的核心信息，是订单域的核心表
 
| 属性 | 值 |
|------|-----|
| 表名 | order_order |
| 所属库 | order_db |
| 业务域 | 订单 |
| 负责人 | @张三 |
| 创建时间 | 2024-01-01 |
| 最后更新 | 2024-06-01 |
| 数据量级 | 约 5000 万 |
 
## 字段说明
 
| 字段名 | 类型 | 可空 | 默认值 | 说明 | 枚举值 |
|--------|------|------|--------|------|--------|
| id | BIGINT | 否 | - | 主键ID，雪花算法生成 | - |
| order_no | VARCHAR(32) | 否 | '' | 订单号，业务唯一标识 | - |
| user_id | BIGINT | 否 | 0 | 用户ID，关联 sys_user.id | - |
| merchant_id | BIGINT | 否 | 0 | 商户ID，关联 mer_merchant.id | - |
| order_status | TINYINT | 否 | 0 | 订单状态 | 0-待支付 1-已支付 2-已发货 3-已完成 4-已取消 5-已退款 |
| pay_type | TINYINT | 否 | 0 | 支付方式 | 0-未支付 1-支付宝 2-微信 3-银行卡 |
| total_amount | DECIMAL(18,2) | 否 | 0.00 | 订单总金额(元) | - |
| pay_amount | DECIMAL(18,2) | 否 | 0.00 | 实付金额(元) | - |
| discount_amount | DECIMAL(18,2) | 否 | 0.00 | 优惠金额(元) | - |
| receiver_name | VARCHAR(64) | 否 | '' | 收货人姓名 | - |
| receiver_phone | VARCHAR(20) | 否 | '' | 收货人手机号 | - |
| receiver_address | VARCHAR(255) | 否 | '' | 收货地址 | - |
| remark | VARCHAR(500) | 否 | '' | 订单备注 | - |
| pay_time | DATETIME(3) | 是 | NULL | 支付时间(UTC) | - |
| ship_time | DATETIME(3) | 是 | NULL | 发货时间(UTC) | - |
| finish_time | DATETIME(3) | 是 | NULL | 完成时间(UTC) | - |
| is_deleted | TINYINT(1) | 否 | 0 | 逻辑删除标记 | 0-否 1-是 |
| create_time | DATETIME(3) | 否 | CURRENT_TIMESTAMP(3) | 创建时间(UTC) | - |
| update_time | DATETIME(3) | 否 | CURRENT_TIMESTAMP(3) ON UPDATE | 更新时间(UTC) | - |
 
## 索引
 
| 索引名 | 类型 | 字段 | 说明 |
|--------|------|------|------|
| PRIMARY | 主键 | id | 主键 |
| uk_order_no | 唯一 | order_no | 订单号唯一 |
| idx_user_status_time | 普通 | user_id, order_status, create_time | 用户订单列表查询 |
| idx_merchant_status | 普通 | merchant_id, order_status | 商户订单查询 |
| idx_create_time | 普通 | create_time | 按时间范围查询 |
 
## 变更记录
 
| 版本 | 日期 | 变更内容 | 操作人 |
|------|------|----------|--------|
| V1.0.0 | 2024-01-01 | 初始创建 | 张三 |
| V1.0.1 | 2024-03-15 | 新增 discount_amount 字段 | 李四 |
| V1.1.0 | 2024-06-01 | order_status 新增 5-已退款 | 王五 |