Java · java.time 时间处理

场景 1 · 全局约定改造: DB/服务全 UTC, 出口统一格式化

三地部署后同一笔订单的创建时间差 8/13 小时, 报表对不上账; 按清单一次改造, 全链路统一 UTC:

// 改造清单 (新服务直接照抄):
// 1) JDBC URL: jdbc:mysql://...?connectionTimeZone=UTC&forceConnectionTimeZoneToSession=true
// 2) 实体时间字段统一 Instant/OffsetDateTime, 列类型 TIMESTAMP
// 3) API 出口 RFC3339 带偏移, 关掉时间戳数字序列化
@Bean
Jackson2ObjectMapperBuilderCustomizer utcJackson() {
    return b -> b.featuresToDisable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS);
}
// 4) JVM 启动参数 -Duser.timezone=UTC, 把"默认时区"这个暗依赖也钉死
// 5) 存量表: 写双读旧的一次迁移窗口内换列, 别在线上双写超过一周

改造后三地报表同一时刻对齐, "时间差 8 小时"类工单清零。

场景 2 · "每天 8 点发券"按用户时区分组分批

全球用户都想在自己本地的早上 8 点收到券; 服务器只有一个 UTC 时钟 — 按时区分组调度:

Map<ZoneId, List<User> byZone = users.stream()
    .collect(groupingBy(u -> ZoneId.of(u.getTimeZone())));   // "Asia/Shanghai"
for (var en : byZone.entrySet()) {
    ZoneId zone = en.getKey();
    ZonedDateTime next8 = LocalDate.now(zone).atTime(8, 0).atZone(zone); // 今天本地 08:00
    if (!next8.isAfter(ZonedDateTime.now(zone))) next8 = next8.plusDays(1); // 过了排明天
    scheduler.schedule(() -> sendBatch(en.getValue()),
        Duration.between(Instant.now(), next8.toInstant()).toMillis(),
        TimeUnit.MILLISECONDS);    // 调度内部统一换算回 UTC Instant, 只在入口看钟面
}

场景 3 · DateTimeFormatter 预编译 static final, 格式化百万次省一个核

导出接口每次请求都 ofPattern, 压测显示 12% CPU 花在"反复解析同一串 pattern":

// 差: 每次调用都解析 pattern + 新建 formatter
String s = now().format(DateTimeFormatter.ofPattern("uuuu-MM-dd HH:mm:ss"));

// 好: 不可变, 预编译一次全局共享
private static final DateTimeFormatter TS = DateTimeFormatter.ofPattern("uuuu-MM-dd HH:mm:ss");

// 更好: 预定义常量零解析, ISO 出口直接用
private static final DateTimeFormatter ISO = DateTimeFormatter.ISO_LOCAL_DATE_TIME;
// JMH 量级: 每次构建 ~1μs → 静态复用 ~120ns; 日志百万次/天 ≈ 省下 15 分钟纯 CPU

场景 4 · Duration 管接口耗时与超时预算

"这次调用花了多少/超没超预算"用 Duration 表达, 天然可读可比较, 别再手写毫秒减法:

Instant t0 = clock.instant();
try {
    return callDownstream(req);
} finally {
    Duration cost = Duration.between(t0, clock.instant());
    metrics.observe(cost);                       // 直方图: P99 从这看
    if (cost.compareTo(budget) > 0)             // 预算超支即时告警
        log.warn("slow call cost={} budget={}", cost, budget);
}
// 预算拆账: 总 P99 300ms = 网关 20 + 下游A 200 + 下游B 80, 全用 Duration 声明
private static final Duration BUDGET = Duration.ofMillis(200);

场景 5 · Clock 注入: 过期判断/倒计时测试不再碰运气

token 过期逻辑直接 now(), 测试要么 sleep 要么构造"刚好临界"的数据, 偶发红; 把时间变成输入:

class TokenService {
    private final Clock clock;               // 构造器注入, 生产传 systemUTC()
    TokenService(Clock clock) { this.clock = clock; }

    boolean expired(Token t) {
        return t.expireAt().isBefore(clock.instant());  // "现在"是注入的
    }
}
// 测试: 固定钟钉死当前时刻, 边界用例一次写全
Clock frozen = Clock.fixed(Instant.parse("2026-09-26T00:00:00Z"), ZoneOffset.UTC);
var svc = new TokenService(frozen);
assertTrue(svc.expired(new Token("2026-09-25T23:59:59Z")));   // 过期 1 秒
assertFalse(svc.expired(new Token("2026-09-26T00:00:01Z")));  // 还剩 1 秒

场景 6 · 跨时区会议室: 同一时刻的三个钟面 + 冲突检测

上海提议的会议时间, 纽约/伦敦同事各自钟面是几点, 是否落在各自工作时间 — 一次换算全知道:

ZoneId SH = ZoneId.of("Asia/Shanghai"), NY = ZoneId.of("America/New_York"),
       LO = ZoneId.of("Europe/London");
ZonedDateTime sh = LocalDate.of(2026, 9, 28).atTime(9, 0).atZone(SH); // 上海 09:00
ZonedDateTime ny = sh.withZoneSameInstant(NY);   // 同一时刻的纽约钟面 21:00 前一天
ZonedDateTime lo = sh.withZoneSameInstant(LO);   // 伦敦钟面 02:00
boolean ok = ny.getHour() >= 8 && ny.getHour() < 20 && lo.getHour() >= 8 && lo.getHour() < 20;
// withZoneSameInstant: 时刻不动换钟面; withZoneSameLocal: 保钟面换时刻 — 用错就是事故

场景 7 · 夏令时切换日: 23/25 小时的排班与计费

美国区活动按"自然天"计费, 春令时那天只有 23 小时, 手写 24*3600 的代码多收了一小时的钱:

ZoneId ny = ZoneId.of("America/New_York");
LocalDate dst = LocalDate.of(2026, 3, 8);         // 春令时: 当天少 1 小时
ZonedDateTime a = dst.atStartOfDay(ny);
ZonedDateTime b = dst.plusDays(1).atStartOfDay(ny);
Duration dayLen = Duration.between(a, b);       // PT23H — 不是 24 小时!
// 计费/排班按 Duration 算自动正确; 按小时单价 × 24 就是多收钱
// 钟面语义: zdt.plusDays(1) 保持钟面 (02:30 的下一天还是 02:30, 不存在的时刻自动平移)
// 秋令时 11-1: 01:30 出现两次, 存库必须带偏移/规则否则读不回唯一时刻

场景 8 · 时间分片 key: 按天分表用哪个"天"

订单表按天分了 1024 张, 分片键取值时用服务器本地日期 — 8 小时差让 0 点后的单落错表, 迁移脚本全部对不上:

static final ZoneId SHARD_ZONE = ZoneOffset.UTC;   // 写死并文档化, 全链路一致
static String tableFor(Instant t) {
    LocalDate day = t.atZone(SHARD_ZONE).toLocalDate();   // UTC 天, 与存储约定同源
    return "order_" + day.format(DateTimeFormatter.BASIC_ISO_DATE); // order_20260926
}
// 跨天查询: [t0, t1) 先换算出覆盖的 UTC 天集合, 再逐表 UNION — 别用本地天猜
// 想按"业务本地天"分片可以, 但 SHARD_ZONE 必须是常量并进设计文档, 不许读系统默认

场景 9 · 账单/生日的 Period 月度对齐

会员账单"每月 15 日出账", 用 30 天近似的结果是半年后账单日漂到 17 号, 客服爆单:

LocalDate billStart = LocalDate.of(2026, 8, 15);
LocalDate billEnd   = billStart.plus(Period.ofMonths(1));   // 2026-09-15, 月度语义
Period cycle = Period.between(billStart, billEnd);         // P1M: 28/29/30/31 天都对
// 生日提醒: birthday.withYear(today.getYear()) 再比较今天
// 2/29 生日在平年要自己定规则 (2/28 或 3/1), java.time 不会替你做业务决定
// 千万别用 Duration.ofDays(30) 凑月 — 两种"量"混用是本页头号坑

场景 10 · 老代码 Date/Calendar → java.time 机械替换清单

三十万行遗留代码不敢大动; 按"等价替换"清单机械迁移, 每条都有映射, 不改行为只换类型:

// Date → Instant:            date.toInstant()  /  Date.from(instant)
// Calendar → ZonedDateTime:   cal.toInstant().atZone(ZoneId.systemDefault())
// SimpleDateFormat → DTF:     ofPattern 预编译 static final 后共享
// cal.add(DAY_OF_MONTH, 1):  老日历 1/31+1 天静默滚到 3/3; zdt.plusDays(1) 直接抛异常
//                            — 迁移时把"依赖静默溢出"的代码暴露出来是收益不是麻烦
// new Date() → clock.instant(); System.currentTimeMillis() 计时用途可保留
// java.sql.Timestamp → rs.getObject(col, OffsetDateTime.class) (JDBC 4.2+)
// 三行替换覆盖 90% 场景; 剩下的 (日历算法/夏令时逻辑) 先补测试再动