结论先行：联调返工里最阴的一类，不是字段名写错、也不是枚举漏值，而是「单位/量纲」没约定——同一个字段，前端理解成元、后端吐的是分；同一个时间戳，这边按毫秒、那边按秒。它比"字段缺失"更危险，因为每个环节都"看起来对"：接口 200、字段非空、类型匹配，只有把两个系统的数字摆到一起做对账时，才炸出 100 倍的差。我 3 年做技术产品，带过 9 人产研小组，复盘 11 个迭代、63 个联调返工单，其中 24 个（38%）根因是单位/量纲约定不一致，平均每个吃掉 2.1 人日，而且越是"看起来都懂了"的字段（金额、时间、开关），越容易栽。
一、现象与背景：四个"都对"的字段，凑一起对不上账
先给规模和数字。我们一条 B 端 SaaS 的计费+订单链路（Java 17 + Spring Boot 3.1 后端，React 18 + TS 5.4 前端，日均 4 万+ 笔交易），2024 年内联调返工 63 单，我逐单归因，24 单栽在"单位/量纲"上，具体五起最典型的：
- 金额分/元错位：后端
amount存的是分（整数 29900 = ¥299.00），前端直接当元渲染，账单页显示 ¥29900。运营当"显示 bug"提单，前端改完又"正常"了——因为测试环境用的是小金额，¥2.99 显示成 ¥299 没人察觉。 - 时间戳秒/毫秒错位：网关返回
ts=1700000000（秒），前端new Date(ts)当毫秒解析，页面直接显示 1970-01-20。反过来的更阴：后端拿前端传的毫秒戳当秒存，日期飞到 2149 年。 - 布尔三态打架：后端
switch=1（int），前端有的页面按true/false判断、有的按1/0，还有一个老页面按字符串"0"判断——同一份数据，三处页面显示三个结果。 - 枚举大小写：后端吐
PENDING_PAY，前端if (status === 'pending_pay')走 default 兜底，状态显示"未知"，不报错、不 500，上线当天客服工单爆掉。 - 精度量纲：单价用
double，0.1 + 0.2算出0.30000000000000004，直接透传到前端，对账脚本按==比对全红。
一句话：字段名约定了，字段的"单位"没约定——而单位恰恰是跨语言、跨系统最容易脑补、脑补还各不相同的东西。
二、根因：为什么"单位"最容易丢——它是隐式约定，没有显式载体
字段名是显式的：写在文档、写在代码、写在契约里，四个环节读到的是同一份事实。但"单位"是隐式的：它不在字段名里（除非你特意加后缀），只能靠每个读者脑内补全。而"脑内补全"这件事，PM、后端、前端、测试四个人补出来的是四份不同的东西。
机制上有三个放大器：
- 各语言/库的默认约定天然不同。同样是"现在的时间"：JS 的
Date.now()是毫秒，Python 的time.time()是秒，Java 的System.currentTimeMillis()是毫秒，而 SQL 的UNIX_TIMESTAMP()是秒。后端用 Java、前端用 JS、数据脚本用 Python——三个默认值里有两个是毫秒、一个是秒，只要没人显式对齐，就必然踩雷。同理，数据库金额习惯存分（整数、避免精度），展示层习惯元（浮点、易读），中间差 100 倍。 - "看起来对"的字段，没人觉得需要写。金额、时间、开关这些字段"大家都懂"，所以 PRD 里往往只写字段名不写单位——而这恰恰是离散度最低、脑补空间最大的一类。枚举和上限这类"不写就报错"的字段，大家反而记得写（这点和我之前写过的 PRD 三件套是一个道理）。
- 失真沿传递路径累积。一个金额字段从 PRD → 后端设计 → 前端渲染 → 对账脚本，每经过一个没写单位的空白，就被填一次默认值。四个环节 × 各自脑补，就是四份想象。等四个数字摆到一起做对账，100 倍的差才现形——而且它不报错，只在"对不上"时暴露，这是最阴的一类。
对比：写清单位的字段，四个环节读到同一份事实；没写单位的字段，四个环节读到四份想象。返工率就是这么来的。
三、具体做法：一张「字段单位契约表」+ 四条硬规则
1. 字段单位契约表模板（直接抄进 PRD / 接口文档）
每个涉及"量"的字段，必须填全五列，单位写进字段名后缀，不要只写在文档里：
| 字段 | 类型 | 单位/量纲 | 示例值 | 非法值处理 |
|---|---|---|---|---|
| amount_cents | int64 | 最小货币单位（分） | 29900 = ¥299.00 | <0 返回 400 + code=INVALID_AMOUNT |
| created_at_ms | int64 | epoch 毫秒（UTC） | 1700000000000 | <10^12 视为秒，直接 400，不静默兼容 |
| paid | boolean | JSON true/false | true | 非布尔返回 400 |
| status | enum | SCREAMING_SNAKE_CASE | PENDING_PAY | 未枚举值返回 400，不走 default 兜底 |
2. 四条硬规则（写死，不许"看情况"）
- 金额永远用最小货币单位的整数（分），字段名带
_cents/_fen后缀；禁用 double 存金额。展示层的"元"由前端负责换算：¥${(cents/100).toFixed(2)}。 - 时间戳统一 epoch 毫秒，字段名带
_ms后缀；需要跨时区展示时，另给一个 ISO8601 带时区字段的字符串（如2023-11-14T08:00:00+08:00），不要用"裸日期串"。存 UTC、展示本地化（这点和时区那篇的结论一致）。 - 布尔只用
true/false，禁止0/1、禁止字符串"0"/"1"。 - 枚举用
SCREAMING_SNAKE_CASE，且前后端都要做白名单校验——遇到未枚举值直接报错，不许 default 兜底静默吞掉。
3. 一段可复现的契约测试断言（把"单位"变成可执行检查）
# test_contract.py —— 把单位/量纲写进断言，而不是只断"非空"
def test_amount_unit_is_cents(resp):
a = resp["amount_cents"]
assert isinstance(a, int), f"金额必须是整数(分)，实际 {type(a)}"
assert a >= 0 and a % 1 == 0, "金额不能是浮点"
# 反例：如果后端误吐了"元"的小数，这条立刻红
assert a != 299.00, "疑似把元当分吐了（浮点金额）"
def test_ts_is_millis(resp):
ts = resp["created_at_ms"]
assert ts >= 10**12, f"疑似秒级时间戳 {ts}，契约要求毫秒"
# 反例：1700000000（秒）会在这里被拦下，而不是等到页面显示 1970
def test_bool_is_json_bool(resp):
assert resp["paid"] in (True, False), f"布尔必须是 true/false，实际 {resp['paid']!r}"
关键：把"单位对不对"写成断言，而不是只写 assert resp is not None。弱断言漏掉的就是这类"值在但单位错"的问题。
四、踩过的坑 / 反直觉之处
- 秒/毫秒是最阴的：两个值都"合法"，
1700000000和1700000000000都是正整数、都非空、都通过类型检查，只有量纲差 1000 倍。而且它"看起来对"——1970 年、2149 年，人眼第一眼不会怀疑时间戳本身。解法：契约测试里加一条ts >= 10**12的量纲下限断言，把"是不是秒"变成可执行检查。 - 金额用 double 是慢性毒药：
0.1+0.2==0.30000000000000004，前端toFixed(2)能掩盖，但对账脚本按==比对全红。金额一律最小单位整数，别让浮点碰钱。 - 布尔的三态地狱：
1、"1"、true、"0"、null五种写法我在一条链路里全见过。老页面按字符串"0"判断，新代码给false，"0" === false是 false、false == "0"又是 true——严格相等和宽松相等在这里给出相反结论。统一 JSON 布尔，禁止数字/字符串表示开关。 - 枚举 default 兜底是最阴的静默故障：
switch(status){...default: 显示"未知"}不报错、不 500、监控全绿，只有用户看到"未知"才暴露。我那条"状态显示未知"的工单就是这么来的。枚举必须白名单校验 + 未枚举值直接 400，把静默兜底改成显式报错。 - 单位写进字段名 ≠ 写进文档：光加
_cents后缀不够，测试同学按"元"造数据照样踩雷。字段名后缀 + 契约表单位列 + 契约测试断言，三层都要有，缺任何一层都会在某个环节被脑补掉。
五、结论与可复用清单
结论：单位/量纲是隐式约定，没有显式载体，只能靠每个环节脑内补全——而四个环节补出的是四份想象。把单位从"脑内默认"提升为"契约字段 + 可执行断言"，这类"看起来都对、凑一起对不上"的返工就能被拦在联调阶段。
可复用清单（直接抄进你的接口文档与测试）：
- 金额 = 最小货币单位整数（分），字段名带
_cents/_fen，禁用 double； - 时间戳 = epoch 毫秒，字段名带
_ms，跨时区另给 ISO8601 带时区字符串；契约测试加ts>=10**12量纲断言； - 布尔 = 只用
true/false，禁止0/1与字符串； - 枚举 =
SCREAMING_SNAKE_CASE+ 白名单校验，未枚举值直接 400，禁止 default 兜底； - 每个"量"字段填五列契约表：字段/类型/单位量纲/示例值/非法值处理；
- 把单位写进契约测试断言，别只断"非空"——弱断言漏的正是"值在但单位错"；
- 记住放大器：各语言默认单位不同（JS 毫秒 / Python 秒）、"看起来都懂"的字段没人写、失真沿路径累积——用"字段名后缀 + 文档 + 断言"三层显式化来对冲。
参考：字段"没写全"（枚举/上限/默认值）导致的 70% 联调返工见沈知远《PRD 里最容易漏的三件事》；序列化层静默丢值见顾亦舟-864《JSON.stringify 的 4 个静默数据丢失路径》；时区与时间字段口径见许知远-920《月末日 DAU 凭空多出 18%》。