日期时间工具 - DateUtil

1. 背景介绍

在 Java 中，日期和时间操作一直是一个复杂的领域，尤其是 Java 原生的 Date 和 Calendar 类的设计，使得日期操作繁琐且容易出错。为了解决这些问题，Hutool 提供了一个功能强大的日期时间工具类——DateUtil，它简化了日期与时间的操作，提供了丰富的功能，例如日期与字符串之间的转换、日期的加减操作、日期的格式化等。

2. 日期时间的获取与转换

2.1 获取当前日期时间

DateUtil 提供了多个方法用于获取当前时间，涵盖了 Date、Calendar、时间戳等形式。

import cn.hutool.core.date.DateUtil;

public class DateUtilExample {
    public static void main(String[] args) {
        // 获取当前时间，返回 Date 对象
        Date date = DateUtil.date();
        System.out.println(date);

        // 使用 Calendar 获取当前时间
        Date date2 = DateUtil.date(Calendar.getInstance());
        System.out.println(date2);

        // 使用系统时间戳获取当前时间
        Date date3 = DateUtil.date(System.currentTimeMillis());
        System.out.println(date3);

        // 获取当前时间的字符串表示，格式为：yyyy-MM-dd HH:mm:ss
        String now = DateUtil.now();
        System.out.println(now);

        // 获取当前日期的字符串表示，格式为：yyyy-MM-dd
        String today = DateUtil.today();
        System.out.println(today);
    }
}

API 说明

• date()：获取当前时间，返回 Date 对象。

  • 作用：提供当前时间的 Date 对象，类似于 new Date()。
  • 返回值：当前时间的 Date 对象。

• date(Calendar calendar)：通过 Calendar 获取时间。

  • 作用：将 Calendar 对象转换为 Date。
  • 参数：
    • calendar：Calendar 对象。
  • 返回值：转换后的 Date 对象。

• date(long millis)：通过时间戳获取时间。

  • 作用：将时间戳转换为 Date。
  • 参数：
    • millis：时间戳，单位为毫秒。
  • 返回值：转换后的 Date 对象。

• now()：获取当前时间的字符串表示，格式为 yyyy-MM-dd HH:mm:ss。

  • 作用：获取当前时间的标准格式字符串。
  • 返回值：当前时间的字符串表示。

• today()：获取当前日期的字符串表示，格式为 yyyy-MM-dd。

  • 作用：获取当前日期的标准格式字符串。
  • 返回值：当前日期的字符串表示。

实际开发场景

在实际开发中，经常需要获取当前时间进行日志记录、生成时间戳等操作。DateUtil 的这些方法可以简化时间获取操作，特别是在生成日志文件名或记录操作时间时非常有用。

public class Application {
    public static void main(String[] args) {
        // 获取当前时间并记录操作
        String operationTime = DateUtil.now();
        System.out.println("操作时间：" + operationTime); // 输出格式：2024-08-20 10:22:35
    }
}

---

2.2 字符串与日期对象之间的转换

DateUtil.parse() 方法可以将日期字符串转换为 Date 对象。它支持多种日期格式，可以自动识别常用格式。

自动识别常用格式：

• yyyy-MM-dd HH:mm:ss
• yyyy/MM/dd HH:mm:ss
• yyyy.MM.dd HH:mm:ss
• yyyy年MM月dd日 HH时mm分ss秒
• yyyy-MM-dd
• yyyy/MM/dd
• yyyy.MM.dd
• HH:mm:ss
• HH时mm分ss秒
• yyyy-MM-dd HH:mm
• yyyy-MM-dd HH:mm:ss.SSS
• yyyyMMddHHmmss
• yyyyMMddHHmmssSSS
• yyyyMMdd
• EEE, dd MMM yyyy HH:mm:ss z
• EEE MMM dd HH:mm:ss zzz yyyy
• yyyy-MM-dd'T'HH:mm:ss'Z'
• yyyy-MM-dd'T'HH:mm:ss.SSS'Z'
• yyyy-MM-dd'T'HH:mm:ssZ
• yyyy-MM-dd'T'HH:mm:ss.SSSZ

示例代码

import cn.hutool.core.date.DateUtil;

public class DateUtilExample {
    public static void main(String[] args) {
        // 将字符串 "2017-03-01" 转换为 Date 对象
        String dateStr = "2017-03-01";
        Date date = DateUtil.parse(dateStr);
        System.out.println(date); // 输出：Wed Mar 01 00:00:00 GMT 2017

        // 使用自定义格式 "yyyy-MM-dd" 转换字符串为 Date 对象
        Date customDate = DateUtil.parse(dateStr, "yyyy-MM-dd");
        System.out.println(customDate); // 输出：Wed Mar 01 00:00:00 GMT 2017
    }
}

API 说明

• parse(String dateStr)：自动识别格式并将字符串转换为 Date。

  • 作用：解析常见日期格式的字符串，返回对应的 Date 对象。
  • 参数：
    • dateStr：日期字符串。
  • 返回值：解析后的 Date 对象。

• parse(String dateStr, String format)：使用指定格式解析日期字符串。

  • 作用：根据指定格式解析日期字符串，返回对应的 Date 对象。
  • 参数：
    • dateStr：日期字符串。
    • format：日期格式字符串，例如 yyyy-MM-dd。
  • 返回值：解析后的 Date 对象。

实际开发场景

在处理用户输入的日期或从外部接口获取的日期字符串时，通常需要将其转换为 Date 对象，便于后续操作。DateUtil.parse() 可以自动识别多种常见格式，非常适合处理不同来源的日期字符串。

public class Application {
    public static void main(String[] args) {
        String userInput = "2024-08-20";
        Date userDate = DateUtil.parse(userInput);
        System.out.println("用户输入的日期：" + userDate); // 输出：Tue Aug 20 00:00:00 GMT 2024
    }
}

---

3. 日期时间格式化

将日期对象格式化为字符串是日期操作中的常见需求。DateUtil 提供了多种格式化方法，支持常见日期格式。

示例代码

import cn.hutool.core.date.DateUtil;

public class DateUtilExample {
    public static void main(String[] args) {
        Date date = DateUtil.date();

        // 将日期对象格式化为字符串，格式为：yyyy/MM/dd
        String formattedDate = DateUtil.format(date, "yyyy/MM/dd");
        System.out.println(formattedDate); // 输出格式：2024/08/20

        // 使用常用格式，将日期对象格式化为字符串，格式为：yyyy-MM-dd
        String formatDate = DateUtil.formatDate(date);
        System.out.println(formatDate); // 输出格式：2024-08-20

        // 将日期对象格式化为日期时间字符串，格式为：yyyy-MM-dd HH:mm:ss
        String formatDateTime = DateUtil.formatDateTime(date);
        System.out.println(formatDateTime); // 输出格式：2024-08-20 10:22:35

        // 将日期对象格式化为时间字符串，格式为：HH:mm:ss
        String formatTime = DateUtil.formatTime(date);
        System.out.println(formatTime); // 输出格式：10:22:35
    }
}

API 说明

• format(Date date, String format)：将日期对象格式化为指定格式的字符串。

  • 作用：根据指定的格式，将 Date 对象转换为字符串。
  • 参数：
    • date：日期对象。
    • format：格式字符串，例如 yyyy/MM/dd。
  • 返回值：格式化后的日期字符串。

• formatDate(Date date)：使用常见的 yyyy-MM-dd 格式格式化日期。

  • 作用：将 Date 对象格式化为 yyyy-MM-dd 格式的字符串。
  • 参数：
    • date：日期对象。
  • 返回值：格式化后的日期字符串。

• formatDateTime(Date date)：使用常见的 yyyy-MM-dd HH:mm:ss 格式格式化日期时间。

  • 作用：将 Date 对象格式化为 yyyy-MM-dd HH:mm:ss 格式的字符串。
  • 参数：
    • date：日期对象。
  • 返回值：格式化后的日期时间字符串。

• formatTime(Date date)：使用常见的 HH:mm:ss 格式格式化时间。

  • 作用：将 Date 对象格式化为 HH:mm:ss 格式的时间字符串。
  • 参数：
    • date：日期对象。
  • 返回值：格式化后的时间字符串。

实际开发场景

日期的格式化操作广泛应用于日志记录、前端显示、数据导出等场景。例如，在报表生成中，我们经常需要将日期格式化为指定格式，以便用户阅读。

public class Application {


    public static void main(String[] args) {
        Date currentDate = DateUtil.date();
        String reportDate = DateUtil.format(currentDate, "yyyy/MM/dd");
        System.out.println("报表生成日期：" + reportDate); // 输出：报表生成日期：2024/08/20
    }
}

---

4. 获取 Date 对象的某个部分

在实际开发中，我们常常需要获取日期对象的某些特定部分（如年、月、日）。DateUtil 提供了便捷的方法来获取这些信息。

示例代码

import cn.hutool.core.date.DateUtil;
import cn.hutool.core.date.Month;

public class DateUtilExample {
    public static void main(String[] args) {
        Date date = DateUtil.date();

        // 获取年份
        int year = DateUtil.year(date);
        System.out.println("年份：" + year); // 输出：2024

        // 获取月份（从0开始计数，0表示1月）
        int month = DateUtil.month(date);
        System.out.println("月份：" + month); // 输出：7（表示8月）

        // 获取月份的枚举
        Month monthEnum = DateUtil.monthEnum(date);
        System.out.println("月份枚举：" + monthEnum); // 输出：AUGUST
    }
}

API 说明

• year(Date date)：获取年份。

  • 作用：从日期对象中提取年份。
  • 参数：
    • date：日期对象。
  • 返回值：年份（整型）。

• month(Date date)：获取月份。

  • 作用：从日期对象中提取月份，返回的月份从 0 开始计数（0 表示 1 月）。
  • 参数：
    • date：日期对象。
  • 返回值：月份（整型，0 表示 1 月）。

• monthEnum(Date date)：获取月份的枚举表示。

  • 作用：从日期对象中提取月份并返回 Month 枚举。
  • 参数：
    • date：日期对象。
  • 返回值：月份的 Month 枚举。

实际开发场景

获取日期的年、月、日信息在生日计算、日历应用等场景中非常常见。例如，在判断某人是否成年时，可以通过提取年份进行计算。

public class Application {
    public static void main(String[] args) {
        Date birthDate = DateUtil.parse("2005-08-20");
        int birthYear = DateUtil.year(birthDate);
        int currentYear = DateUtil.year(DateUtil.date());
        
        if (currentYear - birthYear >= 18) {
            System.out.println("已成年");
        } else {
            System.out.println("未成年");
        }
    }
}

---

5. 开始时间与结束时间的获取

在实际开发中，经常需要获取某个日期的开始时间或结束时间，例如统计一天的数据、获取某个月的完整时间范围等。DateUtil 提供了这些便捷的方法。

示例代码

import cn.hutool.core.date.DateUtil;

public class DateUtilExample {
    public static void main(String[] args) {
        String dateStr = "2017-03-01 22:33:23";
        Date date = DateUtil.parse(dateStr);

        // 获取一天的开始时间，结果：2017-03-01 00:00:00
        Date beginOfDay = DateUtil.beginOfDay(date);
        System.out.println(beginOfDay);

        // 获取一天的结束时间，结果：2017-03-01 23:59:59
        Date endOfDay = DateUtil.endOfDay(date);
        System.out.println(endOfDay);
    }
}

API 说明

• beginOfDay(Date date)：获取某一天的开始时间。

  • 作用：将日期时间调整为当天的 00:00:00。
  • 参数：
    • date：日期对象。
  • 返回值：调整后的日期对象。

• endOfDay(Date date)：获取某一天的结束时间。

  • 作用：将日期时间调整为当天的 23:59:59。
  • 参数：
    • date：日期对象。
  • 返回值：调整后的日期对象。

实际开发场景

获取一天或一个月的开始和结束时间通常用于数据统计、筛选和过滤。例如，在统计用户日活跃量时，可以使用当天的开始时间和结束时间作为查询条件。

示例应用

public class Application {
    public static void main(String[] args) {
        Date currentDate = DateUtil.date();
        Date startOfDay = DateUtil.beginOfDay(currentDate);
        Date endOfDay = DateUtil.endOfDay(currentDate);

        // 假设我们进行一天的数据统计
        System.out.println("统计开始时间：" + DateUtil.formatDateTime(startOfDay));
        System.out.println("统计结束时间：" + DateUtil.formatDateTime(endOfDay));
    }
}

---

6. 日期时间的偏移

日期或时间的偏移是指在某个日期上增加或减少一定的时间单位，例如天、小时等。DateUtil 提供了许多便捷的方法来实现这一功能。

示例代码

import cn.hutool.core.date.DateUtil;
import cn.hutool.core.date.DateField;
import cn.hutool.core.date.DateTime;

public class DateUtilExample {
    public static void main(String[] args) {
        String dateStr = "2017-03-01 22:33:23";
        Date date = DateUtil.parse(dateStr);

        // 日期偏移，结果：2017-03-03 22:33:23（向后偏移2天）
        Date newDate = DateUtil.offset(date, DateField.DAY_OF_MONTH, 2);
        System.out.println(newDate);

        // 常用偏移，结果：2017-03-04 22:33:23（向后偏移3天）
        DateTime newDate2 = DateUtil.offsetDay(date, 3);
        System.out.println(newDate2);

        // 常用偏移，结果：2017-03-01 19:33:23（向前偏移3小时）
        DateTime newDate3 = DateUtil.offsetHour(date, -3);
        System.out.println(newDate3);

        // 获取昨天的日期
        Date yesterday = DateUtil.yesterday();
        System.out.println("昨天的日期：" + DateUtil.formatDate(yesterday));

        // 获取明天的日期
        Date tomorrow = DateUtil.tomorrow();
        System.out.println("明天的日期：" + DateUtil.formatDate(tomorrow));
    }
}

API 说明

• offset(Date date, DateField field, int offset)：根据指定的时间字段和偏移量进行日期偏移。

  • 作用：在指定日期上根据时间字段进行加减操作，例如偏移天数、小时数等。
  • 参数：
    • date：日期对象。
    • field：时间字段，例如 DateField.DAY_OF_MONTH。
    • offset：偏移量，正数为向后偏移，负数为向前偏移。
  • 返回值：偏移后的日期对象。

• offsetDay(Date date, int offset)：按天数进行偏移。

  • 作用：在指定日期上偏移指定的天数。
  • 参数：
    • date：日期对象。
    • offset：天数偏移量。
  • 返回值：偏移后的日期对象。

• offsetHour(Date date, int offset)：按小时数进行偏移。

  • 作用：在指定日期上偏移指定的小时数。
  • 参数：
    • date：日期对象。
    • offset：小时偏移量。
  • 返回值：偏移后的日期对象。

• yesterday()：获取昨天的日期。

  • 作用：返回昨天的日期对象。
  • 返回值：昨天的日期对象。

• tomorrow()：获取明天的日期。

  • 作用：返回明天的日期对象。
  • 返回值：明天的日期对象。

• lastWeek()：获取上周的日期。

  • 作用：返回当前时间的上周同一天的日期对象。
  • 返回值：上周同一天的日期对象。

• nextWeek()：获取下周的日期。

  • 作用：返回当前时间的下周同一天的日期对象。
  • 返回值：下周同一天的日期对象。

• lastMonth()：获取上个月的日期。

  • 作用：返回当前时间的上个月同一天的日期对象。
  • 返回值：上个月同一天的日期对象。

• nextMonth()：获取下个月的日期。

  • 作用：返回当前时间的下个月同一天的日期对象。
  • 返回值：下个月同一天的日期对象。

实际开发场景

日期偏移操作在统计、日程管理、定时任务等场景中非常常见。无论是计算某个事件的到期时间，还是设置提醒时间，日期偏移都是必要的操作。

public class Application {
    public static void main(String[] args) {
        DateTime now = DateUtil.date();
        
        // 获取上个月的同一天
        DateTime lastMonth = DateUtil.lastMonth();
        System.out.println("上个月的同一天：" + DateUtil.formatDate(lastMonth)); // 输出上个月的日期
        
        // 向后偏移7天（计算一周后的日期）
        DateTime nextWeek = DateUtil.offsetDay(now, 7);
        System.out.println("一周后的日期：" + DateUtil.formatDate(nextWeek)); // 输出一周后的日期
    }
}

---

7. 日期时间差的计算

在实际应用中，经常需要计算两个日期之间的时间差。DateUtil.between() 方法可以计算两个日期之间的差异，支持秒、分钟、小时、天等多种时间单位。

示例代码

import cn.hutool.core.date.DateUtil;
import cn.hutool.core.date.DateUnit;

public class DateUtilExample {
    public static void main(String[] args) {
        String dateStr1 = "2024-08-01 22:33:23";
        Date date1 = DateUtil.parse(dateStr1);

        String dateStr2 = "2024-08-20 23:33:23";
        Date date2 = DateUtil.parse(dateStr2);

        // 计算两个日期之间的天数差，结果：19天
        long betweenDay = DateUtil.between(date1, date2, DateUnit.DAY);
        System.out.println("日期差：" + betweenDay + " 天");
    }
}

API 说明

• between(Date startDate, Date endDate, DateUnit unit)：计算两个日期之间的差异。
  • 作用：计算两个日期之间的时间差，支持多种时间单位。
  • 参数：
    • startDate：起始日期。
    • endDate：结束日期。
    • unit：时间单位，如 DateUnit.DAY、DateUnit.HOUR 等。
  • 返回值：时间差，单位由 unit 参数决定。

实际开发场景

计算日期差在考勤管理、项目进度监控、时间统计等场景中非常常见。例如，计算用户在某个平台上的注册天数，或是计算项目截止日期与当前日期的天数差。

public class Application {
    public static void main(String[] args) {
        Date startDate = DateUtil.parse("2024-08-01");
        Date endDate = DateUtil.date();

        // 计算项目进行的天数
        long projectDays = DateUtil.between(startDate, endDate, DateUnit.DAY);
        System.out.println("项目进行时间：" + projectDays + " 天");
    }
}

---

8. 格式化时间差

有时我们希望看到更易读的时间差表达，例如“XX天XX小时XX分XX秒”。DateUtil.formatBetween() 提供了这种功能，可以将时间差格式化为友好的字符串表示。

示例代码

import cn.hutool.core.date.DateUtil;
import cn.hutool.core.date.BetweenFormatter;

public class DateUtilExample {
    public static void main(String[] args) {
        Date date1 = DateUtil.parse("2024-08-01 22:33:23");
        Date date2 = DateUtil.parse("2024-08-20 23:33:23");

        // 计算两个日期之间的时间差（以毫秒为单位）
        long betweenMillis = DateUtil.between(date1, date2, DateUnit.MS);

        // 格式化时间差，精确到分钟，结果："19天1小时"
        String formatBetween = DateUtil.formatBetween(betweenMillis, BetweenFormatter.Level.MINUTE);
        System.out.println("时间差：" + formatBetween);
    }
}

API 说明

• formatBetween(long betweenMillis, BetweenFormatter.Level level)：格式化时间差。
  • 作用：将时间差格式化为易读的字符串表示，支持精确到秒、分钟、小时等级别。
  • 参数：
    • betweenMillis：时间差（以毫秒为单位）。
    • level：时间差格式化的精度级别，例如 Level.SECOND、Level.MINUTE 等。
  • 返回值：格式化后的时间差字符串。

实际开发场景

时间差的格式化通常用于用户界面显示。例如，在任务管理系统中，可以显示任务剩余时间；在电商平台中，可以显示倒计时活动的剩余时间。

public class Application {
    public static void main(String[] args) {
        Date startTime = DateUtil.parse("2024-08-01 22:33:23");
        Date endTime = DateUtil.date(); // 当前时间

        // 计算并格式化任务运行时间
        long taskDuration = DateUtil.between(startTime, endTime, DateUnit.MS);
        String durationStr = DateUtil.formatBetween(taskDuration, BetweenFormatter.Level.MINUTE);
        System.out.println("任务已运行：" + durationStr); // 输出格式："X天X小时X分"
    }
}

---

9. 星座与属相

DateUtil 提供了获取星座和属相的方法，适用于生日、生肖相关的场景。

示例代码

import cn.hutool.core.date.DateUtil;

public class DateUtilExample {
    public static void main(String[] args) {
        // 获取星座，结果："狮子座"
        String zodiac = DateUtil.getZodiac(8, 10);
        System.out.println("星座：" + zodiac);

        // 获取属相，结果："马"
        String chineseZodiac = DateUtil.getChineseZodiac(1990);
        System.out.println("属相：" + chineseZodiac);
    }
}

API 说明

• getZodiac(int month, int day)：获取星座。

  • 作用：根据生日中的月份和日期获取对应的星座。
  • 参数：
    • month：月份（1-12）。
    • day：日期（1-31）。
  • 返回值：星座字符串。

• getChineseZodiac(int year)：获取属相。

  • 作用：根据出生年份获取对应的生肖属相。
  • 参数：
    • year：年份（如 1990）。
  • 返回值：生肖字符串。

实际开发场景

星座与属相的获取在娱乐应用、个性化推荐等场景中应用广泛。例如，用户在填写个人信息时，可以自动计算其星座或属相，并进行相关个性化推荐。

public class Application {
    public static void main(String[] args) {
        int birthYear = 1994;
        String chineseZodiac = DateUtil.getChineseZodiac(birthYear);
        System.out.println("出生年份属相：" + chineseZodiac); // 输出："狗"
    }
}

---

10. 日期范围生成

DateUtil 提供了日期范围生成器，可以用于生成特定范围的日期列表，常用于报表、日历等场景。

示例代码

import cn.hutool.core.date.DateUtil;
import cn.hutool.core.date.DateRange;
import cn.hutool.core.date.DateField;
import cn.hutool.core.date.DateTime;

public class DateUtilExample {
    public static void main(String[] args) {
        // 创建日期范围生成器
        DateTime start = DateUtil.parse("2024-01-01");
        DateTime end = DateUtil.parse("2024-12-31");
        DateRange range = DateUtil.range(start, end, DateField.MONTH);

        // 遍历日期范围
        for (Date

Time dateTime : range) {
            System.out.println(dateTime);
        }
    }
}

API 说明

• range(DateTime start, DateTime end, DateField unit)：生成日期范围。
  • 作用：根据起始日期、结束日期和步长单位生成一个日期范围，方便批量操作。
  • 参数：
    • start：起始日期。
    • end：结束日期。
    • unit：步长单位，例如 DateField.MONTH 表示按月步进。
  • 返回值：日期范围对象 DateRange。

实际开发场景

日期范围生成器在报表生成、日历展示、时间序列分析等场景中非常有用。例如，在生成月度报表时，可以使用日期范围生成器生成每个月的起始日期列表。

public class Application {
    public static void main(String[] args) {
        DateTime startDate = DateUtil.parse("2024-01-01");
        DateTime endDate = DateUtil.parse("2024-12-31");

        // 按月遍历日期范围，生成报表时间段
        DateRange dateRange = DateUtil.range(startDate, endDate, DateField.MONTH);
        for (DateTime date : dateRange) {
            System.out.println("报表日期：" + DateUtil.formatDate(date));
        }
    }
}

---

11. 其他实用功能

DateUtil 还提供了许多实用功能，例如计算年龄、判断是否为闰年等。

示例代码

import cn.hutool.core.date.DateUtil;

public class DateUtilExample {
    public static void main(String[] args) {
        // 计算年龄
        int age = DateUtil.ageOfNow("1990-01-30");
        System.out.println("年龄：" + age);

        // 判断是否为闰年
        boolean isLeapYear = DateUtil.isLeapYear(2024);
        System.out.println("是否为闰年：" + isLeapYear);
    }
}

API 说明

• ageOfNow(String birthDateStr)：计算年龄。

  • 作用：根据生日字符串计算当前年龄。
  • 参数：
    • birthDateStr：生日字符串，格式如 yyyy-MM-dd。
  • 返回值：当前年龄。

• isLeapYear(int year)：判断是否为闰年。

  • 作用：判断指定年份是否为闰年。
  • 参数：
    • year：年份。
  • 返回值：布尔值，true 表示是闰年。

实际开发场景

这些功能在用户信息管理、日期验证等场景中应用广泛。例如，在用户注册时自动计算年龄或在日期选择器中标记闰年。

public class Application {
    public static void main(String[] args) {
        // 判断是否为闰年
        boolean leapYear = DateUtil.isLeapYear(2024);
        System.out.println("2024年是闰年吗？" + leapYear); // 输出：是

        // 计算用户的实际年龄
        String birthday = "1990-01-30";
        int userAge = DateUtil.ageOfNow(birthday);
        System.out.println("用户年龄：" + userAge); // 输出：34
    }
}

---

总结

DateUtil 工具类不仅功能强大，而且使用方便，能够极大简化日期和时间的操作。在实际开发中，DateUtil 是一个非常实用的工具，能够帮助我们更高效地处理日期和时间相关的任务。