LocalDateTime 工具类 - LocalDateTimeUtil

介绍

从 Hutool 5.4.x 版本开始，LocalDateTimeUtil 工具类提供了对 JDK 8+ 日期 API 的封装，包含了 LocalDateTime 和 LocalDate 的解析、格式化、转换等常见操作。该工具类使得日期时间的操作更加简便，符合现代 Java 开发的习惯。

1. 日期转换

LocalDateTimeUtil 提供了将 Date 对象、时间戳转换为 LocalDateTime 的方法。

// 定义一个日期字符串
String dateStr = "2020-01-23T12:23:56";

// 将日期字符串解析为 DateTime 对象
DateTime dt = DateUtil.parse(dateStr);

// 将 Date 对象转换为 LocalDateTime 对象
LocalDateTime localDateTime = LocalDateTimeUtil.of(dt);
// 参数 dt：表示要转换的 Date 对象
// 返回值：LocalDateTime 表示对应的本地日期时间

// 通过时间戳转换为 LocalDateTime 对象（UTC时间）
LocalDateTime localDateTimeFromTimestamp = LocalDateTimeUtil.ofUTC(dt.getTime());
// 参数 dt.getTime()：表示要转换的时间戳
// 返回值：LocalDateTime 表示对应的本地日期时间

• of(Date date)：将 Date 对象转换为 LocalDateTime。
• ofUTC(long timestamp)：将时间戳转换为 LocalDateTime（UTC时间）。

实际开发中： 在处理旧系统遗留的 Date 类型数据时，通常需要转换为 LocalDateTime，以便更方便地进行时间计算和操作。

2. 日期字符串解析

LocalDateTimeUtil 可以将字符串解析为 LocalDateTime 或 LocalDate 对象，支持 ISO 标准格式和自定义格式。

// 解析 ISO 标准时间字符串为 LocalDateTime 对象
LocalDateTime localDateTime = LocalDateTimeUtil.parse("2020-01-23T12:23:56");
// 参数："2020-01-23T12:23:56"：表示要解析的日期字符串
// 返回值：LocalDateTime 表示解析后的本地日期时间

// 解析自定义格式时间字符串为 LocalDateTime 对象
localDateTime = LocalDateTimeUtil.parse("2020-01-23", DatePattern.NORM_DATE_PATTERN);
// 参数："2020-01-23"：表示要解析的日期字符串
// 参数：DatePattern.NORM_DATE_PATTERN：表示使用的日期格式模式
// 返回值：LocalDateTime 表示解析后的本地日期时间

• parse(String dateStr)：解析符合 ISO 标准的日期时间字符串为 LocalDateTime。
• parse(String dateStr, DateTimeFormatter formatter)：解析自定义格式的日期时间字符串为 LocalDateTime。

// 解析自定义格式的日期字符串为 LocalDate 对象
LocalDate localDate = LocalDateTimeUtil.parseDate("2020-01-23");
// 参数："2020-01-23"：表示要解析的日期字符串
// 返回值：LocalDate 表示解析后的本地日期

// 解析日期时间字符串为 LocalDate 对象，忽略时间部分
localDate = LocalDateTimeUtil.parseDate("2020-01-23T12:23:56", DateTimeFormatter.ISO_DATE_TIME);
// 参数："2020-01-23T12:23:56"：表示要解析的日期时间字符串
// 参数：DateTimeFormatter.ISO_DATE_TIME：表示使用的格式化器
// 返回值：LocalDate 表示解析后的本地日期，忽略时间部分

• parseDate(String dateStr)：解析日期字符串为 LocalDate。
• parseDate(String dateStr, DateTimeFormatter formatter)：解析日期时间字符串为 LocalDate，忽略时间部分。

实际开发中： 解析用户输入的日期时间字符串或从接口返回的数据时，常常需要将其转换为 LocalDateTime 或 LocalDate 以便后续操作。

3. 日期格式化

LocalDateTimeUtil 提供了将 LocalDateTime 格式化为字符串的功能，支持标准格式和自定义格式。

// 定义一个 LocalDateTime 对象
LocalDateTime localDateTime = LocalDateTimeUtil.parse("2020-01-23T12:23:56");

// 使用标准格式将 LocalDateTime 格式化为字符串
String formattedDate = LocalDateTimeUtil.format(localDateTime, DatePattern.NORM_DATETIME_PATTERN);
// 参数：localDateTime：表示要格式化的 LocalDateTime 对象
// 参数：DatePattern.NORM_DATETIME_PATTERN：表示使用的日期格式模式
// 返回值：String 表示格式化后的日期时间字符串

• format(LocalDateTime localDateTime, String pattern)：将 LocalDateTime 格式化为指定格式的字符串。

实际开发中： 格式化日期时间通常用于日志记录、数据展示或生成文件名等。

4. 日期偏移

LocalDateTimeUtil 支持对日期时间进行偏移操作，可以向前或向后偏移任意时间单位。

// 定义一个 LocalDateTime 对象
final LocalDateTime localDateTime = LocalDateTimeUtil.parse("2020-01-23T12:23:56");

// 偏移一天，得到新的 LocalDateTime 对象
LocalDateTime offset = LocalDateTimeUtil.offset(localDateTime, 1, ChronoUnit.DAYS);
// 参数：localDateTime：表示要偏移的 LocalDateTime 对象
// 参数：1：表示偏移量
// 参数：ChronoUnit.DAYS：表示时间单位为天
// 返回值：LocalDateTime 表示偏移后的新日期时间

// 如果是减少时间，可以传入负数作为偏移量
offset = LocalDateTimeUtil.offset(localDateTime, -1, ChronoUnit.DAYS);
// 结果：偏移一天后返回的 LocalDateTime 对象为 "2020-01-22T12:23:56"

• offset(LocalDateTime localDateTime, long amountToAdd, TemporalUnit unit)：对 LocalDateTime 对象进行时间偏移。

实际开发中： 偏移操作常用于计算未来的某个日期时间或回溯某个事件的发生时间等场景。

5. 计算时间间隔

LocalDateTimeUtil 可以计算两个日期时间之间的间隔，结果以 Duration 表示。

// 定义两个 LocalDateTime 对象
LocalDateTime start = LocalDateTimeUtil.parse("2019-02-02T00:00:00");
LocalDateTime end = LocalDateTimeUtil.parse("2020-02-02T00:00:00");

// 计算两个日期时间之间的间隔，返回 Duration 对象
Duration between = LocalDateTimeUtil.between(start, end);
// 参数：start：表示开始的 LocalDateTime 对象
// 参数：end：表示结束的 LocalDateTime 对象
// 返回值：Duration 表示时间间隔

// 将时间间隔转换为天数
long daysBetween = between.toDays();
// 返回值：long 表示间隔的天数，结果为 365

• between(LocalDateTime startInclusive, LocalDateTime endExclusive)：计算两个 LocalDateTime 之间的时间间隔，返回 Duration 对象。

实际开发中： 计算两个事件的间隔时间（如任务执行时间、活动持续时间等）时，常使用该方法。

6. 获取一天的开始和结束时间

LocalDateTimeUtil 提供了获取某一天的开始时间（00:00）和结束时间（23:59:59.999999999）的方法。

// 定义一个 LocalDateTime 对象
LocalDateTime localDateTime = LocalDateTimeUtil.parse("2020-01-23T12:23:56");

// 获取当天的开始时间，结果："2020-01-23T00:00"
LocalDateTime beginOfDay = LocalDateTimeUtil.beginOfDay(localDateTime);
// 参数：localDateTime：表示要获取开始时间的 LocalDateTime 对象
// 返回值：LocalDateTime 表示当天的开始时间

// 获取当天的结束时间，结果："2020-01-23T23:59:59.999999999"
LocalDateTime endOfDay = LocalDateTimeUtil.endOfDay(localDateTime);
// 参数：localDateTime：表示要获取结束时间的 LocalDateTime 对象
// 返回值：LocalDateTime 表示当天的结束时间

• beginOfDay(LocalDateTime localDateTime)：返回某一天的开始时间（00:00）。
• endOfDay(LocalDateTime localDateTime)：返回某一天的结束时间（23:59: