Hutool之DateUtil：让Java日期处理变得更加简单
前言
在Java开发中，日期和时间的处理是一个常见问题。为了简化这个过程，许多开发者会使用第三方工具包，如Hutool。Hutool是一个Java工具包，提供了许多实用的功能，其中之一就是日期处理。日期时间工具类是Hutool的核心包之一，提供针对JDK中Date和Calendar对象的封装，封装对象如下：
| 封装对象 | 说明 |
|---|---|
| DateUtil | 针对日期时间操作提供一系列静态方法 |
| DateTime | 提供类似于Joda-Time中日期时间对象的封装，继承自Date类，并提供更加丰富的对象方法。 |
| FastDateFormat | 提供线程安全的针对Date对象的格式化和日期字符串解析支持。 |
| DateBetween | 计算两个时间间隔的类，除了通过构造新对象使用外，相关操作也已封装在DateUtil和DateTime的相关方法中。 |
| TimeInterval | 一个简单的计时器类，常用于计算某段代码的执行时间，提供包括毫秒、秒、分、时、天、周等各种单位的花费时长计算。 |
| DatePattern | 提供常用的日期格式化模式，包括String类型和FastDateFormat两种类型。 |
| Quarter | 季度枚举 |
| Month | 月份枚举 |
| Week | 周枚举 |
| DateUnit | 日期时间单位，表示某个时间单位对应的毫秒数，常用于计算时间差。 |
一、概述
1.1 工具简介
Hutool 的 DateUtil 工具类是 Hutool 工具库中用于日期和时间处理的核心类之一，提供了许多静态方法，用于方便地处理常见的日期和时间操作。考虑到 Java 本身对日期时间的支持有限，并且 Date 和 Calendar 对象的并存导致各种方法使用混乱和复杂，故使用此工具类做了封装。这其中的封装主要是日期和字符串之间的转换，以及提供对日期的定位。
1.2 引入依赖
在使用Hutool工具之前，我们需要将Hutool添加到项目的依赖中。如果使用Maven构建项目，可以在 pom.xml 文件中添加以下依赖：
<!-- https://mvnrepository.com/artifact/cn.hutool/hutool-all -->
<dependency><groupId>cn.hutool</groupId><artifactId>hutool-all</artifactId><version>${hutool.version}</version>
</dependency>
Hutool-all 是一个 Hutool 的集成打包产品，由于考虑到“懒人”用户及分不清各个模块作用的用户，“无脑”引入 hutool-all 模块是快速开始和深入应用的最佳方式。如果你想像 SpringBoot 一样引入 Hutool，再由子模块决定用到哪些模块，你可以在父模块中加入：
<dependencyManagement><dependencies><dependency><groupId>cn.hutool</groupId><artifactId>hutool-bom</artifactId><version>${hutool.version}</version><type>pom</type><!-- 注意这里是import --><scope>import</scope></dependency></dependencies>
</dependencyManagement>
然后再在子模块中就可以引入自己需要的模块了：
<dependencies><dependency><groupId>cn.hutool</groupId><artifactId>hutool-core</artifactId></dependency>
</dependencies>
二、基本使用示例
2.1 计算生日
| 方法 | 部分参数 | 作用 |
|---|---|---|
| age(Date birthday, Date dateToCompare) | birthday：生日 dateToCompare：需要对比的日期 | 计算相对于dateToCompare的年龄，常用于计算指定生日在某年的年龄 |
| ageOfNow(String birthDay) | birthDay:生日，标准日期字符串 | 生日转为年龄，计算法定年龄 |
| ageOfNow(Date birthDay) | birthDay:生日 | 生日转为年龄，计算法定年龄 |
| getChineseZodiac(int year) | 计算生肖，只计算1900年后出生的人 | |
| getZodiac(int month, int day) | 通过生日计算星座 |
2.2 获取时间属性
2.2.1 获取当前时间
Hutool 提供了多种方式获取当前时间，例如当前时间戳、当前日期字符串等等。
| 方法 | 部分参数 | 作用 |
|---|---|---|
| DateTime date() | 将当前时间转换为DateTime对象 | |
| DateTime date(Calendar calendar) | 根据已有 Calendar 转换为 DateTime对象 | |
| DateTime dateSecond() | 当前时间，转换 DateTime 对象，忽略毫秒部分 | |
| String now() | 当前时间，格式 yyyy-MM-dd HH:mm:ss | |
| String today() | 当前日期，格式 yyyy-MM-dd | |
| long current() | 当前时间的时间戳 | |
| long currentSeconds() | 当前时间的时间戳（秒） |
2.2.2 获取当前时间属性
| 方法 | 部分参数 | 作用 |
|---|---|---|
| int getLastDayOfMonth(Date date) | 获得本月的最后一天 | |
| int thisDayOfMonth() | 当前日期所在月份的第几周 | |
| int thisDayOfWeek() | 当前日期是星期几 | |
| int thisHour(boolean is24HourClock) | is24HourClock - 是否24小时制 | 当前日期的小时数部分 |
| int thisMinute() | 当前日期的分钟数部分 | |
| int thisMillisecond() | 当前日期的毫秒数部分 | |
| int thisMonth() | 当前月份，从0开始计数 | |
| int thisSecond() | 当前日期的秒数部分 | |
| int thisWeekOfMonth() | 当前日期所在月份的第几周 | |
| int thisWeekOfYear() | 当前日期所在年份的第几周 | |
| thisYear | 今年 |
// 当前时间
Date date = DateUtil.date();
System.out.println(date);// Calendar转Date
System.out.println(DateUtil.date(Calendar.getInstance()));// 时间戳转Date
System.out.println(DateUtil.date(System.currentTimeMillis()));// 当前时间字符串，格式：yyyy-MM-dd HH:mm:ss
System.out.println(DateUtil.now());// 当前日期字符串，格式：yyyy-MM-dd
System.out.println(DateUtil.today());
2.2.3 获取时间部分属性
| 方法 | 部分参数 | 作用 |
|---|---|---|
| DateTime date() | 将当前时间转换为DateTime对象 | |
| int year(Date date) | 获得年的部分 | |
| int month(Date date) | 获得月份，从0开始计数 | |
| int hour(Date date, boolean is24HourClock) | is24HourClock - 是否24小时制 | 获得指定日期的小时数部分 |
| int minute(Date date) | 获得指定日期的分钟数部分 | |
| int second(Date date) | 获得指定日期的秒数部分 | |
| int millisecond(Date date) | 获得指定日期的毫秒数部分 |
Date date = DateUtil.date();// 获得年的部分
int year = DateUtil.year(date);// 获得月份，从0开始计数
int month = DateUtil.month(date);// 获得月份枚举
DateUtil.monthEnum(date).getValue();
2.2.4 获取指定时间属性
| 方法 | 部分参数 | 作用 |
|---|---|---|
| int dayOfMonth(Date date) | 获得指定日期是这个日期所在月份的第几天 | |
| int dayOfWeek(Date date) | 获得指定日期是星期几，1表示周日，2表示周一 | |
| dayOfWeekEnum | 获得指定日期是星期几 | |
| int dayOfYear(Date date) | 获得指定日期是这个日期所在年的第几天 | |
| int quarter(Date date) | 获得指定日期所属季度，从1开始计数 | |
| String yearAndQuarter(Date date) | 获得指定日期年份和季节。例如[20131]表示2013年第一季度 | |
| int lengthOfMonth(int month,boolean isLeapYear) | isLeapYear - 是否闰年 | 获得指定月份的总天数 |
| int lengthOfYear(int year) | 获得指定年份的总天数 | |
| int millisecond(Date date) | 获得指定日期的毫秒数部分 | |
| int minute(Date date) | 获得指定日期的分钟数部分 |
2.3 获取某时间的开始、结束日期
有的时候我们需要获得每天的开始时间、结束时间，每月的开始和结束时间等等，DateUtil也提供了相关方法：
| 方法 | 部分参数 | 作用 |
|---|---|---|
| DateTime beginOfYear(Date date) | 获取某年的开始时间 | |
| DateTime endOfYear(Date date) | 获取某年的结束时间 | |
| DateTime beginOfQuarter(Date date) | 获取某季度的开始时间 | |
| DateTime endOfQuarter(Date date) | 获取某季度的结束时间 | |
| DateTime beginOfMonth(Date date) | 获取某月的开始时间 | |
| DateTime endOfMonth(Date date) | 获取某月的结束时间 | |
| DateTime beginOfWeek(Date date) | 获取某周的开始时间，周一为一周的开始 | |
| beginOfWeek(Date date,boolean isMondayAsFirstDay) | isMondayAsFirstDay:是否周一做为一周的第一天 | 获取某周的开始时间 |
| DateTime endOfWeek(Date date) | 获取某周的结束时间，周日为一周的结束 | |
| endOfWeek(Date date,boolean isSundayAsLastDay) | isSundayAsLastDay:是否周日做为一周的最后一天 | 获取某周的结束时间 |
| DateTime beginOfDay(Date date) | 获取某天的开始时间 | |
| DateTime endOfDay(Date date) | 获取某天的结束时间 | |
| beginOfHour(Date date) | 获取某小时的开始时间 | |
| endOfHour(Date date) | 获取某小时的结束时间 | |
| beginOfMinute(Date date) | 获取某分钟的开始时间 | |
| endOfMinute(Date date) | 获取某分钟的结束时间 | |
| beginOfSecond(Date date) | ||
| DateTime beginOfSecond(Date date) | 获取秒级别的开始时间，即毫秒部分设置为0 |
String dateStr = "2022-11-09 22:33:23";
Date date = DateUtil.parse(dateStr);// 一天的开始，结果：2022-11-09 00:00:00
Date beginOfDay = DateUtil.beginOfDay(date);// 一天的结束，结果：2022-11-09 23:59:59
Date endOfDay = DateUtil.endOfDay(date);// 获取秒级别的开始时间，即毫秒部分设置为0
System.out.println(DateUtil.beginOfSecond(date));// 获取某周的开始时间
System.out.println(DateUtil.beginOfWeek(date));
2.4 日期时间计算
Hutool 提供了丰富的日期计算方法，例如获取某天的开始时间、结束时间，计算两个日期之间的天数、小时等等。
2.4.1 日期时间比较
| 方法 | 部分参数 | 作用 |
|---|---|---|
| int compare(Date date1,Date date2) | 日期比较。 如果date1 < date2，小于0，date1==date2返回0，date1 > date2 大于0 | |
| boolean isIn(Date date,Date beginDate, Date endDate) | 当前日期是否在日期指定范围内 | |
| boolean isSameDay(Date date1,Date date2) | 比较两个日期是否为同一天 | |
| boolean isSameMonth(Date date1,Date date2) | 比较两个日期是否为同一月 | |
| boolean isSameTime(Date date1,Date date2) | 比较两个日期的时间戳是否相同 | |
| boolean isSameWeek(Date date1,Date date2) | 比较两个日期是否为同一周 |
2.4.2 日期时间偏移计算
日期或时间的偏移指针对某个日期增加或减少分、小时、天等等，达到日期变更的目的。Hutool也针对其做了大量封装：
| 方法 | 部分参数 | 作用 |
|---|---|---|
| offset(Date date, DateField dateField, int offset) | offset - 偏移量，正数为向后偏移，负数为向前偏移 | 获取指定日期偏移指定时间后的时间， 生成的偏移日期不影响原日期 |
| offsetDay(Date date, int offset) | 偏移天 | |
| offsetHour(Date date, int offset) | 偏移小时 | |
| offsetMillisecond(Date date, int offset) | 偏移毫秒数 | |
| offsetMinute(Date date, int offset) | 偏移分钟 | |
| offsetMonth(Date date, int offset) | 偏移月 | |
| offsetSecond(Date date, int offset) | 偏移秒数 | |
| offsetWeek(Date date, int offset) | 偏移周 |
tring dateStr = "2022-11-09 22:33:23";
Date date = DateUtil.parse(dateStr);//结果：2022-11-11 22:33:23
Date newDate = DateUtil.offset(date, DateField.DAY_OF_MONTH, 2);//常用偏移，结果：2023-11-12 22:33:23
DateTime newDate2 = DateUtil.offsetDay(date, 3);//常用偏移，结果：22023-11-09 19:33:23
DateTime newDate3 = DateUtil.offsetHour(date, -3);
针对当前时间，提供了简化的偏移方法（例如昨天、上周、上个月等）：
| 方法 | 部分参数 | 作用 |
|---|---|---|
| yesterday | 昨天 | |
| tomorrow | 明天 | |
| lastWeek | 上周 | |
| nextWeek | 下周 | |
| lastMonth | 上个月 | |
| nextMonth | 下个月 |
2.4.3 计算两个时间之差
有时候我们需要计算两个日期之间的时间差（相差天数、相差小时数等等），Hutool将此类方法封装为between方法：
| 方法 | 部分参数 | 作用 |
|---|---|---|
| between(Date beginDate, Date endDate, DateUnit unit) | beginDate：起始日期 endDate：结束日期 unit：相差的单位 | 判断两个日期相差的时长，只保留绝对值 |
| between(Date beginDate, Date endDate, DateUnit unit, boolean isAbs) | beginDate:起始日期 endDate:结束日期 unit:相差的单位 | 判断两个日期相差的时长 |
| betweenMs(Date beginDate, Date endDate) | beginDate:起始日期 endDate:结束日期 | 判断两个日期相差的毫秒数 |
| betweenDay(Date beginDate, Date endDate, boolean isReset) | beginDate:起始日期 endDate:结束日期 isReset:是否重置时间为起始时间 | 判断两个日期相差的天数。 |
| betweenWeek(Date beginDate, Date endDate, boolean isReset) | beginDate:开始时间 endDate:结束时间 isReset:是否重置时间为起始时间 | 计算指定时间区间内的周数 |
| betweenMonth | 计算两个日期相差月数。 | |
| betweenYear | 计算两个日期相差年数。 |
String dateStr1 = "2022-11-09 22:33:23";
Date date1 = DateUtil.parse(dateStr1);String dateStr2 = "2022-12-09 23:33:23";
Date date2 = DateUtil.parse(dateStr2);// 相差一个月，31天
long betweenDay = DateUtil.between(date1, date2, DateUnit.DAY);Date startDate=DateUtil.parse("2021-04-20 02:00:00");
Date endDate=DateUtil.parse("2021-04-21 05:10:00");
long week=DateUtil.between(startDate,endDate,DateUnit.WEEK); //相差周数
long day=DateUtil.between(startDate,endDate,DateUnit.DAY); //相差天数
long hour=DateUtil.between(startDate,endDate,DateUnit.HOUR); //相差小时数
long minute=DateUtil.between(startDate,endDate,DateUnit.MINUTE);//相差分钟数
long second=DateUtil.between(startDate,endDate,DateUnit.SECOND);//相差秒数
long millis=DateUtil.between(startDate,endDate,DateUnit.MS); //相差毫秒数
2.5 日期解析
| 方法 | 部分参数 | 作用 |
|---|---|---|
| parse(CharSequence dateCharSequence) | 将日期字符串转换为 Date 对象 | |
| parse(CharSequence dateStr, DateFormat dateFormat) | dateStr：Date字符串 dateFormat：格式化器 SimpleDateFormat | |
| parse(CharSequence dateStr, DateParser parser) | dateStr：Date字符串 parser：格式化器 FastDateFormat | |
| parse(CharSequence dateStr,DateParser parser,boolean lenient) | dateStr：Date字符串 parser：格式化器 FastDateFormat lenient：是否宽容模式 | |
| parse(CharSequence dateStr, DateTimeFormatter formatter) | dateStr：Date字符串 formatter：格式化器 DateTimeFormatter | |
| parse(CharSequence dateStr, String format) | dateStr：特定格式的日期 format：格式，例如yyyy-MM-dd | 将特定格式的日期转换为Date对象 |
| parse(CharSequence dateStr, String format, Locale locale) | dateStr：特定格式的日期 format：格式，例如yyyy-MM-dd locale：区域信息 | 将特定格式的日期转换为Date对象 |
| parse(String str, String… parsePatterns) | 通过给定的日期格式解析日期时间字符串 | |
| parseDate(CharSequence dateCharSequence) | 解析日期字符串 | |
| parseDateTime(CharSequence dateCharSequence) | 解析日期时间字符串 | |
| parseLocalDateTime(CharSequence dateCharSequence) | 构建LocalDateTime对象 | |
| parseTime(CharSequence dateCharSequence) | 解析时间，格式HH:mm:ss， | |
| parseTimeToday(CharSequence dateCharSequence) | 解析时间，格式HH:mm或HH:mm:ss | |
| parseUTC(String utcString) | 解析UTC时间 |
String dateStr = "2022-11-09";
Date date = DateUtil.parse(dateStr);Date date = DateUtil.parse(dateStr, "yyyy-MM-dd");
2.6 日期格式化
2.6.1 格式化日期时间
Hutool 对日期进行了非常详细的封装，可以有效避免我们自己的日期格式出现混乱的情况。而且 hutool 为我们提供了多个日期格式解析，转换成 yyyy-MM-dd HH:mm:ss 格式，同时我们可以引用这些日期格式：
| 方法 | 部分参数 | 作用 |
|---|---|---|
| format(Date date, DateFormat format) | 将 Date 对象格式化为指定的字符串 | |
| format(Date date, String format) | 根据特定格式格式化日期 | |
| formatChineseDate(Date date,boolean isUppercase,boolean withTime) | date - 被格式化的日期 isUppercase - 是否采用大写形式 withTime - 是否包含时间部分 | 格式化为中文日期格式。 |
| formatDate(Date date) | 格式化日期部分（不包括时间） | |
| formatDateTime(Date date) | 格式化日期时间 | |
| formatHttpDate(Date date) | 格式化为Http的标准日期格式 | |
| formatLocalDateTime | 格式化日期时间 | |
| formatTime(Date date) | 格式化时间 |
String dateStr = "2023-11-09";
Date date = DateUtil.parse(dateStr);//结果 2017/03/01
String format = DateUtil.format(date, "yyyy/MM/dd");//常用格式的格式化，结果：2023-11-09
String formatDate = DateUtil.formatDate(date);//结果：2023-11-09 00:00:00
String formatDateTime = DateUtil.formatDateTime(date);//结果：00:00:00
String formatTime = DateUtil.formatTime(date);
2.6.2 格式化时间差
有时候我们希望看到易读的时间差，比如XX天XX小时XX分XX秒，此时使用DateUtil.formatBetween方法：
| 方法 | 部分参数 | 作用 |
|---|---|---|
| formatBetween(Date beginDate, Date endDate) | 格式化日期间隔输出，精确到毫秒 | |
| formatBetween(Date beginDate, Date endDate, BetweenFormatter.Level level) | 格式化日期间隔输出 | |
| formatBetween(long betweenMs) | 格式化日期间隔输出，精确到毫秒 | |
| formatBetween(long betweenMs, BetweenFormatter.Level level) | 格式化日期间隔输出 |
【说明】BetweenFormatter 即格式化等级枚举，支持DAY（天）、HOUR（小时）、MILLISECOND（毫秒）、MINUTE（分钟）、SECOND（秒）等。
Date startDate=DateUtil.parse("2021-04-20 02:00:00");
Date endDate=DateUtil.parse("2021-04-21 05:10:00");//相差毫秒数
long millis=DateUtil.between(startDate,endDate,DateUnit.MS);
//相差1天(天)
String formatDay = DateUtil.formatBetween(millis, BetweenFormatter.Level.DAY);
//相差1天3小时(小时)
String formatHour = DateUtil.formatBetween(millis, BetweenFormatter.Level.HOUR);
//相差1天3小时10分(分钟)
String formatMinute = DateUtil.formatBetween(millis, BetweenFormatter.Level.MINUTE);
//相差1天3小时10分(秒)
String formatSecond = DateUtil.formatBetween(millis, BetweenFormatter.Level.SECOND);
//相差1天3小时10分(毫秒)
String formatMillis = DateUtil.formatBetween(millis, BetweenFormatter.Level.MILLISECOND);
2.7 其他
2.7.1 日期时间判断
Hutool 可以方便地判断日期是否在某个范围内、是否是周末等等。
| 方法 | 部分参数 | 作用 |
|---|---|---|
| boolean isAM(Date date) | 是否为上午 | |
| boolean isLastDayOfMonth | 是否为本月最后一天 | |
| boolean isLeapYear(int year) | 判断指定年份是否是闰年 | |
| boolean isOverlap(Date realStartTime,Date realEndTime,Date startTime,Date endTime) | 检查两个时间段是否有时间重叠 | |
| boolean isPM(Date date) | 是否为下午 | |
| boolean isWeekend(Date date) | date - 判定的日期Date | 是否为周末（周六或周日） |
// 定义时间范围
Date startDate = DateUtil.parse("2025-04-01");
Date endDate = DateUtil.parse("2025-04-30");// 需要判断的日期
Date date = DateUtil.parse("2025-04-18");
// 判断日期是否在范围内
boolean isInRange = DateUtil.isIn(date, startDate, endDate);
System.out.println("isInRange = " + isInRange);// 判断是否是周末
boolean isWeekend = DateUtil.isWeekend(date);
System.out.println("日期是否是周末：" + isWeekend);
2.7.2 时间计时
| 方法 | 部分参数 | 作用 |
|---|---|---|
| String secondToTime(int seconds) | 秒数转为时间格式(HH:mm:ss) | |
| long spendMs(long preTime) | 计时，常用于记录某段代码的执行时间，单位：毫秒 | |
| long spendNt(long preTime) | 计时，常用于记录某段代码的执行时间，单位：纳秒 | |
| timer() | 计算某个过程花费的时间，精确到毫秒 | |
| timer(boolean isNano) | isNano - 是否使用纳秒计数，false则使用毫秒 | 计算某个过程花费的时间，精确到毫秒 |
| int timeToSecond(String timeStr) | HH:mm:ss时间格式字符串转为秒数 |
三、总结
通过学习 Hutool 工具库中的 DateUtil 工具类，我们可以方便地处理日期和时间相关的操作。它提供了许多实用的方法，可以简化我们在日常开发中的日期处理工作，提高开发效率，减少出错的可能性。而且 DateUtil 在实现上进行了性能优化，对常见的日期和时间操作进行了高效处理，同时尽量避免了线程安全问题。
Hotool 不仅仅只有这一种工具类，还包含了其他许多工具类。在这里我作为一名Hutool的用户，我感谢Hutool的创作者和维护者们为我们带来如此强大便捷的工具库，希望Hutool功能越来越完善，为我们的开发工作带来更多的便利。同时也祝愿所有开发者没有BUG困扰，能够愉快地编写出高效、功能完善的程序。
