数据契约的语义层：命名规范、数据类型定义、枚举值管理、字段描述的最佳实践

数据契约写好了，但团队里每个人对同一个字段的理解可能完全不同。我见过一个项目，A 团队把 status 字段定义为「0=正常，1=异常」，B 团队却理解为「0=待处理，1=已完成」。结果联调时数据全乱套了。

这就是语义层要解决的问题。说白了，就是给数据契约里的每个字段「定规矩」——叫什么名字、什么类型、取值范围是什么、到底代表什么意思。今天咱们就把这块掰开揉碎了讲清楚。

命名规范：一眼看懂，不用猜

命名这事，看着简单，坑最多。我接手过一个遗留系统，字段名有 usrNm、user_name、UserName 三种写法，同一个含义。你想想看，这要是写数据契约，下游消费方得疯。

我个人习惯用 snake_case（小写+下划线）。为什么？因为它在 SQL、JSON、Java、Python 里都能直接用，不用转来转去。

# 推荐
order_id
customer_name
created_at

# 不推荐
orderId        # 驼峰，SQL 里要加引号
OrderID        # 大小写混用，容易出错
order-id       # 连字符，JSON 里要转义

命名规范要定几条硬规则：

• 全小写 + 下划线：统一风格，避免大小写敏感问题
• 业务含义优先：user_status 比 flag 好一百倍
• 避免缩写：除非是行业通用缩写（如 id、url），否则写全称
• 层级用点号：比如 address.city、address.zip_code

数据类型定义：精确到字节

数据类型定义不精确，后果很严重。我曾经遇到过一个案例：订单金额字段定义为 decimal，但没指定精度。结果上游存的是 10.99，下游消费时变成了 10.9900000000000001。财务对账对不上，查了三天。

数据契约里，数据类型必须精确到：

• 数值型：指定精度和小数位数，比如 decimal(10,2)
• 字符串：指定最大长度，比如 varchar(100)
• 时间戳：指定时区和格式，比如 timestamp with time zone
• 布尔型：明确 true/false 还是 1/0

字段	错误定义	正确定义
订单金额	decimal	decimal(10,2)
用户姓名	string	varchar(50)
创建时间	datetime	timestamp(3) with time zone
是否激活	int	boolean

枚举值管理：别让数字成为谜语

枚举值是最容易出问题的环节。你想想看，status = 3 是什么意思？没人知道，除非去翻文档。

我建议枚举值管理遵循三条原则：

1. 用字符串，不用数字："pending" 比 1 直观得多
2. 枚举值集中定义：放在契约文件头部，不要散落在各个字段里
3. 版本化管理：新增枚举值要升级契约版本，不能偷偷加

// 好的做法
enum OrderStatus {
  PENDING    = "pending"
  CONFIRMED  = "confirmed"
  SHIPPED    = "shipped"
  DELIVERED  = "delivered"
  CANCELLED  = "cancelled"
}

// 坏的做法
// status: 0=待支付, 1=已支付, 2=已发货, 3=已完成, 4=已取消
// 数字含义全靠脑补

字段描述：写给人看，也写给机器看

字段描述不是摆设。好的描述能减少 80% 的沟通成本。我见过最离谱的字段描述是「备注」——备注什么？谁来备注？什么时候备注？全没说。

字段描述要包含：

• 业务含义：这个字段代表什么
• 取值范围：最小值、最大值、可选值
• 特殊规则：比如「创建时间不可为空」「金额必须大于 0」
• 示例值：给一个典型值，让人一看就懂

# 好的字段描述
字段名: order_amount
类型: decimal(10,2)
描述: 订单总金额，包含商品金额和运费，不含已退款金额
规则: 必须大于 0
示例: 199.99

# 坏的字段描述
字段名: amount
类型: decimal
描述: 金额
示例: 无

知识体系总览

下面这张图把语义层的四个核心要素串起来了。你可以把它当作检查清单——写契约时对着看，缺哪个补哪个。

实战检查清单

每次写数据契约时，拿这个清单过一遍：

• 命名：是否全小写+下划线？是否一眼能看懂？
• 类型：精度是否明确？长度是否合理？
• 枚举：是否用字符串？是否集中定义？版本号更新了吗？
• 描述：是否包含业务含义、取值范围、特殊规则、示例值？