落地Java日期时间API的关键是建立可执行、可检查、可传承的协作习惯，统一建模规范（LocalDate/Instant/ZonedDateTime等按语义选用）、封装工具类（TimeProvider、预定义格式器）、数据库与序列化对齐（禁用LocalDateTime DTO、显式时区控制），并严格执行代码审查清单。
在团队中落地 Java 日期时间 API 的最佳实践，关键不是堆砌技术细节，而是建立可执行、可检查、可传承的协作习惯。核心目标是：让所有人写的时间逻辑一致、可读、可测、不出时区 bug。
统一时间建模规范
明确项目里每种时间语义该用哪个类，避免随意混用：
- 存储用户填写的“生日”“合同生效日”等纯日期 → 强制用 LocalDate
- 记录系统操作日志时间戳（如“订单创建于”）→ 必须用 Instant 或 ZonedDateTime，禁止用 LocalDateTime 存数据库
- 前端展示给上海用户看的“下单时间” → 后端返回 ZonedDateTime 并带
Asia/Shanghai，或统一转成 ISO-8601 字符串（含+08:00） - 定时任务触发时间（如“每天凌晨2点跑批”）→ 使用 LocalTime + 固定时区（如
ZoneId.of("Asia/Shanghai")），避免依赖服务器本地时区
封装基础工具类，禁用原始构造
不许任何人直接 new LocalDate.now() 或 LocalDateTime.parse(...)，全部走团队封装的工具：
- 提供
TimeProvider接口，生产环境默认返回系统时钟，测试时可注入固定时间（便于单元测试断言） - 提供
DateFormatters工具类，只暴露预定义的格式常量，如YYYY_MM_DD、ISO_DATETIME_WITH_ZONE，禁止运行时拼接 pattern - 所有字符串解析入口统一收口，例如
TimeParsers.parseAsInstant(String s)内部强制按 UTC 解析；parseAsShanghaiZdt(String s)强制绑定上海时区
数据库与序列化对齐
避免 ORM 或 JSON 库自动转换引入隐式行为：
立即学习“Java免费学习笔记（深入）”；
- JPA/Hibernate：对 Instant 字段用
@Column(columnDefinition = "TIMESTAMP WITH TIME ZONE")（PostgreSQL）或@Column(columnDefinition = "BIGINT")（MySQL 存毫秒值），并配@Converter显式控制 - JSON 序列化（Jackson）：全局配置
JavaTimeModule，禁用WRITE_DATES_AS_TIMESTAMPS，确保 Instant 输出为 ISO 字符串（如"2026-10-09T04:33:00Z"） - 禁止在 DTO 中暴露 LocalDateTime 字段——它没有时区信息，前端无法可靠还原本地时间
代码审查清单（PR 时必查）
把以下条目写进团队 Code Review CheckList，每次合并前打钩：
- 是否用了
new Date()、Calendar.getInstance()或SimpleDateFormat？→ 拒绝合入 - 是否有
LocalDateTime.now()出现在业务逻辑中？→ 改为通过TimeProvider获取 - 数据库字段类型和 Java 类型是否匹配？（例如 MySQL
DATETIME对应LocalDateTime是错的，应对应ZonedDateTime或Instant） - 日志打印时间是否用了
Instant.now().toString()？避免LocalDateTime.now().toString()（无时区，日志无法跨服务器比对）
