Timestamp Converter 排查 API 日志：秒、毫秒、UTC 和过期边界
用时间戳转换器排查 API 日志时，重点区分秒级、毫秒级、UTC、本地时区和数据库存储格式。本文说明如何从日志时间、接口返回值、前端显示和数据库字段之间定位偏差，并处理跨时区、夏令时和 10 位/13 位混用。适合接口联调、日志回放和线上时间显示问题定位。并给出复核顺序。流程。方法。
API 日志里的时间“不对”，通常不是真的时间坏了，而是单位、时区、格式化层或比较规则混在一起。最典型的症状有三类：页面显示差几个小时、过期时间提前或延后、时间戳转换后跑到 1970 年或几十年后的未来。
使用 Timestamp Converter 的目的，不是马上改代码，而是先确认一个原始值到底代表哪个时间点。只有原始值、单位和显示规则都清楚后，才知道问题在生产方、消费方还是 UI 展示层。
第一步：回到原始值
排查时间问题时，不要从后台面板里已经格式化过的时间开始。先找到原始来源：API payload、数据库字段、服务器日志、webhook 请求体、JWT payload 或浏览器事件对象。
如果时间值在 JSON 里，先用 JSON Formatter 把结构展开，再复制具体字段。常见字段包括：
created_at、updated_at；expires_at、expire_time；exp、iat、nbf；scheduled_for、event_time；timestamp、ts、time。
不要复制整段日志里看起来像时间的第一个数字。很多日志同时包含 request id、耗时、端口、用户 ID 和时间戳，字段错了会让后续判断全部偏掉。
秒和毫秒混用会让时间差几十年
Unix timestamp 常见单位是秒，JavaScript Date.now() 返回毫秒。把秒当毫秒会显示到 1970 附近；把毫秒当秒会显示到遥远未来。
可以先用位数做粗判：
| 形态 | 常见含义 | 排查重点 |
|---|---|---|
| 10 位数字 | 秒级 Unix timestamp | 后端、JWT、数据库常见 |
| 13 位数字 | 毫秒级 timestamp | JavaScript、前端事件常见 |
| 16 位或更长 | 微秒/纳秒或其他 ID | 先查字段文档，不要直接截断 |
| 很小的数字 | 持续时间、偏移量、TTL | 可能不是绝对时间点 |
| ISO 字符串 | 已格式化时间 | 看是否带 Z 或时区偏移 |
不要靠“删三个 0 试试”解决生产问题。临时转换可以帮助判断，但代码里应该明确单位来源和转换规则。
UTC 和本地显示都可能是对的
Timestamp 表示的是一个绝对时间点。UTC、服务器本地时间、用户浏览器时间可能显示成不同小时，甚至跨日期，但它们可以同时正确。
排查时建议建立一张对照表：
| 层级 | 值 | 单位/时区 | 谁生成 |
|---|---|---|---|
| API 原始字段 | 例如 1718000000 |
秒/UTC 时间点 | 后端服务 |
| 数据库存储 | 2026-06-10 02:00:00 |
UTC 或数据库时区 | 数据库/ORM |
| 服务端日志 | 本地格式化文本 | 服务器时区 | 日志框架 |
| 浏览器 UI | 用户看到的时间 | 用户本地时区 | 前端代码 |
如果只差 8 小时、5 小时或其他固定时区偏移，先怀疑显示规则，而不是直接修改存储数据。把 UTC 存储改成本地时间，常常会制造更难排查的二次问题。
过期问题通常卡在边界比较
Token、邀请链接、临时下载链接、webhook replay window 最容易在边界时间出问题。timestamp 本身可能正确，错误发生在比较条件。
重点检查：
- 使用
<还是<=； - 当前时间来自服务端还是客户端；
- 秒和毫秒是否在比较前统一；
- 是否把毫秒截断成秒；
- 是否有 clock skew 宽限；
- 过期时间是“到这一秒开始失效”还是“这一秒结束后失效”；
- 日志显示时间和实际比较时间是否同一层。
例如 JWT 的 exp 通常是秒级 NumericDate。如果前端用毫秒和它直接比，或者后端日志把过期时间格式化成本地时区，就可能让人误判 token 提前过期。
示例：webhook 事件时间看起来晚了 8 小时
假设 webhook payload 里有：
{
"event_time": 1781056800,
"type": "payment.succeeded"
}
排查时不要先改 UI。先把 event_time 作为秒级 timestamp 转成 UTC，再看本地时区显示。如果 UTC 是 02:00，本地是 10:00，这只是时区展示差异。接着检查：支付平台文档是否声明该字段为秒级 Unix timestamp，服务器日志是否按本地时区打印，数据库是否又存了一份格式化时间。
如果用户界面应该显示用户本地时间，就在展示层明确格式化；如果报表要求统一 UTC，就不要让浏览器默认本地化。
数字格式异常时再查进制或精度
少数系统会把时间放进十六进制、雪花 ID、数据库内部时间或纳秒字段里。遇到位数特别长、字段名不像时间，或转换结果完全不合理时，先查文档。必要时可以用 进制转换工具 排除十六进制/十进制混淆。
另外，JavaScript 对超大整数有精度限制。如果日志里是纳秒级时间戳，直接当 Number 处理可能已经丢精度。此时应该在代码里使用字符串或 BigInt，而不是继续用普通数字猜。
可执行排查流程
可以按下面顺序走：
- 找到原始 payload 或日志字段，不使用二次格式化值；
- 根据字段名和文档确认它是不是绝对时间点；
- 用位数初判秒、毫秒、微秒或 ISO 字符串；
- 先转换成 UTC，再对比本地显示；
- 列出生产方、存储层、消费方和 UI 的单位/时区；
- 对过期类问题检查比较符、截断、取整和 clock skew；
- 用边界前后各一个值补测试；
- 最后再决定是修显示、修转换还是修业务逻辑。
这套流程能避免把“显示差异”误修成“数据迁移”，也能避免在生产代码里反复加减时区偏移。
FAQ
timestamp 差几个小时是不是错了？
不一定。先比较 UTC 和本地时区显示。如果差值刚好等于时区偏移，通常是展示规则问题。
timestamp 显示到 1970 年怎么办？
优先检查是否把秒级 timestamp 当成毫秒处理。10 位通常是秒，13 位通常是毫秒。
JWT 的 exp 应该怎么查？
先解出 payload 里的原始 exp，按秒级时间戳转换，再和服务端当前时间比较，同时检查是否允许 clock skew。
可以在前端直接加 8 小时修复吗？
通常不建议。应先明确存储和显示规则。硬编码偏移会在用户时区、夏令时和跨地区场景下制造新问题。