Class DateUtil

java.lang.Object
com.sure.tool.date.DateUtil

public class DateUtil extends Object
日期时间工具类,参考 Hutool 的 DateUtil 设计。

English: Date and time parsing, formatting and arithmetic for Date values, with java.time-based internals.

Since:
0.1.0
Author:
suretool
  • Field Details

    • NORM_DATE_PATTERN

      public static final String NORM_DATE_PATTERN
      标准日期格式:yyyy-MM-dd
      See Also:
    • NORM_TIME_PATTERN

      public static final String NORM_TIME_PATTERN
      标准时间格式:HH:mm:ss
      See Also:
    • NORM_DATETIME_PATTERN

      public static final String NORM_DATETIME_PATTERN
      标准日期时间格式:yyyy-MM-dd HH:mm:ss
      See Also:
    • ISO_DATETIME_PATTERN

      public static final String ISO_DATETIME_PATTERN
      ISO 日期时间格式:yyyy-MM-dd'T'HH:mm:ss
      See Also:
  • Method Details

    • now

      public static Date now()
      当前时间。
      Returns:
      当前时间
    • current

      public static long current()
      当前毫秒时间戳。
      Returns:
      当前毫秒
    • currentSeconds

      public static long currentSeconds()
      当前秒级时间戳。
      Returns:
      当前秒
    • date

      public static Date date(long timeMillis)
      时间戳转 Date。
      Parameters:
      timeMillis - 毫秒时间戳
      Returns:
      Date
    • date

      public static Date date(Calendar calendar)
      Calendar 转 Date。
      Parameters:
      calendar - Calendar
      Returns:
      Date,空值返回 null
    • format

      public static String format(Date date)
      格式化日期时间(yyyy-MM-dd HH:mm:ss)。
      Parameters:
      date - 日期
      Returns:
      格式化字符串,空值返回 null
    • format

      public static String format(Date date, String format)
      按格式格式化日期。
      Parameters:
      date - 日期
      format - 格式
      Returns:
      格式化字符串,空值返回 null
    • formatDate

      public static String formatDate(Date date)
      格式化日期(yyyy-MM-dd)。
      Parameters:
      date - 日期
      Returns:
      格式化字符串
    • formatTime

      public static String formatTime(Date date)
      格式化时间(HH:mm:ss)。
      Parameters:
      date - 日期
      Returns:
      格式化字符串
    • parse

      public static Date parse(String dateStr, String format)
      按格式解析日期。
      Parameters:
      dateStr - 日期字符串
      format - 格式
      Returns:
      Date
    • parse

      public static Date parse(String dateStr)
      自动识别解析日期,支持:
      • yyyy-MM-dd
      • HH:mm:ss
      • yyyy-MM-dd HH:mm:ss
      • yyyy-MM-dd'T'HH:mm:ss
      Parameters:
      dateStr - 日期字符串
      Returns:
      Date,空白返回 null
    • offset

      public static Date offset(Date date, int datePart, int offset)
      日期偏移。
      Parameters:
      date - 日期
      datePart - 偏移字段(Calendar 常量,如 Calendar.DAY_OF_MONTH)
      offset - 偏移量,负数向前
      Returns:
      偏移后的日期
    • offsetDay

      public static Date offsetDay(Date date, int offset)
      天偏移。
      Parameters:
      date - 日期
      offset - 偏移天数,负数向前
      Returns:
      偏移后的日期
    • offsetHour

      public static Date offsetHour(Date date, int offset)
      小时偏移。
      Parameters:
      date - 日期
      offset - 偏移小时数,负数向前
      Returns:
      偏移后的日期
    • offsetMinute

      public static Date offsetMinute(Date date, int offset)
      分钟偏移。
      Parameters:
      date - 日期
      offset - 偏移分钟数,负数向前
      Returns:
      偏移后的日期
    • yesterday

      public static Date yesterday()
      昨天。
      Returns:
      昨天
    • tomorrow

      public static Date tomorrow()
      明天。
      Returns:
      明天
    • beginOfDay

      public static Date beginOfDay(Date date)
      当天开始时间(00:00:00.000)。
      Parameters:
      date - 日期
      Returns:
      当天开始时间
    • endOfDay

      public static Date endOfDay(Date date)
      当天结束时间(23:59:59.999)。
      Parameters:
      date - 日期
      Returns:
      当天结束时间
    • beginOfMonth

      public static Date beginOfMonth(Date date)
      当月开始时间(1 日 00:00:00.000)。
      Parameters:
      date - 日期
      Returns:
      当月开始时间
    • endOfMonth

      public static Date endOfMonth(Date date)
      当月结束时间(最后一天 23:59:59.999)。
      Parameters:
      date - 日期
      Returns:
      当月结束时间
    • between

      public static long between(Date start, Date end, DateUnit unit)
      两个日期之间的时间差。
      Parameters:
      start - 开始日期
      end - 结束日期
      unit - 时间单位
      Returns:
      时间差(按单位取整)
    • age

      public static int age(Date birthDate)
      计算周岁年龄。
      Parameters:
      birthDate - 出生日期
      Returns:
      年龄(周岁)
    • year

      public static int year(Date date)
      获取年份。
      Parameters:
      date - 日期
      Returns:
      年份
    • month

      public static int month(Date date)
      获取月份(1-12)。
      Parameters:
      date - 日期
      Returns:
      月份
    • day

      public static int day(Date date)
      获取日(1-31)。
      Parameters:
      date - 日期
      Returns:
      日
    • dayOfWeek

      public static int dayOfWeek(Date date)
      获取星期几(1=周日,7=周六)。
      Parameters:
      date - 日期
      Returns:
      星期几
    • isSameDay

      public static boolean isSameDay(Date date1, Date date2)
      是否为同一天。
      Parameters:
      date1 - 日期 1
      date2 - 日期 2
      Returns:
      是否为同一天
    • isLeapYear

      public static boolean isLeapYear(int year)
      是否为闰年。
      Parameters:
      year - 年份
      Returns:
      是否为闰年
    • toCalendar

      public static Calendar toCalendar(Date date)
      Date 转 Calendar。
      Parameters:
      date - 日期
      Returns:
      Calendar
    • getZodiac

      public static String getZodiac(Date date)
      获取星座。
      Parameters:
      date - 日期
      Returns:
      星座名,如 白羊座;null 返回 null
    • getChineseZodiac

      public static String getChineseZodiac(int year)
      获取农历生肖(按公历年,1900 年为鼠年)。
      Parameters:
      year - 公历年份
      Returns:
      生肖
    • beginOfWeek

      public static Date beginOfWeek(Date date)
      一天开始(周一为一周第一天,00:00:00.000)。
      Parameters:
      date - 日期
      Returns:
      当周周一 00:00:00.000
    • endOfWeek

      public static Date endOfWeek(Date date)
      一周结束(周日 23:59:59.999)。
      Parameters:
      date - 日期
      Returns:
      当周周日 23:59:59.999
    • formatChineseDateTime

      public static String formatChineseDateTime(Date date)
      中文格式日期时间(2026年9月16日 15:30:45)。
      Parameters:
      date - 日期
      Returns:
      中文日期时间
    • dayOfMonth

      public static int dayOfMonth(Date date)
      当月第几天(1~31)。
      Parameters:
      date - 日期
      Returns:
      日
    • hour

      public static int hour(Date date)
      小时(0~23)。
      Parameters:
      date - 日期
      Returns:
      小时
    • season

      public static int season(Date date)
      季度(1~4)。
      Parameters:
      date - 日期
      Returns:
      季度
    • formatChineseDate

      public static String formatChineseDate(Date date)
      中文格式日期(2026年9月16日)。
      Parameters:
      date - 日期
      Returns:
      中文日期
    • dayOfYear

      public static int dayOfYear(Date date)
      当年第几天(1~366)。
      Parameters:
      date - 日期
      Returns:
      天序号
    • minute

      public static int minute(Date date)
      分钟(0~59)。
      Parameters:
      date - 日期
      Returns:
      分钟
    • second

      public static int second(Date date)
      秒(0~59)。
      Parameters:
      date - 日期
      Returns:
      秒
    • formatBetween

      public static String formatBetween(Date start, Date end)
      两时间差的可读文本(x天x小时x分x秒)。
      Parameters:
      start - 开始
      end - 结束
      Returns:
      可读时长
    • isWeekend

      public static boolean isWeekend(Date date)
      是否为周末(周六/周日)。
      Parameters:
      date - 日期
      Returns:
      是否周末
    • offsetWeek

      public static Date offsetWeek(Date date, int offset)
      按周偏移。
      Parameters:
      date - 日期
      offset - 周偏移量(可负)
      Returns:
      偏移后日期
    • beginOfYear

      public static Date beginOfYear(Date date)
      年初(1 月 1 日 00:00:00.000)。
      Parameters:
      date - 日期
      Returns:
      当年 1 月 1 日 00:00:00.000
    • endOfYear

      public static Date endOfYear(Date date)
      年末(12 月 31 日 23:59:59.999)。
      Parameters:
      date - 日期
      Returns:
      当年 12 月 31 日 23:59:59.999
    • offsetMonth

      public static Date offsetMonth(Date date, int offset)
      按月偏移。
      Parameters:
      date - 日期
      offset - 月偏移量(可负)
      Returns:
      偏移后日期
    • getGanzhi

      public static String getGanzhi(Date date)
      年份天干地支(如 2026 → 丙午)。
      Parameters:
      date - 日期
      Returns:
      天干地支
    • offsetSecond

      public static Date offsetSecond(Date date, int offset)
      按秒偏移。
      Parameters:
      date - 日期
      offset - 秒偏移量(可负)
      Returns:
      偏移后日期
    • offsetYear

      public static Date offsetYear(Date date, int offset)
      按年偏移。
      Parameters:
      date - 日期
      offset - 年偏移量(可负)
      Returns:
      偏移后日期
    • isIn

      public static boolean isIn(Date date, Date start, Date end)
      是否在时间区间内(含边界)。
      Parameters:
      date - 待判断日期
      start - 区间开始(可为 null 表示无下界)
      end - 区间结束(可为 null 表示无上界)
      Returns:
      是否在区间内
    • isToday

      public static boolean isToday(Date date)
      是否今天。
      Parameters:
      date - 日期
      Returns:
      是否今天
    • isYesterday

      public static boolean isYesterday(Date date)
      是否昨天。
      Parameters:
      date - 日期
      Returns:
      是否昨天
    • beginOfQuarter

      public static Date beginOfQuarter(Date date)
      获取季度开始时间(当季第 1 天 00:00:00)。
      Parameters:
      date - 日期
      Returns:
      季度开始
    • endOfQuarter

      public static Date endOfQuarter(Date date)
      获取季度结束时间(当季最后 1 天 23:59:59)。
      Parameters:
      date - 日期
      Returns:
      季度结束
    • age

      public static int age(Date birthDate, Date date)
      计算周岁年龄(指定参考日期)。
      Parameters:
      birthDate - 出生日期
      date - 参考日期
      Returns:
      周岁
    • isSameMonth

      public static boolean isSameMonth(Date date1, Date date2)
      判断两个日期是否同一个月。
      Parameters:
      date1 - 日期 1
      date2 - 日期 2
      Returns:
      是否同年同月;任一为 null 返回 false
    • toDate

      public static Date toDate(Calendar calendar)
      Calendar 转 Date。
      Parameters:
      calendar - Calendar
      Returns:
      Date;null 返回 null
    • beginOfHour

      public static Date beginOfHour(Date date)
      当前小时开始时间。
      Parameters:
      date - 日期
      Returns:
      小时起点(分钟/秒/毫秒归零)
    • endOfHour

      public static Date endOfHour(Date date)
      当前小时结束时间。
      Parameters:
      date - 日期
      Returns:
      小时终点(下一小时前 1 毫秒)
    • daysBetween

      public static long daysBetween(Date start, Date end)
      两个日期的自然日天数差(忽略时分秒)。
      Parameters:
      start - 开始日期
      end - 结束日期
      Returns:
      天数差(end - start)
    • betweenMs

      public static long betweenMs(Date start, Date end)
      两个日期的毫秒差(end - start)。
      Parameters:
      start - 开始日期
      end - 结束日期
      Returns:
      毫秒差
    • betweenSeconds

      public static long betweenSeconds(Date start, Date end)
      两个日期的秒差(end - start,向下取整)。
      Parameters:
      start - 开始日期
      end - 结束日期
      Returns:
      秒差
    • isOverlap

      public static boolean isOverlap(Date start1, Date end1, Date start2, Date end2)
      判断两个时间段是否重叠(含边界相接,start < end 为前置条件)。
      Parameters:
      start1 - 时间段 1 开始
      end1 - 时间段 1 结束
      start2 - 时间段 2 开始
      end2 - 时间段 2 结束
      Returns:
      是否重叠
    • rangeToList

      public static List<Date> rangeToList(Date start, Date end, DateUnit unit)
      生成日期区间列表(含头含尾,按指定单位步进)。
      Parameters:
      start - 开始日期
      end - 结束日期
      unit - 步进单位
      Returns:
      日期列表,start 晚于 end 时返回空列表
    • getWeekOfMonth

      public static int getWeekOfMonth(Date date)
      日期在当月中的第几周。
      Parameters:
      date - 日期
      Returns:
      周序号(1 起)
    • isSameYear

      public static boolean isSameYear(Date date1, Date date2)
      判断两个日期是否同年。
      Parameters:
      date1 - 日期一
      date2 - 日期二
      Returns:
      是否同年
    • getMonthName

      public static String getMonthName(int month)
      获取月份中文名(一月~十二月)。
      Parameters:
      month - 月份(1-12)
      Returns:
      中文月份名
    • getMonthName

      public static String getMonthName(Date date)
      获取日期所在月份的中文名。
      Parameters:
      date - 日期
      Returns:
      中文月份名
    • offsetQuarter

      public static Date offsetQuarter(Date date, int offset)
      偏移季度。
      Parameters:
      date - 日期
      offset - 偏移量(可为负)
      Returns:
      偏移后的日期
    • getYear

      public static int getYear(Date date)
      获取年份。
      Parameters:
      date - 日期
      Returns:
      年份
    • getMonth

      public static int getMonth(Date date)
      获取月份(1-12)。
      Parameters:
      date - 日期
      Returns:
      月份
    • getDayOfMonth

      public static int getDayOfMonth(Date date)
      获取日(1-31)。
      Parameters:
      date - 日期
      Returns:
      日
    • getHour

      public static int getHour(Date date)
      获取小时(0-23)。
      Parameters:
      date - 日期
      Returns:
      小时
    • getWeekOfYear

      public static int getWeekOfYear(Date date)
      获取一年中的第几周。
      Parameters:
      date - 日期
      Returns:
      周序号(1 起)
    • format

      public static String format(LocalDate date)
      格式化 LocalDate(yyyy-MM-dd)。
      Parameters:
      date - 日期
      Returns:
      格式化字符串
    • format

      public static String format(LocalDateTime dateTime)
      格式化 LocalDateTime(yyyy-MM-dd HH:mm:ss)。
      Parameters:
      dateTime - 日期时间
      Returns:
      格式化字符串
    • beginOfMinute

      public static Date beginOfMinute(Date date)
      获取某时刻所在分钟的开始(秒和毫秒归零)。
      Parameters:
      date - 日期
      Returns:
      分钟开始
    • endOfMinute

      public static Date endOfMinute(Date date)
      获取某时刻所在分钟的结束(秒 59、毫秒 999)。
      Parameters:
      date - 日期
      Returns:
      分钟结束
    • getAge

      public static int getAge(Date birth)
      计算周岁年龄。
      Parameters:
      birth - 出生日期
      Returns:
      年龄(周岁),null 返回 0
    • beginOfSecond

      public static Date beginOfSecond(Date date)
      获取某时刻所在秒的开始(毫秒归零)。
      Parameters:
      date - 日期
      Returns:
      秒开始
    • endOfSecond

      public static Date endOfSecond(Date date)
      获取某时刻所在秒的结束(毫秒 999)。
      Parameters:
      date - 日期
      Returns:
      秒结束
    • toLocalDate

      public static LocalDate toLocalDate(Date date)
      转换为 LocalDate(系统默认时区)。

      示例:DateUtil.toLocalDate(new Date())。

      Parameters:
      date - 日期,可为 null
      Returns:
      LocalDate;null 返回 null
    • toLocalDateTime

      public static LocalDateTime toLocalDateTime(Date date)
      转换为 LocalDateTime(系统默认时区)。

      示例:DateUtil.toLocalDateTime(new Date())。

      Parameters:
      date - 日期,可为 null
      Returns:
      LocalDateTime;null 返回 null
    • toDate

      public static Date toDate(LocalDate localDate)
      LocalDate 转 Date(系统时区当日 00:00)。

      示例:DateUtil.toDate(LocalDate.now())。

      Parameters:
      localDate - LocalDate,可为 null
      Returns:
      Date;null 返回 null
    • toDate

      public static Date toDate(LocalDateTime localDateTime)
      LocalDateTime 转 Date(系统默认时区)。

      示例:DateUtil.toDate(LocalDateTime.now())。

      Parameters:
      localDateTime - LocalDateTime,可为 null
      Returns:
      Date;null 返回 null
    • parseLocalDate

      public static LocalDate parseLocalDate(String dateStr)
      解析 ISO 日期字符串(yyyy-MM-dd)为 LocalDate。

      示例:DateUtil.parseLocalDate("2026-10-15")。

      Parameters:
      dateStr - 日期字符串,可为 null
      Returns:
      LocalDate;null 或空串返回 null
    • parseLocalDateTime

      public static LocalDateTime parseLocalDateTime(String dateTimeStr)
      解析常见日期时间字符串为 LocalDateTime(自动探测格式)。

      支持格式:yyyy-MM-dd HH:mm:ss、yyyy-MM-dd HH:mm、yyyy-MM-dd HH:mm:ss.SSS、 ISO 日期时间等;纯日期按当日 00:00 处理。

      Parameters:
      dateTimeStr - 日期时间字符串,可为 null
      Returns:
      LocalDateTime;null 或空串返回 null
    • parseLocalDateTime

      public static LocalDateTime parseLocalDateTime(String dateTimeStr, String pattern)
      按指定格式解析日期时间字符串为 LocalDateTime。

      示例:DateUtil.parseLocalDateTime("2026/10/15 08:30", "yyyy/MM/dd HH:mm")。

      Parameters:
      dateTimeStr - 日期时间字符串,可为 null
      pattern - 格式模式(DateTimeFormatter 语法)
      Returns:
      LocalDateTime;null 或空串返回 null
    • isSameWeek

      public static boolean isSameWeek(Date date1, Date date2)
      判断两个日期是否在同一周(ISO 周定义:周一为一周首日)。

      示例:DateUtil.isSameWeek(monday, friday) 同周返回 true。

      Parameters:
      date1 - 日期 1,可为 null
      date2 - 日期 2,可为 null
      Returns:
      同周返回 true;任一为 null 返回 false
    • truncate

      public static Date truncate(Date date, int field)
      截断到指定 Calendar 字段(该字段保留,更小字段清零)。

      对齐 Commons DateUtils.truncate:示例 DateUtil.truncate(date, Calendar.DAY_OF_MONTH) 等价于 beginOfDay(date)。

      Parameters:
      date - 日期,可为 null
      field - Calendar 字段常量(如 Calendar.HOUR_OF_DAY / Calendar.DAY_OF_MONTH / Calendar.MONTH)
      Returns:
      截断后的日期;null 返回 null
    • round

      public static Date round(Date date, int field)
      四舍五入到指定 Calendar 字段。

      对齐 Commons DateUtils.round:秒 >= 30 时进位到下一分钟,小时 >= 12 时进位到下一日等。

      Parameters:
      date - 日期,可为 null
      field - Calendar 字段常量
      Returns:
      舍入后的日期;null 返回 null
    • ceiling

      public static Date ceiling(Date date, int field)
      进位到指定 Calendar 字段(字段本身保留,更小字段清零并向上进位)。

      对齐 Commons DateUtils.ceiling:任何小于 field 的字段非零即进位到下一字段。

      Parameters:
      date - 日期,可为 null
      field - Calendar 字段常量
      Returns:
      进位后的日期;null 返回 null