java.time日期/时间API包总结

Java 8日期、时间API包总结

---

1 JSR310介绍

JSR 310实际上有两个日期概念：

1. 第一个是Instant，大致对应于 java.util.Date 类，因为它代表一个确定的时间点，即相对于标准Java纪元（1970 年 1 月 1 日）的偏移量；但与java.util.Date类不同，其精确到了纳秒级别。
2. 第二个对应于人类自身的观念，如LocalDate和LocalTime，代表一般的时区概念，要么是日期（不含时间），要么是时间（不含日期），类似于java.sql的表示方式。此外还有一个MonthDay，可以存储某人的生日（不含年份）。每个类都在内部存储正确的数据而不是像java.util.Date那样利用午夜12点来区分日期，利用1970-01-01来表示时间。

Java 8实现了JSR310的全部内容，新增的java.time包中定义的类表示了日期-时间概念的规则，包括Instant、Duration、Date、Time、TimeZone和Period。这些都基于ISO日历系统，并遵循Gregorian规则。最重要的一点是值不可变，且线程安全。java.time包下一些主要类的值的格式如下图所示

---

2 Java 8日期/时间特性

Java 8日期/时间API的实现目标是克服旧的日期时间实现中所有的缺陷，新的日期/时间API的一些设计原则如下：

• 不变性：新的日期/时间 API 中，所有的类都是不可变的，这对多线程环境有好处。
• 关注点分离：新的 API 将人可读的日期时间和机器时间（Unix Timestamp）明确分离，它为日期（Date）、时间 （Time）、日期时间（DateTime）、时间戳（unix timestamp）以及时区定义了不同的类。
• 清晰：在所有的类中，方法都被明确定义用以完成相同的行为。例如，要拿到当前实例可以使用now()方 法，在所有的类中都定义了format()和parse()方法，而不是像以前那样专门有一个独立的类。为了更好的处理问题，所有的类都使用了工厂模式和策略模式，一旦你使用了其中某个类的方法，与其他类协同工作并不困难。
• 实用操作：所有新的日期/时间 API 类都实现了一系列方法用以完成通用的任务，如：加、减、格式化、解析、从日期/时间中提取单独部分等。
• 可扩展性：新的日期/时间API默认工作在ISO-8601日历系统上，但也可以将其应用在非ISO的日历上。

Java 8常用的日期/时间API包如下所示：

1. java.time包：新的Java日期/时间API的基础包，所有的主要基础类都是这个包的一部分，如：LocalDate、LocalTime、LocalDateTime、Instant、Period、Duration等。所有这些类都是不可变的和线程安全的，在绝大多数情况下，这些类能够有效地处理一些公共的需求。
2. java.time.chrono包：为非ISO的日历系统定义了一些泛化的API，可以扩展AbstractChronology类来创建自己的日历系统。
3. java.time.format包：这个包包含能够格式化和解析日期时间对象的类，在绝大多数情况下，我们不应该直接使 用它们，因为 java.time 包中相应的类已经提供了格式化和解析的方法。
4. java.time.temporal包：这个包包含一些时态对象，可以用其找出关于日期/时间对象的某个特定日期或时间， 例如，找到某月的第一天或最后一天。这些方法都具有“withXXX”的格 式，可以非常容易地认出。
5. java.time.zone包：这个包包含支持不同时区以及相关规则的类。

---

3 日期/时间常用API

java.time包下的方法概览

方法名	说明
of	静态工厂方法
parse	静态工厂方法，关注于解析
get	获取某事物的值
is	检查某事物是否为true
with	不可变的setter等价物
plus	加一些量到某个对象
minus	从某个对象减去一些量
to	转换到另一个类型
at	把这个对象与另一个对象组合起来

如果提供无效的参数去创建日期/时间， 系统会抛出异常java.time.DateTimeException。

支持通过传入ZoneId得到指定时区的日期/时间数据，可以从其Javadoc中得到支持的Zoneid列表。

3.1 java.time.LocalDate

LocalDate是一个不可变的类，它表示默认格式yyyy-MM-dd的日期，可以使用now()方法得到当前时间，也可以提供输入年份、月份和日期的输入参数来创建一个LocalDate实例。该类为now()方法提供了重载方法，可以传入ZoneId来获得指定时区的日期。该类提供与java.sql.Date相同的功能。

// Current date
LocalDate today = LocalDate.now();
System.out.println("Current date: " + today);

// Creating LocalDate by providing input arguments
LocalDate firstDay_2024 = LocalDate.of(2024, Month.JANUARY, 1);
System.out.println("Specific date: " + firstDay_2024);

// Current date in "Asia/Shanghai", you can get it from ZoneId javadoc
LocalDate todayShanghai = LocalDate.now(ZoneId.of("Asia/Shanghai"));
System.out.println("Current date in CTT: " + todayShanghai);

// Getting date from the base date i.e. 01/01/1970
LocalDate dateFromBase = LocalDate.ofEpochDay(365);
System.out.println("365th day from the base date: " + dateFromBase);

LocalDate hundredDay_2024 = LocalDate.ofYearDay(2014, 100);
System.out.println("100th day of 2024: " + hundredDay_2024);

3.2 java.time.LocalTime

LocalTime是一个不可变的类，它的实例代表一个符合人类可读格式的时间， 默认格式为hh:mm:ss.zzz。 像LocalDate一样，该类也提供了时区支持，同时也可以传入小时、分钟和秒等输入参数创建实例。

// Current time
LocalTime time = LocalTime.now();
System.out.println("Current Time: " + time);

// Creating LocalTime by providing input arguments
LocalTime specificTime = LocalTime.of(12, 20, 25, 40);
System.out.println("Specific time of day: " + specificTime);

// Current date in "Asia/Shanghai", you can get it from ZoneId javadoc
LocalTime timeShanghai = LocalTime.now(ZoneId.of("Asia/Shanghai"));
System.out.println("Current time in CTT: " + timeShanghai);

// Getting date from the base date i.e. 01/01/1970
LocalTime specificSecondTime = LocalTime.ofSecondOfDay(10000);
System.out.println("10000th second time: " + specificSecondTime);

3.3 java.time.LocalDateTime

LocalDateTime是一个不可变的日期-时间对象，它表示一组日期-时间，默认格式为yyyy-MM-dd-HH-mmss.zzz。它提供了一个工厂方法，接收LocalDate和LocalTime输入参数，创建LocalDateTime实例。

// Current date
LocalDateTime today = LocalDateTime.now(