Java 日期、时间 API 总结

水深无声 2023-06-11 11:21 5阅读 0赞

# 日期、时间的相关抽象 #

Java 8 对时间、日期进行了新的抽象，构建了一系列的日期、时间对象用作相关的时间操作。

## LocalDate , LocalTime 和 LocalDateTime ##

LocalDate 是对日期的抽象，即年月日。LocalTime 是对时间的抽象，即时分秒。而 LocalDateTime 即是 LocalDate 以及 LocalTime 的结合，表示日期与时间。  
以上三者都是在开发时常用到的三种时间表示方式。三者的实例都是不可变对象，每次时间的改变，都会新创建一个对应的对象，所以它们是线程安全的。  
下面将较为详细的介绍三者。

### LocalDate ###

LocalDate 表示日期，获取一个 LocalDate 对象有如下方式：

// 创建表示当前日期的 LocalDate 对象
    LocalDate nowDate = LocalDate.now();
    // 创建指定日期的 LocalDate 对象
    LocalDate specificDate = LocalDate.of(2018, 8, 8);
    // 获取最小日期，通常用来表示很久很久以前
    LocalDate minDate = LocalDate.MIN;
    // 获取获取最大日期，通常用来表示很远很远的未来
    LocalDate maxDate = LocalDate.MAX;

除此之外，还有一种解析字符串创建 LocalDate 的方式，这也是在实际开发中经常用到的。在默认情况下使用 ISO 8601 标准。有以下用例：

LocalDate specificDate = LocalDate.parse("2018-08-08");

获取到实例后，有各种实用的、可读性强的 API 供我们读取相关的时间信息。有以下用例：

LocalDate date = LocalDate.of(2018, 8, 8);
    // 获取年份
    int year = date.getYear();
    // 获取月份对象，可以使用 getMonthValue 方法获取月份值，范围为 1-12
    Month month = date.getMonth();
    // 获取日期
    int day = date.getDayOfMonth();
    // 获取周对象
    DayOfWeek dow = date.getDayOfWeek();
    // 获取本日期的月份长度
    int len = date.lengthOfMonth();
    // 判断本日期是否为闰年
    boolean leap = date.isLeapYear();

除此之外，LocalDate 还有一个 get 方法，可以接受一个 TemporalField 参数拿到指定的信息。该接口定义了如何获取各个日期、时间对象某个字段的值，枚举类 [ChronoField][] 实现了该接口，可以很方便的通过传递 ChronoField 枚举类的实例来获取指定信息。有以下用例：

int year = date.get(ChronoField.YEAR);
    int month = date.get(ChronoField.MONTH_OF_YEAR);
    int day = date.get(ChronoField.DAY_OF_MONTH);

要注意的是，不同的日期、时间对象可以接受的 TemporalField 参数是不同的，如果无法接受传递 TemporalField 的参数将会抛出异常 **UnsupportedTemporalTypeException** 。

除了获取信息外，修改日期、时间对象也是常见的需求，例如，要获取当前日期 3 天后的日期。可以利用日期、时间对象的 **plus** 方法便捷地完成该需求：

LocalDate date = LocalDate.now().plus(3, ChronoUnit.DAYS);

前面提到，LocalDate 是不可变对象，所以 plus 方法返回的是一个新的 LocalDate 对象。如果想获取的是三天前的日期，传递一个负数即可。

### LocalTime ###

LocalTime 表示时间（时分秒），创建一个 LocalTime 实例有如下方式：

// 获取当前时间
    LocalTime nowTime = LocalTime.now();
    // 获取指定时间，12时30分30秒
    LocalTime specificTime = LocalTime.of(12, 30, 30);
    // 获取当天最小时间，即 00时00分
    LocalTime minTime = LocalTime.MIN;
    // 获取当天最大时间，即 23时59分59.999999999秒
    LocalTime maxTime = LocalTime.MAX;
    // 半夜十二点，与 LocalTime.MIN 一样的值
    LocalTime midnightTime = LocalTime.MIDNIGHT;
    // 中午十二点
    LocalTime noonTime = LocalTime.NOON;
    // 解析字符串获取时间对象，以 ISO 8601 标准为解析格式
    LocalTime strSpecificTime = LocalTime.parse("12:30:30");

有以下获取 LocalTime 对象信息的方式：

int hour = time.getHour();
    int minute = time.getMinute(); 
    int second = time.getSecond();
    int minuteOfDay = time.get(ChronoField.MINUTE_OF_DAY);

同样也可以使用 plus 方法修改对象，当然返回的将会是一个新的 LocalTime 实例。

// 获取当前时间 2 分钟后的时间
    LocalTime time = LocalTime.now().plus(2, ChronoUnit.MINUTES);

### LocalDateTime ###

LocalDateTime 表示时间日期，是 LocalDate 与 LocalTime 的结合，LocalDate 或是 LocalTime 有的特性 LocalDateTime 基本上都有。  
可以通过以下方式获取 LocalDateTime 的实例：

// 获取当前时间和日期
    LocalDateTime nowDateTime = LocalDateTime.now();
    // 获取指定的时间日期，如 2018-08-12T12:30:30
    LocalDateTime specificDateTime = LocalDateTime.of(2018, Month.AUGUST, 12, 12, 30, 30);
    // 解析字符串获取日期时间
    LocalDateTime strSpecificDateTime = LocalDateTime.parse("2018-08-12T12:30:30");
    // 最小日期时间，通常用来表示很久很久以前
    LocalDateTime minDateTime = LocalDateTime.MIN;
    // 最大日期时间，通常用来表示很远很远的未来
    LocalDateTime maxDateTime = LocalDateTime.MAX;
    
    // 通过 LocalDate 实例以及 LocalTime 实例获取 LocalDateTime 实例
    LocalDate date = LocalDate.of(2018, 8, 8);
    LocalTime time = LocalTime.of(12, 30, 30);
    
    LocalDateTime dt = LocalDateTime.of(date, time);
    LocalDateTime dt1 = date.atTime(time);
    LocalDateTime dt2 = date.atTime(12, 30, 30);
    LocalDateTime dt3 = time.atDate(date);

能够通过 LocalDate 实例以及 LocalTime 实例获取 LocalDateTime 实例，自然也能通过 LocalDateTime 对象获取到 LocalDate ，LocalTime 对象。

LocalDate date = dateTime.toLocalDate();
    LocalTime time = dateTime.toLocalTime();

通过 LocalDate 和 LocalTime 获取的信息，基本上也可以通过 LocalDateTime 获取到。有以下简单的用例：

int year = dateTime.getYear();
    int minute = dateTime.getMinute();
    int dayOfHours = dateTime.get(ChronoField.HOUR_OF_DAY);

最后对于 LocalDateTime 对象的修改，同样，实际上没有修改 LocalDateTime 对象，而是返回一个新的对象。

LocalDateTime.now().plus(-1, ChronoUnit.DAYS);
    LocalDateTime.now().plus(3, ChronoUnit.HOURS);

## Instant ##

前面提到的日期时间类如 LocalDate ，对人类是友好的，因为它们以我们所属性的方式表现时间。但是对于机器来说，多少年，几号，周几这样的算法是不友好的，而像 UNIX 时间戳这种用数值来表示当前时间点的方式对机器跟为友好。  
Instant 类是对时间线上的某个时间点的抽象，简单点说就是对时间戳的抽象。它也是一个不可变对象，当尝试去修改一个 Instant 实例时，将会得到一个新的 Instant 实例。  
可以通过以下方式获取 Instant 的实例：

// 获取当前时间
    Instant nowInstant = Instant.now();
    // 通过时间戳数值获取时间，单位为秒
    Instant specificInstantBySecond = Instant.ofEpochSecond(1540182630L);
    // 在 1540182630 的基础上加上一百万纳秒，即 1 秒
    Instant specificInstantBySecondAndNano = Instant.ofEpochSecond(1540182630L, 1_000_000_000);
    // 通过时间戳数值获取时间，单位为毫秒
    Instant specificInstantByMilli = Instant.ofEpochMilli(1540182630 * 1000L);
    // 通过解析字符串获取时间，默认解析标准为 ISO 8601 。
    Instant specificInstantByStr = Instant.parse("2018-10-22T12:30:00.000Z");

通过 Instant 对象，可以获取到的是时间戳数值。

long timeStampSecond = Instant.now().getEpochSecond();
    long timeStampMill = Instant.now().get(ChronoField.MILLI_OF_SECOND);

对于 Instant 的修改，主要也是用到相关的 plus 方法。

Instant instant1 = instant.plusSeconds(1L);
    Instant instant2 = instant.plusMillis(1000L);
    Instant instant3 = instant.plus(1L, ChronoUnit.SECONDS);

## Duration 和 Period ##

上面提到的相关时间类表示的是时间点，而 Duration 和 Period 是对时间段的抽象。  
Duration 与 Period 的区别在于 Duration 主要是以整数值（秒和纳秒）来表示时间段，而 Period 则是以对人类友好的方式来表示时间段，即一周，一个月，一年等。

Duration 和 Period 可以用一系列 of 开头的静态方法来创建实例。有以下简单的例子：

// 十分钟
    Duration tenMin = Duration.ofMinutes(10);
    // 两周
    Period twoWeek = Period.ofWeeks(2);

然后可以通过这两个对象获取一些简单的信息：

Duration tenMin = Duration.ofMinutes(10);
    long seconds = tenMin.getSeconds();
    
    Period twoWeek = Period.ofWeeks(2);
    int days = twoWeek.getDays();

Duration 和 Period 的一个最常用功能就是它们的静态方法 between ，该方法可以计算两个时间实例之间的时间差。

LocalDateTime nowDateTime = LocalDateTime.now();
    LocalDateTime weekAgoDateTime = nowDateTime.plus(-2, ChronoUnit.WEEKS);
    Duration duration = Duration.between(weekAgoDateTime, nowDateTime);
    System.out.println(duration.getSeconds()); // 1209600
    
    LocalDate nowDate = LocalDate.now();
    LocalDate weekAgoDate = nowDate.plus(-2, ChronoUnit.WEEKS);
    Period period = Period.between(weekAgoDate, nowDate);
    System.out.println(period.getDays()); // 14

注意的是，Duration 的 between 方法只能用于 Instant ，LocalTime 和 LocalDateTime 等对象的时间差计算。而 Period 的 between 方法只能用于 LocalDate 的时间差计算。而且不同的时间类型对象是不可以混用的，如试图计算 LocalDateTime 对象和 Instant 对象之间的时间差。

Duration 对象还有一个常见的用处，那就是作为参数传给各个日期、时间对象的 plus 方法。  
上面提到的各个日期、时间对象的 plus 方法其实在内部都是利用了一个 Duration 对象来计算日期、时间对象修改后的值，当然也可以显示传递一个 Duration 对象。

LocalTime nowTime = LocalTime.now();
    LocalTime afterTenMin = nowTime.plus(Duration.ofMinutes(10));

# 日期、时间对象的修改 #

首先要明确日期、时间对象都是不可变对象，所以“修改”实际上是创建了一个新的对象。  
对于日期、时间对象的修改，最常用的就是它们的 plus 系列方法，在前面关于各个日期、时间对象的介绍中也有提到。除此之外，日期、时间对象还有一系列的 **with** 方法，可以进行相关的时间修改操作。这里以 LocalDate 为例：

// 初始日期为 2018-08-08
    LocalDate date = LocalDate.of(2018, 8, 8);
    // 将年份修改为 2017 年，日期变为 2017-08-08
    LocalDate dateModifyYear = date.withYear(2017);
    // 将月份修改为 9 月，日期变为 2018-09-08
    LocalDate dateModifyMonth = date.withMonth(9);
    // 将日期修改为 15 号，日期变为 2018-08-15
    LocalDate dateModifyDay = date.with(ChronoField.DAY_OF_MONTH, 15);

如果需要更加复杂的修改操作，就需要用到接口 **TemporalAdjuster** 。

@FunctionalInterface
    public interface TemporalAdjuster {
        /**
         * 设置日期变化的逻辑
         * @param temporal 输入的时间对象，即需要进行修改的时间对象
         * @return 输出的时间杜希昂，即修改后的时间对象
         */
        Temporal adjustInto(Temporal temporal);
    }

该接口声明为函数式接口，即可以以函数式编程的方式使用。  
各个日期、时间类都有一个 with 方法，该 with 方法接受一个参数，即 TemporalAdjuster 。修改日期或事件的逻辑就在于接口 TemporalAdjuster 方法 adjustInto 的具体实现。

在 Java 8 的时间 API 中，有不少类都实现了该接口，可以利用这些类完成一些时间修改的操作，而且有工厂类 [TemporalAdjusters][] 实现了不少常用到的时间修改操作。

// 初始日期为 2018-08-08
    LocalDate date = LocalDate.of(2018, 8, 8);
    // 将日期修改为本周五的日期
    LocalDate dateModifyDayOfWeek = date.with(DayOfWeek.FRIDAY);
    // 将日期修改为月初
    LocalDate dateModifyFirstDayOfMonth = date.with(TemporalAdjusters.firstDayOfMonth());

当然除此之外还可以自己实现 TemporalAdjuster 接口，实现自定义的日期、时间修改逻辑。

# 字符串与时间的转换 #

在开发中经常会遇到字符串与日期、时间对象的相互转换的需求，在 Java 8 中，新添加了一个时间格式化类 [DateTimeFormatter][] 专门用于字符串与日期时间的相互转换。

DateTimeFormatter 自身定义了许多静态实例，代表了各种常用的日期时间表示格式，如下：

<table> 
 <thead> 
  <tr> 
   <th>Formatter</th> 
   <th>Description</th> 
   <th>Example</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>BASIC_ISO_DATE</td> 
   <td>Basic ISO date</td> 
   <td>'20111203'</td> 
  </tr> 
  <tr> 
   <td>ISO_LOCAL_DATE</td> 
   <td>ISO Local Date</td> 
   <td>'2011-12-03'</td> 
  </tr> 
  <tr> 
   <td>ISO_OFFSET_DATE</td> 
   <td>ISO Date with offset</td> 
   <td>'2011-12-03+01:00'</td> 
  </tr> 
  <tr> 
   <td>ISO_DATE</td> 
   <td>ISO Date with or without offset</td> 
   <td>'2011-12-03+01:00'; '2011-12-03'</td> 
  </tr> 
  <tr> 
   <td>ISO_LOCAL_TIME</td> 
   <td>Time without offset</td> 
   <td>'10:15:30'</td> 
  </tr> 
  <tr> 
   <td>ISO_OFFSET_TIME</td> 
   <td>Time with offset</td> 
   <td>'10:15:30+01:00'</td> 
  </tr> 
  <tr> 
   <td>ISO_TIME</td> 
   <td>Time with or without offset</td> 
   <td>'10:15:30+01:00'; '10:15:30'</td> 
  </tr> 
  <tr> 
   <td>ISO_LOCAL_DATE_TIME</td> 
   <td>ISO Local Date and Time</td> 
   <td>'2011-12-03T10:15:30'</td> 
  </tr> 
  <tr> 
   <td>ISO_OFFSET_DATE_TIME</td> 
   <td>Date Time with Offset</td> 
   <td>2011-12-03T10:15:30+01:00'</td> 
  </tr> 
  <tr> 
   <td>ISO_ZONED_DATE_TIME</td> 
   <td>Zoned Date Time</td> 
   <td>'2011-12-03T10:15:30+01:00[Europe/Paris]'</td> 
  </tr> 
  <tr> 
   <td>ISO_DATE_TIME</td> 
   <td>Date and time with ZoneId</td> 
   <td>'2011-12-03T10:15:30+01:00[Europe/Paris]'</td> 
  </tr> 
  <tr> 
   <td>ISO_ORDINAL_DATE</td> 
   <td>Year and day of year</td> 
   <td>'2012-337'</td> 
  </tr> 
  <tr> 
   <td>ISO_WEEK_DATE</td> 
   <td>Year and Week</td> 
   <td>2012-W48-6'</td> 
  </tr> 
  <tr> 
   <td>ISO_INSTANT</td> 
   <td>Date and Time of an Instant</td> 
   <td>'2011-12-03T10:15:30Z'</td> 
  </tr> 
  <tr> 
   <td>RFC_1123_DATE_TIME</td> 
   <td>RFC 1123 / RFC 822</td> 
   <td>'Tue, 3 Jun 2008 11:05:30 GMT'</td> 
  </tr> 
 </tbody> 
</table>

## 字符串转换为日期、时间 ##

在前面可以看到，LocalDate ， LocalTime 以及 LocalDate 都可以利用静态方法 parse 将字符串转换为对应的日期、时间对象。而这个 parse 方法就是字符串转换为时间的方法。该方法还可以传递一个 DateTimeFormatter 对象作为解析格式，默认情况下使用的就是 **DateTimeFormatter.ISO\_LOCAL\_DATE** 、**DateTimeFormatter.ISO\_LOCAL\_TIME** ， **DateTimeFormatter.ISO\_LOCAL\_DATE\_TIME** 这三个表示 ISO 8601 标准的对象。

除了可以传递上述提到的静态对象，还可以自定义格式，然后进行字符串的解析，如下：

DateTimeFormatter dateTimeFormatter = DateTimeFormatter.ofPattern("yyyy/MM/dd");
    LocalDate date = LocalDate.parse("2018/08/08", dateTimeFormatter);

## 日期、时间转换为字符串 ##

日期、时间转换为字符串主要是利用 DateTimeFormatter 的 format 方法。有如下示例：

DateTimeFormatter dateTimeFormatter = DateTimeFormatter.ofPattern("yyyy/MM/dd HH:mm:ss");
    String dateTimeStr = dateTimeFormatter.format(LocalDateTime.now());

除了常规的解析外，还可以进行国际化。

DateTimeFormatter formatter = DateTimeFormatter.ofPattern("MMM uuuu", Locale.SIMPLIFIED_CHINESE);
    String dateStr = formatter.format(LocalDate.now());
    System.out.println(dateStR); // 十月 2018

## 更多预定义的格式 ##

除了上面提到定义好的静态实例外，DateTimeFormatter 有三个静态方法 **ofLocalizedDate** ，**ofLocalizedTime** 和 **ofLocalizedDateTime** ，接受参数 FormatStyle 对象。FormatStyle 是一个枚举类，它有以下定义：

public enum FormatStyle {
        /**
         * Full text style, with the most detail.
         * For example, the format might be 'Tuesday, April 12, 1952 AD' or '3:30:42pm PST'.
         */
        FULL,
        /**
         * Long text style, with lots of detail.
         * For example, the format might be 'January 12, 1952'.
         */
        LONG,
        /**
         * Medium text style, with some detail.
         * For example, the format might be 'Jan 12, 1952'.
         */
        MEDIUM,
        /**
         * Short text style, typically numeric.
         * For example, the format might be '12.13.52' or '3:30pm'.
         */
        SHORT;
    }

根据传递的 FormatStyle 不同，获取到的 DateTimeFormatter 也不同，即解析的格式也不同，而且得到的 DateTimeFormatter 是进行了本地化的，有如下例子：

String dateStr = DateTimeFormatter.ofLocalizedDate(FormatStyle.FULL).format(LocalDate.now());
    System.out.println(dateStr); // 2018年10月22日 星期一

三个静态方法中，ofLocalizedDateTime 稍微特别一点，因为它可以接受两个 FormatStyle 对象作为参数，分别对应于解析日期和时间。

String dateStr = DateTimeFormatter
            .ofLocalizedDate(FormatStyle.FULL)
            .format(LocalDate.now());
    System.out.println(dateStr); // 2018年10月22日 星期一

如果不想本地化，可以利用方法 withLocal 方法改变语言。

String dateStr = DateTimeFormatter
            .ofLocalizedDate(FormatStyle.FULL)
            .withLocale(Locale.US)
            .format(LocalDate.now());
    System.out.println(dateStr); // Monday, October 22, 2018

# 时区 #

一个完整的时间表达是包含时区的，同一个时间点，对于不同时区的人来说时间的表达是不一样的，不同的时区，在日期和时间的计算上有不同的标准。  
LocalDate 、LocalTime 和 LocalDateTime 是一种主观上的时间表示方式，对于人来说，同一个 LocalDate 实例所表达的意义是相同的，但是在时间线上，不同的时区在不同的时间点上。

对于时区信息的问题，可以使用类 **ZoneId** ，它由一个地区 ID 来进行标识，利用地区 ID 来获取 ZoneId 的实例，而且是不可变的，地区 ID 为“\{区域\}/\{城市\}”的格式。获取一个 ZoneId 实例：

ZoneId eastEightArea = ZoneId.of("Asia/Shanghai");

还有一种常用的方式是利用它的静态方法 **systemDefault** 来获取本地机器的时区信息：

ZoneId systemZoneId = ZoneId.systemDefault();

对于时区信息的获取，还可以利用UTC/格林尼治时间的固定偏差计算时区。

// 获取东八区时区的两种方式
    ZoneOffset eastNightAreaZoneOffset = ZoneOffset.of("+8");
    ZoneId eastNightAreaZoneId = ZoneId.of("UTC+8");

ZoneOffset 是对时区偏差的抽象，是 ZoneId 的一个子类。如果 ZoneId 不使用“\{区域\}/\{城市\}”的地区 ID 格式，内部将会使用偏差来计算时区。

获取到时区后，可以在相关的日期、时间对象上添加时区信息，构造成一个具有时区信息的日期、时间对象 **ZonedDateTime**。ZonedDateTime 也可以转换为其他日期、时间对象。

ZoneId eastEightArea = ZoneId.of("Asia/Shanghai");
    
    // LocalDate 与 ZonedDateTime 的相互转换
    LocalDate date = LocalDate.now();
    ZonedDateTime zdt1 = date.atStartOfDay(romeZone);
    date = zdt1.toLocalDate();
    
    // LocalDateTime 与 ZonedDateTime 的相互转换
    LocalDateTime dateTime = LocalDateTime.now();
    ZonedDateTime zdt2 = dateTime.atZone(romeZone);
    dateTime = zdt2.toLocalDateTime();
    
    // Instant 与 ZonedDateTime 的相互转换
    Instant instant = Instant.now();
    ZonedDateTime zdt3 = instant.atZone(romeZone);
    instant = zdt3.toInstant();

# 日历系统 #

ISO-8601 日历系统是世界文明日历系统的事实标准，也是 Java 8 时间 API 体系中默认使用的日历系统。除此之外，还有其他的日历系统，如我们常用的农历（可惜的是 Java 8 没提供），不同的日历系统，对时间的表示有所不同。  
接口 [Chronology][] 抽象了日历，相关的日历系统都实现了该接口。对此感兴趣的可以参考其 API 文档。

[ChronoField]: https://docs.oracle.com/javase/8/docs/api/java/time/temporal/ChronoField.html
[TemporalAdjusters]: https://docs.oracle.com/javase/8/docs/api/java/time/temporal/TemporalAdjusters.html
[DateTimeFormatter]: https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html
[Chronology]: https://docs.oracle.com/javase/8/docs/api/java/time/chrono/Chronology.html