Java String.formatted 处理占位符与参数类型的实现方式

Java 15 起，字符串实例可以直接调用 formatted(Object... args) 完成格式化：把模板放在左侧，把参数按占位符顺序传入即可。它适合日志片段、提示语和已经拿到模板字符串的场景；如果模板与参数分开保存，仍可以使用静态的 String.format。

官方地址：https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/lang/String.html

记住一条规则：%s 主要接收通用对象，%d 面向整数，%f 面向浮点数；占位符数量、顺序和参数类型对不上时，问题会在运行期以 IllegalFormatException 体系异常暴露。

最小写法：让字符串实例承担格式模板

formatted 是实例方法，所以格式字符串写在点号左侧。参数是可变参数，调用时会被收集成 Object...，再交给 Java 的格式化规则处理。

public class FormattedIntro {
    public static void main(String[] args) {
        // 模板中的第一个占位符读取 name，第二个占位符读取 count。
        String message = "任务 %s 已处理 %d 条".formatted("导入订单", 12);
        System.out.println(message);
    }
}

上面的调用把 "导入订单" 放到 %s，把整数 12 放到 %d。格式字符串中的普通文字不会参与参数匹配，只有格式说明符会消耗参数。

占位符与参数类型要一一对应

常见转换符可以先按“接收什么类型”来记：

%s 的适用范围最宽，普通对象会通过字符串表示参与输出；但这不意味着所有转换符都可以随意替换。比如 %d 需要整数类别，浮点数应使用 %f，日期时间则要使用对应的 %t 前缀和后缀。

import java.math.BigDecimal;

public class FormattedTypes {
    public static void main(String[] args) {
        int total = 8;
        BigDecimal amount = new BigDecimal("19.90");

        // %d 读取整数，%.2f 保留两位小数；参数顺序要和占位符顺序一致。
        String line = "数量=%d，金额=%.2f，状态=%s".formatted(total, amount, "待处理");
        System.out.println(line);
    }
}

在实际项目里，建议先把每个占位符写成一张小表，再从左到右核对参数。这样比只盯着一长串 Object... 更容易发现错位。

参数少了、多了或类型不对时会发生什么

格式化不是编译期类型检查。模板和参数都是运行期数据，因此数量和类型问题通常要到调用发生时才暴露。

public class FormattedErrors {
    public static void main(String[] args) {
        // 参数数量不足：第二个占位符找不到对应值。
        String missing = "用户=%s，数量=%d".formatted("小王");

        // 类型不匹配：%d 不能按整数转换规则处理字符串。
        String incompatible = "数量=%d".formatted("12");
    }
}

这两种情况都不应靠“多传几个参数”掩盖。官方 Formatter 规则允许多余参数被忽略，但这往往表示模板和调用方已经失去同步；更稳妥的做法是删除无用参数，或者让模板与参数在同一个方法边界内生成。

排查时按下面顺序看：

1. 从左到右数格式说明符，注意 %% 和 %n 不需要业务参数。
2. 确认显式索引如 %2$s 是否跳过了默认顺序。
3. 确认 %d 的值是不是整数类别，%f 的值是不是浮点类别。
4. 查看异常的具体子类，例如转换不兼容通常会落在 IllegalFormatConversionException。

String.formatted 与 String.format 怎么选

两者的格式规则是一套。Oracle 的 String API 明确说明，formatted 等价于 String.format(this, args)；主要差异是模板放置位置。

import java.util.Locale;

public class FormattedChoice {
    public static void main(String[] args) {
        String template = "价格：%.2f";
        double price = 19.9;

        // 模板已经是一个字符串实例时，实例方法更直观。
        String byInstance = template.formatted(price);

        // 需要显式指定 Locale 时，使用带 Locale 的静态方法。
        String byStatic = String.format(Locale.ROOT, template, price);

        System.out.println(byInstance);
        System.out.println(byStatic);
    }
}

如果只需要默认格式区域，实例方法可以减少一层视觉噪声；如果需要把 Locale 作为调用参数、或者模板和参数在不同变量中维护，静态方法更清楚。两者都不是国际化模板框架，也不会自动替你管理翻译键。

项目中采用时的边界

• 最低运行环境要覆盖 Java 15，因为 formatted 的 API 起始版本是 15。
• 把模板与参数放在同一个方法附近，减少字段名、占位符和参数列表分离造成的错位。
• 对用户输入只做格式化，不要把 formatted 当作 SQL、HTML 或命令拼接的安全边界。
• 需要稳定地区域化数字或日期时，优先明确传入 Locale 并保留相应的回归用例。

简要选择：模板是现成字符串且不需要额外区域设置，用 template.formatted(args)；模板与参数分离或要显式指定区域设置，用 String.format(locale, template, args)。无论选哪一种，都先核对占位符数量、索引和转换类型。

相关问题

String.formatted 支持命名占位符吗？不支持。它使用 Formatter 的格式说明符和可选参数索引，不是命名模板语法。

为什么字符串参数通常用 %s？%s 属于通用转换，会使用对象的字符串表示；它适合文本，但不等同于对对象做结构化序列化。

多传一个参数一定报错吗？不一定，格式规则允许多余参数被忽略；但代码可维护性上，最好让参数列表与模板严格对应。