Java日期时间工具类应以java.time为主，采用final静态类、不可变参数/返回值、线程安全设计；封装字符串转换、当前时间获取、时间计算、时区处理等功能；规避SimpleDateFormat、隐式时区、null静默等陷阱；提供重载、Optional、常量及全覆盖测试。
Java 中编写通用的日期时间工具类，核心是封装常用操作、屏蔽 JDK 版本差异（如 java.util.Date 与 java.time.* 的混用）、避免重复造轮子，并保持线程安全和易读性。推荐以 java.time（Java 8+）为主设计，兼顾兼容性和实用性。
基础结构：静态工具类 + 不可变设计
定义一个 final 类，所有方法为 static，不保存状态，避免实例化：
public final class DateTimeUtils {
private DateTimeUtils() {} // 禁止实例化
}
所有入参使用不可变类型（如 LocalDateTime、ZonedDateTime、Instant），返回也保持不可变，符合函数式习惯。
常用功能封装示例
覆盖高频场景，每个方法职责单一、命名清晰：
java-api-doc-generator
下载
分析 Java Spring Boot 后端 Controller 代码，自动生成 Markdown 格式的接口文档。当用户说“生成 Java 接口文档”、“生成 API 文档”、“从 Spring 代码生成文档”时触发。
立即学习“Java免费学习笔记（深入）”；
-
字符串 ↔ 时间对象转换：预置常用格式（如
"yyyy-MM-dd HH:mm:ss"），支持自定义 pattern；内部统一用DateTimeFormatter，线程安全（JDK 8+ 的 formatter 是不可变且线程安全的）。 -
当前时间快捷获取：如
nowLocalDateTime()、nowInstant()、today()（返回 LocalDate），避免每次 new 或调用System.currentTimeMillis()。 -
时间计算：加减天/小时/分钟（
plusDays(LocalDateTime, int)）、计算间隔（daysBetween(LocalDate, LocalDate)）、判断是否在某区间内（isBetween(LocalDateTime, LocalDateTime, LocalDateTime)）。 -
时区处理：提供默认时区（如
ZoneId.systemDefault()）或显式传入，例如toZonedDateTime(Instant, ZoneId)、convertZone(LocalDateTime, ZoneId, ZoneId)。
规避常见陷阱
实际开发中容易踩坑的地方需主动防御：
- 不直接暴露
SimpleDateFormat（已过时且非线程安全），若需兼容旧代码，内部用ThreadLocal<datetimeformatter></datetimeformatter>或直接改用DateTimeFormatter。 - 解析字符串时明确指定时区，避免隐式依赖系统默认时区导致测试环境与生产环境行为不一致。
- 对 null 入参做快速校验并抛出明确异常（如
IllegalArgumentException），不静默返回或返回空值，便于早期发现问题。 - 避免在工具类中做业务逻辑判断（如“是否为工作日”），这类应下沉到业务层或单独的业务规则类。
增强可用性的小技巧
让工具类更贴近开发直觉：
- 提供重载方法：例如
parse(String)默认用标准格式，parse(String, String pattern)支持自定义。 - 返回 Optional：对可能解析失败的操作（如
parseOpt(String)），用Optional<localdatetime></localdatetime>替代 try-catch，调用方更可控。 - 补充实用常量：如
DEFAULT_DATETIME_PATTERN = "yyyy-MM-dd HH:mm:ss"、EPOCH_DAY = LocalDate.of(1970, 1, 1)。 - 单元测试全覆盖：尤其验证边界值（如闰年2月29日、夏令时切换时刻、不同时区转换）。
