事件名和属性都正确,时间却落到几十年前或未来,报表仍然会错。JSON 合法、接收接口返回成功,都不能证明客户端传来的数字是秒还是毫秒。迁移埋点时,应把时间戳单位写入数据契约,在边界转换一次,再验证可接受的时间范围。
本文由 SensorFlow 项目账号发布,AI 辅助起草,下面的纯 Node.js 示例已用合成数据运行。它不连接生产 SDK、接收服务或客户数据,也不宣称任何分析平台自动具有此校验能力。
单位是输入契约,不是“看起来像”
JavaScript Date 的数值时间以 Unix 纪元以来的毫秒表示,但其他生产者可以给秒值。示例输入明确带 s 或 ms,归一化后再构造日期。真实系统也可以在版本化接口中固定单位,不必每条事件重复传单位。
不要按位数自动猜测。历史导入、设备时钟异常、截断和错误精度都可能产生“看起来合理”的数字。也不要默默把字符串转成数字,或把异常时间修正为今天;这会掩盖原始错误。
用合成样本检查两侧边界
将下面代码保存为 timestamp-check.cjs,运行 node timestamp-check.cjs。固定窗口为 2026-01-01T00:00:00Z(含)到 2027-01-01T00:00:00Z(不含),只是可重复的教学样本,不是实际留存或回填策略。
const assert = require('node:assert/strict');
const START = Date.UTC(2026, 0, 1);
const END = Date.UTC(2027, 0, 1);
function normalizeEventTime(value, unit) {
if (unit !== 's' && unit !== 'ms') throw new TypeError('unit must be s or ms');
if (!Number.isSafeInteger(value)) throw new TypeError('time must be a safe integer');
const ms = unit === 's' ? value * 1000 : value;
if (!Number.isSafeInteger(ms)) throw new RangeError('normalized time is unsafe');
if (ms < START || ms >= END) throw new RangeError('outside fixture window');
return ms;
}
assert.equal(normalizeEventTime(START / 1000, 's'), START);
assert.equal(normalizeEventTime(START + 123, 'ms'), START + 123);
assert.equal(normalizeEventTime(END - 1, 'ms'), END - 1);
assert.throws(() => normalizeEventTime(START / 1000, 'ms'), RangeError);
assert.throws(() => normalizeEventTime(START, 's'), RangeError);
assert.throws(() => normalizeEventTime(String(START), 'ms'), TypeError);
assert.throws(() => normalizeEventTime(NaN, 'ms'), TypeError);
assert.throws(() => normalizeEventTime(END, 'ms'), RangeError);
const parsed = JSON.parse(JSON.stringify({
time: NaN }));
assert.equal(parsed.time, null);
assert.throws(() => normalizeEventTime(parsed.time, 'ms'), TypeError);
console.log('PASS: ten synthetic timestamp checks');
示例会通过十条合成断言。Number.isSafeInteger同时用于输入和乘以 1000 后的结果,因为输入安全不代表转换结果一定安全;其行为见 MDN 文档。断言 API 见 Node 官方文档。
最后三项尤其提醒:JSON.stringify会把非有限数值序列化成 null。只检查发送前的内存对象,不检查接收端解析后的载荷,就可能漏掉这种变化。范围校验只是补充保护,不是通用单位识别器;如果错误单位恰好仍落入宽范围,仍要靠生产者的已声明契约识别。
迁移验收需要同时看发生时间和接收时间
客户端离线后补发时,“何时发生”与“何时收到”本就不同。不要用接收时刻覆盖发生时刻,也不要仅凭发生时刻认定设备时钟准确。验收表应保存生产者版本、原值、声明单位、归一化 UTC 时刻、允许的历史回填窗口和拒绝原因。
可以用 toISOString()展示归一化 UTC 时刻,方便人工核对;这只是展示方式,不是设备真实时间的证明。先从每种来源各取一个合成或脱敏样本,核对发送前值、序列化结果、接收端解析值与最终查询时间窗,再扩大到回填和多端场景。
本例的验收结论只限于声明单位、转换、整数安全和固定范围。它不证明事件真的发生、身份正确、投递恰好一次或报表已完整。真实链路还需分别验证接收、落库和指标口径。