团队时间使用规范（K8S + Java 场景）

适用范围：后端 Java 服务、Kubernetes 部署、数据库（MySQL / PostgreSQL），适用于风控 / 金融 / 业务系统

一、背景与问题说明

在云原生（Docker / Kubernetes）环境下：

• 容器默认使用 UTC 时区

• JVM 如果未显式设置 user.timezone，会继承容器时区

• 如果业务、数据库、前端使用的是 本地时间（CST / UTC+8），将导致：

查询时间偏移、数据“查不到但实际存在”、定时任务提前或延后执行

因此，需要在团队层面统一时间处理规范，避免隐性 Bug。

二、统一时间原则（必须遵守）

✅ 原则 1：后端时间语义必须统一

禁止：

• 一部分代码按 UTC

• 一部分代码按 CST

• SQL / Java 中手动 +8 小时

必须：

一个系统内，时间语义只有一种

✅ 原则 2：明确区分三种“时间”

三、推荐方案（本团队采用）

🎯 方案 A：统一使用 Asia/Shanghai（CST）【当前推荐】

适用于：

• 国内系统

• 无多时区展示需求

• 金融 / 风控 / 内部系统

规范说明：

四、Kubernetes / JVM 时区规范（强制）

4.1 Pod 必须显式设置 JVM 时区

在 Deployment / StatefulSet 中：

env:
  - name: JAVA_TOOL_OPTIONS
    value: "-Duser.timezone=Asia/Shanghai"

禁止依赖容器默认时区

4.2 时区校验（部署后必查）

kubectl exec -it pod -- date
kubectl exec -it pod -- java -XshowSettings:properties -version 2>&1 | grep timezone

期望结果：

CST
user.timezone = Asia/Shanghai

五、Java 时间使用规范（编码规范）

❌ 禁止用法（新代码禁止）

new Date()
SimpleDateFormat
Calendar

原因：

• 线程不安全

• 时区隐式

• 易踩坑

✅ 推荐用法（Java 8+）

// 当前时间
LocalDateTime now = LocalDateTime.now();

// 时间戳
Instant instant = Instant.ofEpochMilli(timestamp);

// 带时区时间
ZonedDateTime zdt = instant.atZone(ZoneId.of("Asia/Shanghai"));

时间格式化规范

DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
String timeStr = zdt.format(formatter);

六、前后端交互规范

✅ 强制规范

• 前端 统一传毫秒时间戳

• 禁止传字符串时间（除展示接口）

{
  "startTime": 1706428800000,
  "endTime": 1706432400000
}

七、数据库时间规范

7.1 字段类型规范

7.2 禁止行为

• SQL 中手动 + interval 8 hour

• where 条件中对时间字段做函数包裹（影响索引）

八、常见问题 & 排查清单

Q1：数据库有数据，但查不到？

检查顺序：

1. Pod date

2. JVM user.timezone

3. 前端是否传时间戳

4. DB 字段类型

Q2：为什么测试环境正常，生产不正常？

90% 是 K8S 容器时区不同

九、故障复盘模板（可复用）

原因：K8S 容器默认使用 UTC，JVM 未显式设置时区，导致时间解析与业务时间语义（CST）不一致，查询条件偏移 8 小时。

解决：在 Pod 中显式设置 -Duser.timezone=Asia/Shanghai，统一系统时间语义。

十、后续演进（可选）

未来如涉及多时区业务：

• 后端统一 UTC（Instant）

• DB 存 UTC

• 前端展示时转换时区

本作品采用《CC 协议》，转载必须注明作者和本文链接