Java Formatter 位置参数怎样复用同一个值

Java Formatter 要复用同一个参数，最稳妥的写法是给格式说明符加显式位置：第一个参数写成 %1$s，第二个参数写成 %2$s。同一个位置可以出现多次，也可以调整输出顺序。如果只是连续复用前一个说明符对应的参数，则可以使用 %。普通的 %s 会按出现顺序消耗参数，适合参数只使用一次的简单格式。

官方地址：https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/Formatter.html

这三种索引方式不要混着凭感觉写。先决定格式串是否需要复用或重排，再选择显式位置或相对位置，能明显降低后续增加字段时的错位风险。

先分清 Formatter 的三种参数索引

Formatter 的格式说明符大致可以看成“参数索引 + 标志 + 宽度 + 精度 + 转换符”。参数索引有三种形态：

显式索引从 1$ 开始，不是从 0$ 开始。它描述的是参数列表中的位置，而不是格式串中第几个占位符。

用 1$ 复用同一个参数并调整顺序

例如订单摘要需要把订单号显示两次，同时把状态放到开头，可以直接引用同一位置：

import java.util.Locale;

public class FormatterReuseDemo {
    public static void main(String[] args) {
        String orderId = "A-1024";
        String status = "已发货";

        // 1$ 指向第一个参数，2$ 指向第二个参数；同一参数可重复引用。
        String text = String.format(Locale.ROOT,
                "状态=%2$s，订单=%1$s，追踪单仍属于=%1$s",
                orderId, status);
        System.out.println(text);
    }
}

这里的 %1$s 两次都读取 orderId，%2$s 读取 status。即使把状态字段插入到格式串前面，参数绑定也不会像普通索引那样整体后移。

用

日期和时间是相对索引很合适的例子：同一个 Date 对象可以分别取月份、日期和年份，而不必重复写 1$。

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

public class RelativeIndexDemo {
    public static void main(String[] args) {
        LocalDate date = LocalDate.of(2026, 11, 1);

        // 第一个说明符使用 date，后面的 

依赖“前一个格式说明符已经选中过参数”。如果把它放在格式串开头，或者前面只有字面文本，就没有可复用的参数，会抛出 MissingFormatArgumentException。需要跨越多个无关说明符，或团队更看重显式可读性时，优先使用 1$。

混用时注意参数错位与异常

普通索引会自动推进参数位置。下面的格式串中，前两个说明符消耗第 1、2 个参数，显式索引则直接回到第 1 个参数：

public class MixedIndexDemo {
    public static void main(String[] args) {
        // 普通索引先取 name，再取 count；显式索引再次取 name。
        String text = String.format("%s 有 %d 条消息，标题再次写作 %1$s",
                "通知", 3);
        System.out.println(text);
    }
}

这种混用虽然合法，但阅读成本更高。建议一条格式串优先采用一种主策略：需要复用或重排就全部使用显式位置；只在紧邻的同一参数多次格式化时使用 。还要记住，参数编号为零、编号超出参数数量、转换符与参数类型不匹配，都可能触发 IllegalFormatException 的具体子类。

记住这三个选择原则

• 一次性顺序输出：使用 %s、%d 等普通索引。
• 需要复用、重排或长期维护：使用 %1$s、%2$s 这样的显式索引。
• 同一对象紧邻输出多个日期或数字形态：可以使用 %，但不要让它跨越复杂逻辑。

最终可以把格式串当成一个小型模板：显式索引负责稳定绑定，相对索引负责局部复用，普通索引负责最简单的线性场景。

常见问题

位置参数为什么从 1 开始？ Java Formatter 的参数索引定义为参数列表中的十进制位置，第一个参数就是 1$，不是数组式的 0$。

%1$s 和 % 哪个更好？ 前者依赖明确编号，适合重排和长期维护；后者依赖前一个说明符，适合紧凑地连续复用同一参数。