V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
爱意满满的作品展示区。
xkzhangsan
V2EX  ›  分享创造

xk-time Java 时间工具包

  •  1
     
  •   xkzhangsan ·
    xkzhangsan · 2020-09-26 13:56:59 +08:00 · 1918 次点击
    这是一个创建于 1517 天前的主题,其中的信息可能已经有所发展或是发生改变。

    xk-time 是时间转换,计算,格式化,解析,日历和 cron 表达式等的工具,使用 Java8,线程安全,简单易用,多达 70 几种常用日期格式化模板,支持 Java8 时间类和 Date,轻量级,无第三方依赖。

    xk-time is a tool for time conversion, calculation, formatting, parsing, calendar and cron expression, etc., using Java8, thread-safe, easy to use, up to 70 commonly used date formatting templates, support Java8 time class and Date , Lightweight, no third party dependence.

    安装项目

    ( 1 ) Maven

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

    ( 2 ) Gradle

    compile group: 'com.github.xkzhangsan', name: 'xk-time', version: '2.1.2'  
    

    注意:Android 谨慎使用,Android 端因为需要兼容低版本而不支持 Java8,建议继续使用其他工具,如果有需要本项目相关的功能,可以参考源码实现,或留言给我。感谢支持!

    为什么要开发这个工具?

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

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

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

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

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

    1.日期转换工具类 DateTimeConverterUtil

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

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

    2.日期计算工具类 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 )计算指定年月或起始时间区间的时间列表,get*List, 比如 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),根据生日判断当前日期是否到生日。

    ( 17 )周数计算方法,weekof*, 比如 weekOfMonth(Date date),日期所在月中第几周。

    ( 18 )判断星期一,星期五方法,isMonday*,isZhouYi*, 比如 isZhouYi(Date date),是否为周一。

    ( 19 )十二时辰计算方法,getTwelveTwo*, 比如 getTwelveTwo(Date date),获取指定时间对应的十二时辰。

    ( 20 )季度计算方法,getQuarter*, 比如 getQuarter(Date date),获取指定时间对应的季度

    ( 21 )获取季度准确的起始时间方法(四个季度),startTimeOf*Quarter, 比如 startTimeOfFirstQuarter(int year),获取指定年的第一季度

    ( 22 ) 获取年准确的起始时间方法,startTimeOfYear, 比如 startTimeOfYear(int year),获取指定年的开始时间

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

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

    包含常用日期格式如:
    yyyy-MM-dd
    HH:mm:ss
    yyyy-MM-dd HH:mm:ss
    yyyy-MM-dd HH:mm:ss.SSS
    yyyy-MM-dd HH:mm:ss.SSSSSS
    yyyy-MM-dd HH:mm:ss.SSSSSSSSS
    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 。

    ( 8 )自定义模板格式化方法,比如 format(Date date, String dateFormatPattern),根据 dateFormatPattern 格式化 Date 。

    ( 9 )自定义模板解析方法,比如 parseToDate(String text, String dateFormatPattern),根据 dateFormatPattern 格式化 Date 。

    ( 10 ) Timestamp 默认格式( yyyy-mm-dd hh:mm:ss.fffffffff 其中 fffffffff 纳秒,省略后面的 0 )格式化方法。
    比如 formatTimestampStyle(Date date)。

    ( 11 ) Timestamp 默认格式( yyyy-mm-dd hh:mm:ss.fffffffff 其中 fffffffff 纳秒,省略后面的 0 )解析方法。
    比如 parseTimestampStyleToDate(String text)。

    ( 12 )验证日期格式是否正确方法,isValidDate*, 比如 isValidDate(String text),验证 yyyy-MM-dd 格式字符串是否正确。

    ( 13 )根据自定义模板数组解析方法, 比如 parseToDate(String text, String[] dateFormatPatterns),dateFormatPatterns 支持多种模板,只要其中一个解析成功就返回对应 Date 。

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

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

    4.日历工具类 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)生成指定年月的日历,包含农历和所有节假日信息,可以自定义节假日和工作日等。

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

    5.农历日期类 LunarDate

    包含:
    ( 1 )农历日期年月日计算。
    ( 2 )农历岁次,生肖属相计算。
    ( 3 )二十四节气计算等
    注意: 仅支持公历 1900-2100 年的农历转换。

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

    6.节假日计算类 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,仅支持公历 1900-2100 年的计算。

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

    7.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 处理。

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

    8.计算耗时工具 CostUtil

    计算耗时工具,支持秒,毫秒,纳秒

    包括:
    ( 1 )计算耗时,返回耗时结果。
    ( 2 )计算耗时,自定义任务名称,输出耗时结果。
    ( 3 )计算耗时,返回精确计时,带 3 小数的结果,使用 ROUND_DOWN 舍弃超过 3 位的小数部分等。

    参与项目

    1.提 bug 和建议

    2.贡献代码

    ( 1 ) fork 项目。
    ( 2 )在 dev 分支修改。
    ( 3 )提交 pull request 。

    第 1 条附言  ·  2020-09-26 23:33:42 +08:00
    第 2 条附言  ·  2020-10-09 18:50:05 +08:00
    增加了 Javadoc 文档,欢迎使用和提建议 https://apidoc.gitee.com/xkzhangsan/xk-time
    4 条回复    2020-09-27 21:33:14 +08:00
    tomxin7
        1
    tomxin7  
       2020-09-26 19:04:24 +08:00
    支持一下
    xkzhangsan
        2
    xkzhangsan  
    OP
       2020-09-26 19:48:25 +08:00
    @tomxin7 感谢支持!
    18258226728
        3
    18258226728  
       2020-09-27 13:54:40 +08:00
    支持
    xkzhangsan
        4
    xkzhangsan  
    OP
       2020-09-27 21:33:14 +08:00 via Android
    @18258226728 感谢支持!
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   实用小工具   ·   3463 人在线   最高记录 6679   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 25ms · UTC 04:32 · PVG 12:32 · LAX 20:32 · JFK 23:32
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.