xk-time Java 时间工具包。时间转换，计算，格式化，解析，日历和 cron 表达式等的工具，使用 java8，线程安全，简单易用，多达 60 几种常用日期格式化模板。

[xkzhangsan]

https://github.com/xkzhangsan/xk-time

xk-time is a datetime converter calculator formatter calendar and cron expression tool set, based on java8 date and time API, thread safe, easy to use.

时间转换，计算，格式化，解析，日历和 cron 表达式等的工具，使用 java8，线程安全，简单易用，多达 60 几种常用日期格式化模板。

0.为什么要开发这个工具？

（ 1 ） java8 以前的 Date API 设计不太好，使用不方便，往往会有线程安全问题。

xk-time 工具包，使用 java8 api，其中 Instant 、LocalDate 、LocalDateTime 、LocalTime 、ZonedDateTime 等都是线程安全的类，而且增加了更丰富的方法，在此基础上开发相关工具类，线程安全，让使用更方便。

（ 2 ）常见的 DateUtil，往往将时间转换，计算，格式化，解析等功能都放在同一个类中，导致类功能复杂，方法太多，查找不方便。

xk-time 工具包，将上面功能按照时间转换，时间计算，时间格式化解析分成 3 个工具类：DateTimeConverterUtil，DateTimeCalculatorUtil，DateTimeFormatterUtil，每个类只做一个种功能，方便使用。

（ 3 ）为了将与时间紧密相关的节假日、农历、二十四节气、十二星座和日历等功能集中起来开发成工具，方便使用。

1.Maven 坐标

<dependency>  
  <groupId>com.github.xkzhangsan</groupId>    
  <artifactId>xk-time</artifactId>       
  <version>1.1.1</version>    
</dependency>    

2.日期转换工具类 DateTimeConverterUtil

包含 Date 、LocalDate 、LocalDateTime 、LocalTime 、Instant 、ZonedDateTime 、YearMonth 和 Timestamp 的互相转换
注意，ZonedDateTime 相关的转换，尤其是其他时间转 ZonedDateTime，要注意时间和对应时区一致。

详细使用可以查看相关测试代码。

3.日期计算工具类 DateTimeCalculatorUtil

包括：
（ 1 ）获取时间属性方法，get* 比如 getYear(Date date) 获取年部分，getMonthCnLong(Date date)获取月份中文，getDayOfWeekCn(Date date)，获取星期中文。
（ 2 ）获取时间加操作方法，plus* 比如 plusYears(Date date, long amountToAdd) 当前时间年增加 amountToAdd 值。
（ 3 ）获取时间减操作方法，minus* 比如 minusYears(Date date, long amountToSubtract) 当前时间年减少 amountToSubtract 值。
（ 4 ）获取时间修改属性方法，with* 比如 withYear(Date date, long newValue) 修改当前时间年值为 newValue 。
（ 5 ）获取比较 2 个时间方法，between* 比如 betweenYears(Date startInclusive, Date endExclusive) 比较 2 个时间，获取年部分。
（ 6 ）其他常用方法，比如 isLeapYear(Date date) 判断是否闰年，isWeekend(Date date) 判断是否周末，isExpiry(String yearMonthStr) 是否过期等
（ 7 ）时区转换计算方法，transform*，比如 transform(ZonedDateTime zonedDateTime, String zoneId)
（ 8 ）比较 2 个时间大小和相等方法，compare*，比如 compare(Date date1, Date date2)
（ 9 ）获取准确的起始时间方法，start*,end*，比如 startTimeOfMonth() 当月起始时间 当月第一天日期+00:00:00，endTimeOfMonth() 当月最后一天日期+23:59:59 。
（ 10 ）相同月日比较判断方法，isSameMonthDay*，betweenNextSameMonthDay*，nextSameMonthDay*， 比如用于生日，节日等周期性的日期比较判断。
（ 11 ）星座计算方法，getConstellation*，比如 getConstellationNameCn(String monthDayStr)，根据日期计算星座。
（ 12 ）计算指定年月或起始时间区间的时间列表，getList， 比如 getDateList(int year, int month)，计算指定年月的时间列表。
（ 13 ）减少时间精度方法，reduceAccuracyTo， 比如 reduceAccuracyToDay(Date date)，减少时间精度到天，其他补 0，返回如，2020-04-23 00:00:00 。
（ 14 ）获取时间戳方法，getEpoch*， 比如 getEpochMilli()获取时间戳，getEpochMilliFormat()获取时间戳格式化字符串（ yyyy-MM-dd HH:mm:ss ）
（ 15 ）计算年龄方法，getAge*， 比如 getAge(Date birthDay)，通过生日计算年龄。
（ 16 ）判断是否到生日方法，isBirthDay*， 比如 isBirthDay(Date birthDay)，根据生日判断当前日期是否到生日。

详细使用可以查看相关测试代码。

4.日期格式化和解析工具类 DateTimeFormatterUtil

包含常用日期格式如：
yyyy-MM-dd
HH:mm:ss
yyyy-MM-dd HH:mm:ss
yyyy-MM-dd'T'HH:mm:ssZ 等等

（ 1 ）格式化方法，format*， 比如 formatToDateStr(Date date) 格式化，返回日期部分，如：yyyy-MM-dd ；
format(Date date, DateTimeFormatter formatter) formatter 可以选择已定义好的 formatter 比如 YYYY_MM_DD_HH_MM_SS_FMT （ yyyy-MM-dd HH:mm:ss ）格式化日期。

（ 2 ）解析方法，parse*， 比如 parseDateStrToDate(String text) 解析日期 yyyy-MM-dd，返回 Date ；
parseToDate(String text, DateTimeFormatter formatter) 根据 formatter 解析为 Date 。

（ 3 ）自动解析方法，根据字符串特点自动识别解析，smartParse*，比如 smartParseToDate(String text) 自动解析 Date 。

（ 4 ） ISO 格式（包含 T ）自动解析方法，根据字符串特点自动识别解析，parseIso*，比如 parseIsoToDate(String text) 自动解析 Date 。

（ 5 ）解析时间戳方法, parseEpochMilli*， 比如 parseEpochMilliToDate(String text)，解析时间戳为 Date，如 1590224790000 。

（ 6 ）解析 Date 默认格式，parseDateDefaultStr*，比如 parseDateDefaultStrToDate(String text)
解析 EEE MMM dd HH:mm:ss zzz yyyy 比如： Sat May 23 17:06:30 CST 2020 为 Date 。

（ 7 ）自定义时区格式化方法，比如 format(Date date, DateTimeFormatter formatter, String zoneId)，根据 zoneId 格式化 Date 。

注意：格式化和解析与系统时区不同的时间时，使用自定义时区格式化方法，或可以使用 withZone 方法重新设置时区，比如：
YYYY_MM_DD_HH_MM_SS_SSS_FMT.withZone(ZoneId.of("Europe/Paris") 。

详细使用可以查看相关测试代码。

5.日历工具类 CalendarUtil

包括：
（ 1 ）生成指定时间的日历（包含年、月和日层级关系的日历）方法，generateCalendar* 比如 generateCalendar(int year, int month) 生成指定年月的日历。
（ 2 ）生成指定时间的日历（包含年、月和日层级关系的日历），包含农历和所有节假日信息方法，generateCalendarWithHoliday*， 比 generateCalendarWithHoliday(int year, int month, Map<String, String> localHolidayMap,Map<String, String> chineseHolidayMap, Map<String, Integer> dateTypeMap)生成指定年月的日历，包含农历和所有节假日信息，可以自定义节假日和工作日等。

详细使用可以查看相关测试代码。

6.农历日期类 LunarDate

包含：
（ 1 ）农历日期年月日计算。
（ 2 ）农历岁次，生肖属相计算。
（ 3 ）二十四节气计算等
注意： 仅支持公历 1901-2050 年的农历转换。
农历和二十四节气计算的准确依赖于 lunarInfo 和 solarTermInfo 基础数据的准确性和精确度。
根据测试结果，发现本程序和常用万年历基本一致，常用万年历软件中也有很少量计算误差，欢迎提出问题，会不断进行改进和修正。

详细使用可以查看相关测试代码。

7.节假日计算类 Holiday

包含：
（ 1 ）公历节假日计算，getLocalHoliday* 比如 getLocalHoliday(Date date) 计算 date 的公历节日，getLocalHoliday(Date date, Map<String, String> localHolidayMap) 可以传入自定义公历节日数据。
（ 2 ）农历节假日计算，getChineseHoliday* 比如 getChineseHoliday(Date date) 计算 date 的农历节日，getChineseHoliday(Date date, Map<String, String> chineseHolidayMap) 可以传入自定义农历节日数据。
（ 3 ）二十四节气计算，getSolarTerm* 比如 getSolarTerm(Date date) 计算 date 的二十四节气。

注意： 农历和二十四节气使用农历日期类 LunarDate，仅支持公历 1901-2050 年的计算。

详细使用可以查看相关测试代码。

8.Cron 表达式工具类 CronExpressionUtil

cron 表达式从左到右（用空格隔开）：秒（ 0-59 ） 分（ 0-59 ） 小时（ 0-23 ） 日期（ 1-31 ） 月份（ 1-12 的整数或者 JAN-DEC ） 星期（ 1-7 的整数或者 SUN-SAT （ 1=SUN ）） 年份（可选，1970-2099 ）
所有字段均可使用特殊字符：, - * / 分别是枚举，范围，任意，间隔
日期另外可使用：? L W 分别是任意，最后，有效工作日(周一到周五)
星期另外可使用：? L # 分别是任意，最后，每个月第几个星期几
常用 cron 表达式：
（ 1 ） 0 0 2 1 * ? * 表示在每月的 1 日的凌晨 2 点触发
（ 2 ） 0 15 10 ? * MON-FRI 表示周一到周五每天上午 10:15 执行作业
（ 3 ） 0 15 10 ? * 6L 2002-2006 表示 2002-2006 年的每个月的最后一个星期五上午 10:15 执行作
（ 4 ） 0 0/30 9-17 * * ? 朝九晚五工作时间内每半小时
（ 5 ） 0 15 10 L * ? 每月最后一日的上午 10:15 触发
（ 6 ） 0 15 10 ? * 6#3 每月的第三个星期五上午 10:15 触发

包含
（ 1 ）验证和格式化 Cron 表达式方法，isValidExpression 和 formatExpression 。
（ 2 ）生成下一个或多个执行时间方法，getNextTime 和 getNextTimeList 。
（ 3 ）生成下一个或多个执行时间的日期格式化（ yyyy-MM-dd HH:mm:ss ）方法，getNextTimeStr 和 getNextTimeStrList 。
（ 4 ）对比 Cron 表达式下一个执行时间是否与指定 date 相等方法，isSatisfiedBy 。

注意： 底层使用 quartz 的 CronExpression 处理。

详细使用可以查看相关测试代码。

欢迎使用和提建议!

https://github.com/xkzhangsan/xk-time

[xkzhangsan]

开发这个工具，从有想法到现在已经半年多时间，发布过 10 个以上版本，不断迭代，增加新的功能。

会持续维护，欢迎使用和提建议！

[nl101531]

身处国际业务，踩过不少坑，时间我觉得最复杂的是时区问题。。。

[xkzhangsan]

@nl101531 对的，时区处理比较麻烦，Java8 可以使用 ZonedDateTime 非常方便。
格式化和解析也有很好的支持，比如 java.time.format.DateTimeFormatter.ISO_DATE_TIME 。

xk-time 里面有包含时区转换，格式化解析多种功能，希望有所帮助。

[doudouwu]

感觉不错，之前一直用 hutool，可以尝试使用这个看看

[xkzhangsan]

@doudouwu 感谢支持！

[xkzhangsan]

感谢大家的收藏！

[xkzhangsan]

1.1.2 版本发布，更新内容：

1.增加微秒和纳秒格式化模板
2.增加根据自定义模板格式化和解析方法
3.增加 Timestamp 默认格式格式化和解析方法
4.增加 yyyy-M-d H:m:s,SSS 格式化和解析
5.代码优化

支持自定义模板格式化，比如 V2EX 带时区的这个时间格式 2020-06-17 18:16:14 +08:00
使用模板：yyyy-MM-dd HH:mm:ss xxx 注意 0 时区时显示+00:00

使用实例：

System.out.println(DateTimeFormatterUtil.format(new Date(), "yyyy-MM-dd HH:mm:ss xxx"));

输出：

2020-06-18 00:24:19 +08:00

[xkzhangsan]

常用格式化模板已经增加了 70 多种了，有哪些需要添加的模板或功能可以留言。

[xkzhangsan]

感谢大家的收藏！