时区安全规范

服务端代码里，"当前时间"几乎从不应该裸调。一个 docker 镜像默认 UTC、一个生产机配置 Asia/Shanghai，同一份代码跑出来的"本周起点"就差 8 小时。

配套：query-performance-safety（性能） / multi-tenant-safety（隔离）

---

陷阱 #1: 裸调 .now() 依赖 JVM 默认时区

场景: LocalDate.now() / LocalDateTime.now() / Instant.now() / new Date() 不传时区

问题根因

• LocalDate.now() 在 UTC 服务器上返回的"今天"比业务时区少 1 天（凌晨场景）
• LocalDateTime.now() 拿到的是 JVM 默认时区时间，docker base image 经常默认 UTC
• 同一段代码在开发机（Asia/Shanghai）和生产（UTC）跑出不同结果，无法本地复现
• 数据库时间通常按业务时区入库，比较时一边是业务时区一边是 UTC → 偏差 8h

错误示例

// ❌ 错误：依赖 JVM 默认时区
LocalDateTime weekStart = LocalDate.now()
        .with(DayOfWeek.MONDAY)
        .atStartOfDay();

// ❌ 错误：跨日切换的统计依赖默认时区
LocalDate today = LocalDate.now();
List<Order> todayOrders = orderRepository.findByCreatedAtAfter(today.atStartOfDay());

// ❌ 错误：Date 用默认时区
Date now = new Date();

正确做法

项目级业务时区常量 + 所有 .now() 显式传入：

// ✅ 项目常量类（如 TimeConstants.java）
public final class TimeConstants {
    /** 系统业务时区（中国大陆） */
    public static final ZoneId BIZ_ZONE = ZoneId.of("Asia/Shanghai");
    private TimeConstants() {}
}

// ✅ 业务代码统一传入
LocalDateTime weekStart = LocalDate.now(BIZ_ZONE)
        .with(DayOfWeek.MONDAY)
        .atStartOfDay();

LocalDate today = LocalDate.now(BIZ_ZONE);
LocalDateTime nowBiz = LocalDateTime.now(BIZ_ZONE);
Instant instantNow = Instant.now();  // Instant 本身是 UTC 时间戳，无歧义

嗅探信号

# 任何裸 .now() 在业务代码中都该 review
grep -rnE "LocalDate\.now\(\)|LocalDateTime\.now\(\)|LocalTime\.now\(\)" src/main/java/ \
    | grep -v "TimeConstants\|@Configuration"

# Date 系列在新代码中应淘汰
grep -rnE "new Date\(\)|new GregorianCalendar\(\)" src/main/java/

# Go
grep -rnE "time\.Now\(\)" --include="*.go" .

# JS / TS
grep -rnE "new Date\(\)|Date\.now\(\)" --include="*.ts" --include="*.js" src/

检查清单

• 项目内是否有统一的 BIZ_ZONE 常量
• Service / Handler 层禁止裸 .now()，必须显式时区
• Instant.now() 可以裸用（UTC 时间戳无歧义）
• 测试用 Clock.fixed(instant, zone) 注入，不要硬编码 now()

---