Java Formatter 怎样安全输出本地化日期时间

Java Formatter 适合把日期时间嵌入一段面向用户的模板文本，但要把输出做稳定，关键不是记住更多占位符，而是同时管好三件事：传入什么日期时间对象、格式字符串要求什么字段、由哪个 Locale 决定语言和数字约定。最稳妥的做法是显式传入 Locale，使用带参数索引的 %t 转换符，并把格式异常当成模板配置问题处理。

官方文档：https://docs.oracle.com/en/java/javase/26/docs/api/java.base/java/util/Formatter.html

先把 Locale、模板和时间对象分清楚

我在处理导出文件名、邮件主题和报表标题时，最容易踩的坑是把“语言不同”和“时间不同”当成一件事。Formatter 的职责是解释 printf 风格模板；Locale 负责本地化约定；TemporalAccessor、Calendar、Date 或时间戳负责提供可读取的日期时间字段。

用显式 Locale 固定输出约定

如果一段文本要展示给特定语言的用户，就把 Locale 作为调用方的明确输入，而不是让它从进程环境里“顺便”获得。Formatter 支持在构造器中设置 Locale，也支持在 format 调用时传入 Locale；后者适合同一个 Formatter 需要切换输出语言的场景，前者适合一个对象只服务一种语言约定的场景。

import java.time.ZonedDateTime;
import java.time.ZoneId;
import java.util.Formatter;
import java.util.Locale;

public final class LocalizedDateText {
    public static String render(ZonedDateTime time, Locale locale) {
        // Locale 是业务输入，避免输出随着部署机器的默认环境变化
        StringBuilder text = new StringBuilder();
        try (Formatter formatter = new Formatter(text, locale)) {
            // 同一个时间对象通过参数索引重复使用，减少参数顺序出错
            formatter.format("%1$tA，%1$tY年%1$tm月%1$td日 %1$tH:%1$tM %1$tZ", time);
            return text.toString();
        }
    }

    public static void main(String[] args) {
        // 业务代码显式选择时区，避免把服务器时区误当成用户时区
        ZonedDateTime time = ZonedDateTime.of(2026, 11, 12, 9, 30, 0, 0,
                ZoneId.of("Asia/Shanghai"));
        System.out.println(render(time, Locale.SIMPLIFIED_CHINESE));
    }
}

这里的 %1$ 表示重复引用第一个参数，tA 是本地化的完整星期名，tY、tm、td 分别表达年、月、日，tH 和 tM 表达 24 小时制的时分，tZ 表达时区名称。时间对象带有明确的 ZoneId，Locale 则只负责显示约定，两者不要互相替代。

日期时间转换符怎样选才不容易错

Formatter 的日期时间转换符都以 %t 或 %T 开头，后面再跟一个表示字段或组合格式的字符。大写前缀通常会把结果按当前 Locale 转成大写，不能简单理解成“换一种日期格式”。

如果同一个时间对象被多次引用，优先使用参数索引或 % 复用上一个参数。这样不仅少写参数，还能避免模板改动后参数顺序悄悄错位。

import java.time.Instant;
import java.util.Formatter;
import java.util.Locale;

public class FormatterReuse {
    public static String summary(Instant instant) {
        // 使用固定 Locale，保证英文月份和星期不会随主机环境漂移
        try (Formatter formatter = new Formatter(Locale.US)) {
            // %1$ 让日期、时间和时区都读取同一个参数
            return formatter.format("%1$tB %1$td, %1$tY %1$tT %1$tZ", instant)
                    .toString();
        }
    }
}

对于给机器读取的协议字段，通常应选择明确的 ISO 形式或专门的日期时间格式化器；对于邮件标题、报表说明、通知文案这类模板文本，Formatter 的 %t 转换符更直接。

默认 Locale 和格式异常是两类不同问题

没有显式指定 Locale 时，Formatter 会使用构造器或本次调用没有覆盖的默认 Locale。开发机和生产机的默认 Locale 不一致，就可能出现月份语言、大小写、数字小数点或分组分隔符变化。这个问题不一定立即报错，却会让同一份模板产生不同文本。

另一类问题是格式字符串本身不合法，例如把日期转换符用于不支持日期字段的对象、给日期转换提供精度、使用未知转换字符，或者宽度与标志组合不符合规则。这些情况会抛出 IllegalFormatConversionException、UnknownFormatConversionException、IllegalFormatPrecisionException 等异常。

import java.time.LocalDate;
import java.util.Locale;

public class FormatBoundary {
    public static String safeDate(LocalDate date, Locale locale) {
        try {
            // 显式 Locale 只影响显示规则，LocalDate 仍只提供日期字段
            return String.format(locale, "%1$tY-%1$tm-%1$td", date);
        } catch (IllegalArgumentException ex) {
            // 模板来自配置时，把异常转换成带上下文的业务错误
            throw new IllegalStateException("日期格式模板或 Locale 配置无效", ex);
        }
    }
}

捕获异常并不意味着把错误吞掉。更好的做法是让错误带上模板来源、业务场景和输入 Locale，便于在配置中心或日志中快速定位；如果模板是编译期常量，则应优先在测试中覆盖它，而不是在线上依赖兜底。

Formatter 什么时候值得用，什么时候应该换工具

Formatter 的优势是模板表达力强，能把日期时间、数字、文本和参数索引放在一条字符串里，特别适合通知文案、报表标题和命令行输出。它的代价也很明确：格式字符串是运行时解释的，类型不匹配才暴露问题；Formatter 实例也不保证多线程安全，因此不要把可变实例当成全局共享状态。

为什么同一模板在不同服务器输出不同？

优先检查是否遗漏显式 Locale，以及日期时间对象是否使用了服务器默认时区。Locale 影响显示约定，时区影响实际的日期时间字段，它们要分开排查。

Formatter 能不能缓存成一个静态对象？

不建议共享一个可变 Formatter 给多个线程使用。Formatter 的线程安全由调用方负责；短文本场景可以按调用创建，或由更高层的线程隔离策略管理。

为什么日期转换不能写精度？

日期时间转换的精度不适用，给这类转换附加精度会触发格式异常。需要控制小数秒、截断或舍入时，应先在时间对象层面完成，再交给模板输出。

实际落地时可以保留一条简单规则：Locale 是显示约定，时区是时间语义，格式字符串是文本模板，异常是模板与输入不匹配的信号。把四者分开管理，Formatter 就能稳定地服务于本地化日期时间文本。