编辑“︁Java日期时间格式化”︁（章节）

= Java日期时间格式化 =

'''Java日期时间格式化'''是将日期或时间对象转换为可读字符串（格式化）或反向解析的过程。Java 8引入的`java.time.format.DateTimeFormatter`类提供了线程安全且灵活的格式化工具，取代了旧版`SimpleDateFormat`。

== 核心概念 ==
=== 格式化与解析 ===
* '''格式化'''：将`LocalDate`、`LocalDateTime`等对象 → 字符串（如`"2023-12-25"`）
* '''解析'''：将字符串 → 日期时间对象

=== 预定义格式器 ===
Java提供了三种常用格式器：
<syntaxhighlight lang="java">
// 预定义常量示例
DateTimeFormatter.ISO_LOCAL_DATE      // 格式：2023-12-31
DateTimeFormatter.ISO_LOCAL_TIME      // 格式：23:59:59.999
DateTimeFormatter.ISO_LOCAL_DATE_TIME // 格式：2023-12-31T23:59:59.999
</syntaxhighlight>

== 基础用法 ==
=== 自定义模式 ===
通过模式字符串定义格式：
{| class="wikitable"
|+ 常用模式符号
! 符号 !! 含义 !! 示例
|-
| y || 年份 || 2023 → "23"或"2023"
|-
| M || 月份 || 7 → "7"或"07"
|-
| d || 日 || 5 → "5"或"05"
|-
| H || 小时（24小时制） || 15 → "15"
|-
| m || 分钟 || 8 → "8"或"08"
|-
| s || 秒 || 45 → "45"
|}

<syntaxhighlight lang="java">
DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
LocalDateTime now = LocalDateTime.now();

// 格式化
String formatted = now.format(formatter); // 输出如："2023-08-15 14:30:45"

// 解析
LocalDateTime parsed = LocalDateTime.parse("2023-08-15 14:30:45", formatter);
</syntaxhighlight>

=== 本地化格式 ===
结合`Locale`实现地区特定显示：
<syntaxhighlight lang="java">
DateTimeFormatter frenchFormatter = DateTimeFormatter
    .ofPattern("EEEE, d MMMM yyyy", Locale.FRENCH);
String frenchDate = LocalDate.now().format(frenchFormatter);
// 输出："mercredi, 15 août 2023"
</syntaxhighlight>

== 高级特性 ==
=== 格式器构建器 ===
使用`DateTimeFormatterBuilder`实现复杂格式：
<syntaxhighlight lang="java">
DateTimeFormatter complexFormatter = new DateTimeFormatterBuilder()
    .appendLiteral("订单创建时间：")
    .appendValue(ChronoField.YEAR)
    .appendLiteral("/")
    .appendValue(ChronoField.MONTH_OF_YEAR)
    .appendLiteral("/")
    .appendValue(ChronoField.DAY_OF_MONTH)
    .appendLiteral(" ")
    .appendValue(ChronoField.HOUR_OF_DAY)
    .appendLiteral("时")
    .toFormatter();
// 输出示例："订单创建时间：2023/8/15 14时"
</syntaxhighlight>

=== 解析宽松模式 ===
处理非严格匹配的输入：
<syntaxhighlight lang="java">
DateTimeFormatter lenientFormatter = DateTimeFormatter.ofPattern("yyyy-MM-dd")
    .withResolverStyle(ResolverStyle.LENIENT);
LocalDate.parse("2023-02-30", lenientFormatter); // 自动调整为2023-03-02
</syntaxhighlight>

== 新旧API对比 ==
{| class="wikitable"
|+ `DateTimeFormatter` vs `SimpleDateFormat`
! 特性 !! 新API !! 旧API
|-
| 线程安全 || ✔️ 是 || ❌ 否
|-
| 默认严格解析 || ✔️ 是 || ❌ 否
|-
| 支持纳秒 || ✔️ 是 || ❌ 仅到毫秒
|}

旧版代码示例（不推荐新项目使用）：
<syntaxhighlight lang="java">
SimpleDateFormat oldFormatter = new SimpleDateFormat("yyyy-MM-dd");
Date oldDate = oldFormatter.parse("2023-08-15"); // 返回java.util.Date
</syntaxhighlight>

== 实际应用案例 ==
=== 案例1：日志时间戳格式化 ===
<syntaxhighlight lang="java">
DateTimeFormatter logFormatter = DateTimeFormatter.ofPattern("[yyyy-MM-dd HH:mm:ss.SSS]");
System.out.println(logFormatter.format(LocalDateTime.now()) + " 用户登录成功");
// 输出示例：[2023-08-15 14:30:45.123] 用户登录成功
</syntaxhighlight>

=== 案例2：多语言日期显示 ===
<mermaid>
pie
    title 多语言日期格式使用场景
    "英文界面" : 45
    "中文界面" : 30
    "其他语言" : 25
</mermaid>

<syntaxhighlight lang="java">
public String getLocalizedDate(LocalDate date, Locale locale) {
    return date.format(DateTimeFormatter
        .ofLocalizedDate(FormatStyle.LONG)
        .withLocale(locale));
}
// 调用示例：
// getLocalizedDate(LocalDate.now(), Locale.US) → "August 15, 2023"
// getLocalizedDate(LocalDate.now(), Locale.CHINA) → "2023年8月15日"
</syntaxhighlight>

== 常见问题 ==
=== 问题1：解析失败处理 ===
使用`DateTimeParseException`处理错误输入：
<syntaxhighlight lang="java">
try {
    LocalDate.parse("2023/08/15", DateTimeFormatter.ISO_LOCAL_DATE);
} catch (DateTimeParseException e) {
    System.err.println("日期格式错误，请使用yyyy-MM-dd格式");
}
</syntaxhighlight>

=== 问题2：时区处理 ===
格式化带时区的时间：
<syntaxhighlight lang="java">
ZonedDateTime zdt = ZonedDateTime.now(ZoneId.of("America/New_York"));
DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss z");
// 输出："2023-08-15 02:30:45 EDT"
</syntaxhighlight>

== 最佳实践 ==
1. 对于频繁使用的格式器，应声明为`static final`常量
2. 优先使用`ISO-8601`标准格式（如`2023-08-15T14:30:45Z`）进行数据交换
3. 用户界面显示时再转换为本地化格式
4. 时间戳存储推荐使用`Instant`类型

{{Warning|旧版`SimpleDateFormat`不是线程安全的！在多线程环境中必须为每个线程创建独立实例。}}

== 延伸学习 ==
* 日期时间算术运算（如`plusDays()`、`minusHours()`）
* 时区转换（`ZoneId`和`ZonedDateTime`）
* 时间段计算（`Period`和`Duration`）

[[Category:编程语言]]
[[Category:Java]]
[[Category:Java日期时间api]]