jq时间戳转换格式化指南

时间戳与日期字符串的区别

时间戳用于表达相对于统一时间基准的偏移量，本身通常不携带易读的年月日信息。日期字符串则是按照指定模板展示的文本，例如由年份、月份、日期、时分秒等字段组成。

在 jq 中，strftime 负责把可识别的时间值格式化为字符串，常见模板写法如下：

```jq.created_at | strftime("%Y-%m-%d %H:%M:%S")```

这段过滤器假设 created_at 已经是 jq 日期函数能够处理的数值。如果字段来自 JSON 字符串，或者来源系统使用了不同精度，直接格式化可能报错，也可能得到偏离预期的日期。因此，转换前需要检查字段类型、数值尺度与时区语义。

转换原理与精度归一

jq 处理时间戳时，可将流程理解为“读取字段、转换数值、调整尺度、套用模板”。不少接口会把时间戳写成字符串，此时可先使用 tonumber：

```jq.created_at | tonumber | strftime("%Y-%m-%d %H:%M:%S")```

如果来源值采用更细的精度，则应先除以来源协议规定的缩放因子。为了避免把某个假设写死在过滤器中，可以从外部传入尺度参数：

```shjq --argjson scale "$SCALE" '.created_at | tonumber / $scale | strftime("%Y-%m-%d %H:%M:%S")'```

这里的 $SCALE 应依据接口文档、数据库字段定义或生产端代码确定。若无法确认，可先使用时间戳转换与日期核对工具对照少量已知日期，判断原始值的精度和解释方式。不要仅凭数值长度猜测，因为负值、小数以及不同系统的编码规则都可能影响判断。

常用 jq 写法与处理方法

处理单个对象时，可以通过更新赋值保留其余字段，只替换目标时间字段：

```jq.created_at |= (tonumber / $scale | strftime("%Y-%m-%d %H:%M:%S"))```

面对对象列表，可结合 map 对每个元素执行相同规则：

```jqmap(.created_at |= (tonumber / $scale | strftime("%Y-%m-%d %H:%M:%S")))```

如果输入不是时间戳，而是符合固定模板的日期文本，可先用 strptime 解析，再通过 mktime 转为时间值：

```jq.date_text | strptime("%Y-%m-%dT%H:%M:%SZ") | mktime```

若还需要输出另一种样式，可以继续连接 strftime。这种管道式写法便于把解析、转换和展示职责拆开，也更容易定位错误。建议将字段路径、缩放参数和格式模板分别管理，避免在复杂表达式中混合过多业务判断。

时区、空值与兼容性注意事项

日期正确不只取决于时间戳，还取决于时区。jq 的日期函数通常以协调世界时语义处理数据；如果业务要求本地时区，应明确转换发生在 jq、运行环境还是后续应用中。直接为时间戳加上固定偏移并不稳妥，因为地区规则和夏令时可能造成差异。

字段可能为空、缺失或包含不可转换的文本。可以先判断空值，再使用 try 防止异常终止处理：

```jqif .created_at == null then.else.created_at |= (try (tonumber / $scale | strftime("%Y-%m-%d %H:%M:%S")) catch null)end```

将异常结果改成 null 只是其中一种策略，也可以保留原值或输出带状态的对象。选择哪种方式取决于下游是否需要追踪脏数据。此外，不同系统中的 jq 版本及底层日期库可能存在兼容差异，上线前应使用包含空值、边界日期、负时间戳和小数值的样本进行验证。

常见问题