java.time 时间开发规范文档

0. 文档前言

目标：彻底根治 Java 时间时区错乱、线程安全、格式化异常、新旧 API 混用问题

适用范围：所有 SpringBoot 新项目、旧项目重构

核心原则：统一时区、统一类型、统一格式、全程无 Date

本规范统一抛弃老旧的 java.util.Date、Calendar、SimpleDateFormat，全面采用Java 8+ JSR-310 全新时间 API，实现线程安全、时区可控、无歧义时间开发。

1. 核心技术选型规范（强制）

1.1 禁止使用类型（红线）

项目中禁止出现以下所有类，一律替换为新时间 API：

java.util.Date（可变、时区欺骗、API 反人类）
java.util.Calendar（臃肿、性能差、线程不安全）
SimpleDateFormat（致命线程不安全）
java.sql.Date/Time/Timestamp（兼容旧时代产物）

1.2 统一使用类型（标准）

场景	推荐类型	核心作用
数据库存储、时间计算、接口时间戳、日志时间	Instant	UTC 绝对时间戳、全局唯一、无时区歧义、线程安全
前端展示、本地业务判断、日期格式化	LocalDateTime/LocalDate	人类可读时间，用于页面展示、业务判断
跨时区、国际化、海外业务系统	ZonedDateTime	携带时区信息，支持全球时间转换

1.3 全局统一时区（强制）

所有业务系统统一时区：Asia/Shanghai（UTC+8）

底层存储、时间计算基于 UTC，页面展示统一东八区，杜绝时区混乱。

2. 数据库字段设计规范

2.1 时间字段类型标准

MySQL 数据库时间字段统一使用：DATETIME(6)

DATETIME(6)：支持纳秒精度，完美匹配 Instant 精度
禁止使用 DATETIME（无精度，丢失毫秒）、TIMESTAMP（时区、范围限制）

2.2 通用审计字段规范（所有表通用）

-- 通用审计字段create_timeDATETIME(6) NULLCOMMENT '创建时间'update_timeDATETIME(6) NULLCOMMENT '更新时间'

3. 实体类时间字段规范

3.1 字段定义标准

所有实体类审计时间字段，统一使用 Instant，搭配自动填充注解：

importcom.baomidou.mybatisplus.annotation.FieldFill;importcom.baomidou.mybatisplus.annotation.TableField;importjava.time.Instant;// 创建时间：仅插入时填充@TableField(fill = FieldFill.INSERT)private Instant createTime;// 更新时间：插入、更新均填充@TableField(fill = FieldFill.INSERT_UPDATE)private Instant updateTime;

3.2 禁止行为

禁止实体类使用 Date 类型
禁止手动 set 创建时间、更新时间（统一自动填充）
禁止用 LocalDateTime 直接映射数据库（无时区，存储有歧义）

4. MyBatis-Plus 配置规范

4.1 核心配置（application.yml）

mybatis-plus:  configuration:    map-underscore-to-camel-case: true    type-handlers-enabled: true # 开启 JSR310 时间类型自动转换

4.2 全局自动时间填充配置

统一配置 MetaObjectHandler，实现创建/更新时间自动赋值，全局生效：

import com.baomidou.mybatisplus.core.handlers.MetaObjectHandler;import org.apache.ibatis.reflection.MetaObject;import org.springframework.context.annotation.Configuration;import java.time.Instant;@ConfigurationpublicclassMetaObjectHandlerConfigimplementsMetaObjectHandler{@OverridepublicvoidinsertFill(MetaObject metaObject){this.strictInsertFill(metaObject, "createTime", Instant::now, Instant.class);this.strictInsertFill(metaObject, "updateTime", Instant::now, Instant.class);    }@OverridepublicvoidupdateFill(MetaObject metaObject){this.strictUpdateFill(metaObject, "updateTime", Instant::now, Instant.class);    }}

5. 接口 JSON 序列化规范

5.1 统一返回格式

后端实体类 Instant 字段，自动序列化为：yyyy-MM-dd HH:mm:ss 北京时间字符串

前端传入同格式时间字符串，自动反序列化为 Instant，无需手动转换。

5.2 全局 Jackson 时间格式化配置

import com.fasterxml.jackson.datatype.jsr310.deser.InstantDeserializer;import com.fasterxml.jackson.datatype.jsr310.ser.InstantSerializer;import org.springframework.boot.autoconfigure.jackson.Jackson2ObjectMapperBuilderCustomizer;import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.Configuration;import java.time.Instant;import java.time.ZoneId;import java.time.format.DateTimeFormatter;@ConfigurationpublicclassJacksonTimeConfig{privatestaticfinal String PATTERN = "yyyy-MM-dd HH:mm:ss";privatestaticfinal String ZONE_ID = "Asia/Shanghai";@Beanpublic Jackson2ObjectMapperBuilderCustomizer jackson2ObjectMapperBuilderCustomizer(){return builder -> {// 序列化：Instant → 北京时间字符串            builder.serializerByType(Instant.class, newInstantSerializer(DateTimeFormatter.ofPattern(PATTERN).withZone(ZoneId.of(ZONE_ID))            ));// 反序列化：时间字符串 → Instant            builder.deserializerByType(Instant.class, newInstantDeserializer(InstantDeserializer.INSTANT,DateTimeFormatter.ofPattern(PATTERN).withZone(ZoneId.of(ZONE_ID))            ));        };    }}

6. 业务代码时间操作规范

6.1 统一使用工具类

所有时间获取、转换、格式化、计算，统一使用项目内置 TimeUtil，禁止手写格式化、时间计算逻辑。

6.2 核心业务准则

存库、计算、对比：必须用 Instant
页面展示、日志打印：转 LocalDateTime 格式化
前后端交互：自动格式化字符串，无需手动处理
时间差、时间加减：使用 Duration、ChronoUnit 或 TimeUtil 方法

6.3 禁止写法

禁止 new Date() 获取当前时间
禁止 SimpleDateFormat 格式化时间
禁止手动拼接时间字符串
禁止 LocalDateTime 直接存数据库（无时区，存在歧义）

7. 前后端交互规范

7.1 后端 → 前端

Instant 自动输出yyyy-MM-dd HH:mm:ss 标准北京时间，前端直接展示即可。

7.2 前端 → 后端

前端传标准格式时间字符串，后端直接用 Instant 接收，自动解析，无需手动转换。

7.3 时间戳交互

如需时间戳传输，统一使用毫秒级时间戳，通过 TimeUtil 完成 Instant 与时间戳互转。

8. 常见问题与避坑准则

8.1 核心避坑点

Instant 是 UTC 时间，仅存储计算用，禁止直接 toString 展示给用户（带Z时区标识）
LocalDateTime 无时区，禁止用于数据库存储，仅用于展示
所有时间转换必须绑定 Asia/Shanghai 时区，避免系统默认时区导致错乱
新时间 API 全部不可变，时间加减会返回新对象，无需担心并发修改

8.2 新旧代码迁移规则

所有旧 Date 字段，逐步替换为 Instant
所有 SimpleDateFormat 格式化，替换为 TimeUtil 工具方法
所有手动赋值 createTime/updateTime 代码，直接删除，依赖自动填充

9. 规范总结（极简口诀）

存库用Instant，展示用LocalDateTime

数据库存datetime6，全局时区东八区

自动填充时间值，接口自动格式化

抛弃Date旧API，线程安全零bug

10. 附件：TimeUtil 工具类

import java.time.*;import java.time.format.DateTimeFormatter;import java.time.temporal.ChronoUnit;import java.util.Date;/** * 企业级通用时间工具类 * 【规范配套】统一使用 Asia/Shanghai 时区 * 全程基于 Java 8+ java.time 包，线程安全 * 禁止使用 Date / SimpleDateFormat * * @author 项目架构组 */publicfinalclassTimeUtil{// 全局常量（强制统一）publicstaticfinal ZoneId ZONE_SHANGHAI = ZoneId.of("Asia/Shanghai");publicstaticfinal String DATETIME_PATTERN = "yyyy-MM-dd HH:mm:ss";publicstaticfinal String DATE_PATTERN = "yyyy-MM-dd";publicstaticfinal String TIME_PATTERN = "HH:mm:ss";publicstaticfinal String DATETIME_MS_PATTERN = "yyyy-MM-dd HH:mm:ss.SSS";// 线程安全的格式化器publicstaticfinal DateTimeFormatter DATETIME_FORMATTER = DateTimeFormatter.ofPattern(DATETIME_PATTERN).withZone(ZONE_SHANGHAI);publicstaticfinal DateTimeFormatter DATE_FORMATTER = DateTimeFormatter.ofPattern(DATE_PATTERN).withZone(ZONE_SHANGHAI);publicstaticfinal DateTimeFormatter TIME_FORMATTER = DateTimeFormatter.ofPattern(TIME_PATTERN).withZone(ZONE_SHANGHAI);// ====================== 1. 获取当前时间 ======================/**     * 获取当前 Instant（UTC时间戳，推荐用于存储、计算、传输）     */publicstatic Instant now(){return Instant.now();    }/**     * 获取当前毫秒时间戳     */publicstaticlongcurrentMillis(){return System.currentTimeMillis();    }/**     * 获取当前北京时间（LocalDateTime）     */publicstatic LocalDateTime nowLocalDateTime(){return LocalDateTime.now(ZONE_SHANGHAI);    }// ====================== 2. 类型转换 ======================/**     * Date → Instant（兼容旧代码）     */publicstatic Instant toInstant(Date date){if (date == null) {returnnull;        }return date.toInstant();    }/**     * 毫秒时间戳 → Instant     */publicstatic Instant toInstant(long millis){return Instant.ofEpochMilli(millis);    }/**     * Instant → 北京时间 LocalDateTime     */publicstatic LocalDateTime toLocalDateTime(Instant instant){if (instant == null) {returnnull;        }return LocalDateTime.ofInstant(instant, ZONE_SHANGHAI);    }/**     * LocalDateTime → Instant（北京时间 → UTC）     */publicstatic Instant toInstant(LocalDateTime localDateTime){if (localDateTime == null) {returnnull;        }return localDateTime.atZone(ZONE_SHANGHAI).toInstant();    }// ====================== 3. 时间格式化（Instant → 字符串） ======================/**     * 格式化为：yyyy-MM-dd HH:mm:ss     */publicstatic String formatDateTime(Instant instant){if (instant == null) {return"";        }return DATETIME_FORMATTER.format(instant);    }/**     * 格式化为：yyyy-MM-dd     */publicstatic String formatDate(Instant instant){if (instant == null) {return"";        }return DATE_FORMATTER.format(instant);    }/**     * 格式化为：HH:mm:ss     */publicstatic String formatTime(Instant instant){if (instant == null) {return"";        }return TIME_FORMATTER.format(instant);    }// ====================== 4. 字符串解析（字符串 → Instant） ======================/**     * 解析 yyyy-MM-dd HH:mm:ss → Instant     */publicstatic Instant parseDateTime(String text){if (text == null || text.isBlank()) {returnnull;        }        LocalDateTime localDateTime = LocalDateTime.parse(text, DATETIME_FORMATTER);return toInstant(localDateTime);    }/**     * 解析 yyyy-MM-dd 00:00:00 → Instant     */publicstatic Instant parseDate(String text){if (text == null || text.isBlank()) {returnnull;        }        LocalDate localDate = LocalDate.parse(text, DATE_FORMATTER);return toInstant(localDate.atStartOfDay());    }// ====================== 5. 时间差计算 ======================publicstaticlongbetweenSeconds(Instant start, Instant end){return ChronoUnit.SECONDS.between(start, end);    }publicstaticlongbetweenMinutes(Instant start, Instant end){return ChronoUnit.MINUTES.between(start, end);    }publicstaticlongbetweenHours(Instant start, Instant end){return ChronoUnit.HOURS.between(start, end);    }publicstaticlongbetweenDays(Instant start, Instant end){return ChronoUnit.DAYS.between(start, end);    }// ====================== 6. 时间加减 ======================publicstatic Instant plusSeconds(Instant instant, long seconds){return instant.plusSeconds(seconds);    }publicstatic Instant plusMinutes(Instant instant, long minutes){return instant.plus(minutes, ChronoUnit.MINUTES);    }publicstatic Instant plusHours(Instant instant, long hours){return instant.plus(hours, ChronoUnit.HOURS);    }publicstatic Instant plusDays(Instant instant, long days){return instant.plus(days, ChronoUnit.DAYS);    }publicstatic Instant minusDays(Instant instant, long days){return instant.minus(days, ChronoUnit.DAYS);    }// ====================== 7. 常用快捷方法 ======================/**     * 今天 00:00:00     */publicstatic Instant todayStart(){return LocalDate.now(ZONE_SHANGHAI)                .atStartOfDay(ZONE_SHANGHAI)                .toInstant();    }/**     * 今天 23:59:59.999     */publicstatic Instant todayEnd(){return LocalDate.now(ZONE_SHANGHAI)                .atTime(LocalTime.MAX)                .atZone(ZONE_SHANGHAI)                .toInstant();    }/**     * 是否是过去时间     */publicstaticbooleanisBeforeNow(Instant instant){return instant.isBefore(now());    }/**     * 是否是未来时间     */publicstaticbooleanisAfterNow(Instant instant){return instant.isAfter(now());    }}