日期时间对象 - DateTime

背景介绍

由于 Java 自带的 Date 类在某些情况下使用不够便捷，且 Calendar 类相对复杂，Hutool 提供了一个增强版的日期时间类 DateTime。DateTime 类继承自 java.util.Date，不仅具备 Date 的全部功能，还提供了许多便捷方法，使日期时间的操作更加简洁易用。DateTime 对象吸取了 Joda-Time 库的优点，无需额外引入 Joda-Time 也能享受同样的便利。

1. 新建 DateTime 对象

DateTime 提供了多种构造方法，支持以下参数类型：

• Date 对象
• Calendar 对象
• String 类型的日期字符串（可附带格式化参数）
• long 类型的毫秒数

构建 DateTime 对象的两种常用方式是 DateTime.of() 和 new DateTime()。

// 使用当前日期对象构造 DateTime 对象
Date date = new Date();

// 方式一：通过 new 创建 DateTime 对象
DateTime time = new DateTime(date);
Console.log(time);

// 方式二：通过 of() 方法创建 DateTime 对象
DateTime dt = DateTime.of(date);

// 获取当前时间的 DateTime 对象
DateTime now = DateTime.now();

• new DateTime(Date date)：通过 Date 对象创建 DateTime 实例。
• DateTime.of(Date date)：通过静态方法创建 DateTime 实例。
• DateTime.now()：获取当前时间的 DateTime 对象。

实际开发中： 我们经常需要在业务中使用 DateTime 对象来替代 Date，以便使用更多便捷的方法处理日期和时间。

2. 使用 DateTime 对象的成员方法

DateTime 类提供的成员方法多为 DateUtil 类中静态方法的对象表现形式，使用 DateTime 可以简化代码，减少不必要的参数传递。

2.1 获取日期成员

DateTime 提供了获取年、月、日等信息的便捷方法。

// 创建一个 DateTime 对象
DateTime dateTime = new DateTime("2017-01-05 12:34:23", DatePattern.NORM_DATETIME_FORMAT);

// 获取年份，结果：2017
int year = dateTime.year();

// 获取季度（非季节），结果：Season.SPRING（春季）
Season season = dateTime.seasonEnum();

// 获取月份，结果：Month.JANUARY（1月）
Month month = dateTime.monthEnum();

// 获取日期中的“日”部分，结果：5
int day = dateTime.dayOfMonth();

• year()：返回年份。
• seasonEnum()：返回季度，结果为 Season 枚举类型。
• monthEnum()：返回月份，结果为 Month 枚举类型。
• dayOfMonth()：返回当前日期是当月的第几天。

实际开发中： 我们可以利用这些方法快速获取日期的不同部分，进行相关的业务逻辑处理，如根据季度生成报表、根据月份调整促销策略等。

2.2 日期的偏移操作

DateTime 提供了许多偏移方法，可以对日期进行加减操作，类似于 DateUtil 中的静态方法，但使用起来更加直观和简便。

// 创建一个 DateTime 对象
DateTime dateTime = new DateTime("2017-01-05 12:34:23", DatePattern.NORM_DATETIME_FORMAT);

// 偏移年份，结果：2018-01-05 12:34:23
DateTime offsetYear = dateTime.offset(DateField.YEAR, 1);

// 偏移月份，结果：2017-02-05 12:34:23
DateTime offsetMonth = dateTime.offset(DateField.MONTH, 1);

// 偏移天数，结果：2017-01-06 12:34:23
DateTime offsetDay = dateTime.offset(DateField.DAY_OF_MONTH, 1);

• offset(DateField field, int offset)：对 DateTime 对象进行时间单位上的偏移，如年份、月份、天数等。

实际开发中： 偏移操作广泛应用于定时任务的执行时间设置、自动生成到期日期等场景。

3. DateTime 对象的可变性

默认情况下，DateTime 对象是可变的，即调用偏移、设置字段等方法后，会直接修改原对象本身。这种可变性可能会在多处引用 DateTime 对象时引发问题。为了避免这种情况，可以将 DateTime 设置为不可变对象。

// 创建一个 DateTime 对象
DateTime dateTime = new DateTime("2017-01-05 12:34:23", DatePattern.NORM_DATETIME_FORMAT);

// 默认情况下，DateTime 为可变对象，此时 offset == dateTime
DateTime offset = dateTime.offset(DateField.YEAR, 0);

// 设置为不可变对象后，偏移操作将返回新对象，此时 offset != dateTime
dateTime.setMutable(false);
offset = dateTime.offset(DateField.YEAR, 0);

• setMutable(boolean mutable)：设置 DateTime 对象是否可变，true 为可变，false 为不可变。

实际开发中： 如果需要在多个地方使用同一个 DateTime 对象，且不希望原对象被修改，可以设置为不可变模式，避免因意外修改带来的逻辑错误。

4. DateTime 对象的格式化输出

DateTime 对象可以直接调用 toString() 方法，将日期时间转换为字符串。默认格式为 yyyy-MM-dd HH:mm:ss，也可以传入自定义格式。

// 创建一个 DateTime 对象
DateTime dateTime = new DateTime("2017-01-05 12:34:23", DatePattern.NORM_DATETIME_FORMAT);

// 使用默认格式转换为字符串，结果：2017-01-05 12:34:23
String dateStr = dateTime.toString();

// 使用自定义格式转换为字符串，结果：2017/01/05
String dateStrCustom = dateTime.toString("yyyy/MM/dd");

• toString()：返回 yyyy-MM-dd HH:mm:ss 格式的日期时间字符串。
• toString(String format)：使用指定格式返回日期时间字符串。

实际开发中： 格式化输出经常用于日志记录、数据展示、文件命名等场景。

---

总结

Hutool 的 DateTime 对象在日期时间的操作上非常灵活且功能强大。它不仅继承了 Date 类的全部功能，还提供了许多便捷方法，使日期时间处理变得更加简单和高效。在实际开发中，DateTime 对象是替代 Date 和 Calendar 的理想选择，能极大提升代码的可读性和维护性。