Java 的可变参数（varargs）是什么？有哪些使用陷阱？

简化版

可变参数（varargs，类型... 参数名）让方法能接收任意个同类型参数——如 void print(String... args)，可以 print()、print("a")、print("a","b","c") 都行。它的本质是语法糖：编译器把 String... 当成 String[]，调用时自动把你传的多个参数打包成一个数组。所以在方法体里 args 就是个数组。常见陷阱：① 可变参数必须是方法的最后一个参数（否则编译器无法区分边界）；② 和重载一起用会有歧义（print("a") 到底调 print(String) 还是 print(String...)——优先精确匹配的非可变参数版本）；③ 传 null 或数组时有歧义（print(null) 可能被当成「传一个 null 数组」而非「传一个 null 元素」）；④ 泛型可变参数有堆污染警告。

详细版

基本用法：

void print(String... args) {   // args 在方法体里就是 String[]
    for (String s : args) { ... }
    System.out.println(args.length);
}
print();                 // args = 空数组 []（不是 null！）
print("a");              // args = ["a"]
print("a", "b", "c");    // args = ["a","b","c"]
print(new String[]{"x"}); // 也可以直接传数组

本质是语法糖——编译器把可变参数当数组处理：

你写：   print("a", "b", "c")
编译后： print(new String[]{"a", "b", "c"})   // 自动打包成数组
所以方法签名 void print(String... args) 编译后是 void print(String[] args)

四个陷阱：

// 陷阱1：可变参数必须放最后
void f(String... args, int x)  // ✗ 编译错误
void f(int x, String... args)  // ✓ 可变参数在最后

// 陷阱2：重载歧义——优先非可变参数的精确匹配
void g(String s) { print("单个"); }
void g(String... s) { print("可变"); }
g("a");   // 调 g(String)——精确匹配优先于可变参数

// 陷阱3：传 null 的歧义
void h(String... args) { }
h(null);              // ⚠️ 警告：null 被当成"整个数组是 null"（args = null，遍历会 NPE）
h((String) null);     // ✓ 明确：传一个 null 元素（args = [null]）

// 陷阱4：泛型可变参数——堆污染
@SafeVarargs   // 确认安全时用此注解压制警告
<T> void j(T... args) { }   // 泛型 + 可变参数会有 "unchecked/varargs" 警告

⚠️ print(null) 是个隐蔽的坑——因为可变参数底层是数组，null 既可以理解为「传一个 null 数组」（args == null），也可以理解为「传一个 null 元素」（args == [null]）。编译器默认按前者（整个数组为 null），此时方法体里 args.length 或遍历会抛 NPE。要传「一个 null 元素」得显式转型 (String) null。所以可变参数方法要防御性判断 args == null。

完整版教学

一、可变参数解决什么：不定个数的参数

有些方法需要接收「不定个数的同类型参数」——最典型的是 String.format、Arrays.asList、日志方法 log.info(msg, args...)。在可变参数之前，只能用两种笨办法：

没有可变参数时的做法：
  ① 重载一堆方法：f(a), f(a,b), f(a,b,c)... 参数个数无法穷举，很快就不够用
  ② 让调用方自己传数组：f(new String[]{a,b,c}) —— 调用方每次都要手动 new 数组，繁琐

可变参数（Java 5 引入）：
  f(String... args) —— 调用方直接 f(a,b,c)，个数随意，编译器帮你打包成数组

可变参数的价值是「让方法能优雅地接收任意个参数」——调用方写 f(a, b, c) 就行（不用手动 new 数组），方法定义只写一个 String... args（不用重载一堆）。它本质是「让编译器帮你做『打包成数组』这件事」的语法糖。理解「可变参数是为了优雅接收不定个数参数、本质是自动打包成数组」，就理解了它的定位——它不是新机制，而是数组传参的便利写法。

二、本质：编译器打包成数组

可变参数最核心的认知是——它就是数组的语法糖。编译器在两个地方做了转换：

① 方法定义处：String... args 编译后就是 String[] args
   所以方法体里 args 是个真正的数组（能 .length、能遍历、能下标访问）

② 方法调用处：把你传的多个参数自动打包成数组
   print("a", "b", "c") 编译后 → print(new String[]{"a", "b", "c"})
   print() 编译后 → print(new String[]{})   // 空数组，不是 null

关键推论：因为底层是数组，可变参数的很多「陷阱」都能从「它是数组」推出来——比如「传 null 有歧义」（数组本身可以是 null）、「能直接传数组」（本来就是数组）、「空调用得到空数组不是 null」（打包成空数组）。理解「可变参数 = 编译期自动打包的数组」，就掌握了它的本质，后面的陷阱都是这个本质的自然结果。也正因为每次调用都可能 new 一个数组，可变参数在极高频调用的热路径上有轻微的数组创建开销（一般可忽略）。

三、陷阱一：必须是最后一个参数

可变参数必须是方法的最后一个参数，且一个方法只能有一个可变参数：

void f(int x, String... args)   // ✓ 可变参数在最后
void f(String... args, int x)   // ✗ 编译错误
void f(String... a, int... b)   // ✗ 编译错误（不能有两个可变参数）

原因很直接：可变参数会「吃掉」剩余的所有参数——编译器要靠「它是最后一个」来确定「从哪里开始的参数打包进这个数组」。如果 f(String... args, int x) 合法，编译器就无法判断 f("a", "b", 1) 里哪些属于 args、哪个是 x（边界不清）。把可变参数放最后，边界就明确了：前面固定参数按位置对应，剩下的全打包进可变参数。理解「可变参数放最后是为了确定参数边界」，就理解了这个语法约束的必然性。

四、陷阱二：与重载的歧义

可变参数和普通重载一起用时，会有「调哪个」的歧义，规则是精确匹配（非可变参数）优先于可变参数：

void g(String s) { print("单个"); }
void g(String... s) { print("可变"); }

g("a");        // 调 g(String)——精确匹配的固定参数版本优先
g("a", "b");   // 调 g(String...)——两个参数只有可变版本能接
g();           // 调 g(String...)——空参数只有可变版本能接

规则背后的逻辑：编译器选重载时，可变参数是「最后的兜底」——先看有没有「参数个数和类型精确匹配的固定参数版本」，有就用它；没有才考虑可变参数版本。这是因为可变参数版本「太宽泛」（能匹配任意个），如果它和固定版本同等优先，会造成大量歧义。所以 Java 规定「固定参数版本优先」。这也提醒：同时定义固定和可变重载时要小心——g("a") 走固定版本、g("a","b") 走可变版本，行为可能不一致。理解「精确匹配优先、可变参数兜底」，就能预判重载时调哪个。

五、陷阱三：传 null 和传数组的歧义

因为底层是数组，null 和「直接传数组」都有歧义，这是最隐蔽的坑：

void h(String... args) {
    System.out.println(args == null ? "null" : args.length);
}

h(null);              // 输出 "null"！null 被当成"整个数组是 null"
                      //   → 若方法体遍历 args 会 NPE
h((String) null);     // 输出 "1"！显式转型 → 传"一个 null 元素"，args = [null]
h(new String[]{"a"}); // 输出 "1"——直接传数组，args 就是这个数组
h("a", "b");          // 输出 "2"——正常打包

两个歧义点：① h(null)——null 优先被解释为「传一个 null 数组」（args == null），而不是「传一个 null 元素」；要传 null 元素得 (String) null。② h(数组)——可变参数能直接接收一个数组（因为它本来就是数组），所以传数组时 args 就是那个数组、不会再包一层。这两个歧义都源于「可变参数是数组」——数组本身可以为 null、可以直接传。防御做法：可变参数方法开头判断 args == null。理解「null 优先当空数组、能直接传数组」，就能避开这个 NPE 陷阱。

六、陷阱四：泛型可变参数的堆污染

泛型和可变参数一起用，会有「堆污染（heap pollution）」的编译警告：

@SafeVarargs   // 断言「我保证这个可变参数用得安全」，压制警告
static <T> List<T> asList(T... args) {   // 泛型可变参数
    return Arrays.asList(args);
}
// 不加 @SafeVarargs 会有 "unchecked generic array creation for varargs" 警告

原因：泛型有类型擦除、数组有协变，两者冲突会产生「堆污染」隐患——泛型可变参数 T... args 底层要创建一个泛型数组 T[]，但 Java 不允许直接创建泛型数组（擦除后无法保证类型安全），编译器只能创建一个「擦除后的数组」并给出警告。如果方法内部对这个数组做了不安全的操作（如往里存了错误类型），运行时可能出 ClassCastException。@SafeVarargs 注解是开发者的「安全声明」——「我保证这个方法只是读取可变参数、没有不安全操作」，用它压制警告（能加在 static/final/private 方法上）。理解「泛型可变参数因擦除+数组协变有堆污染警告、用 @SafeVarargs 声明安全」，就掌握了这个进阶陷阱（Arrays.asList、List.of 都用了 @SafeVarargs）。

记忆钩子：「可变参数（类型… 参数）本质是编译器自动打包成数组的语法糖（方法体里就是数组、空调用得空数组非 null）；四陷阱：必须放最后（定边界）、重载时精确匹配优先于可变（可变兜底）、传 null 优先当空数组（要传 null 元素得 (T)null）、泛型可变参数有堆污染警告（用 @SafeVarargs 声明安全）」。

七、常见误区与追问

误区：可变参数是一种特殊的新参数机制。 它是数组的语法糖——编译器把 T... 当 T[]、调用时自动打包成数组，方法体里就是普通数组。
误区：不传参数时可变参数是 null。 是空数组（new T[]{}）不是 null；print() 的 args 是长度 0 的数组，可以正常 .length 和遍历。
误区：h(null) 会传一个 null 元素。 会被当成「整个数组是 null」（args == null，遍历 NPE）；要传一个 null 元素得显式转型 (String) null。
误区：可变参数可以放在参数列表任意位置。 必须是最后一个参数（否则边界不清），且一个方法只能有一个可变参数。
追问：可变参数和重载一起用，g("a") 调固定版本还是可变版本？ 调固定版本——精确匹配的非可变参数版本优先，可变参数版本是「兜底」（只有固定版本接不了时才用它）。
追问：为什么可变参数底层是数组？ Java 5 为了兼容和简单，用「编译器自动打包成数组」实现可变参数——方法定义 T... 编译成 T[]、调用处把多个参数打包成数组传入，所以方法体里操作的就是数组。
追问：@SafeVarargs 是干什么的？ 泛型可变参数因类型擦除+数组协变会有「堆污染」警告；@SafeVarargs 是开发者声明「这个可变参数方法用得安全（只读不做不安全操作）」来压制警告，加在 static/final/private 方法上。

八、加强记忆

可变参数（varargs，类型... 参数名，Java 5）让方法接收任意个同类型参数（print(a,b,c) 个数随意），本质是语法糖——编译器把 T... 当 T[]、调用时把多个参数自动打包成数组，所以方法体里就是普通数组（空调用得空数组不是 null）。它的四个陷阱都能从「底层是数组」推出：① 必须是最后一个参数（且只能有一个，因为要靠「最后」确定参数边界）；② 和重载一起时精确匹配的固定参数版本优先、可变参数版本兜底（g("a") 走 g(String)）；③ 传 null 优先被当成「整个数组是 null」（args==null，遍历 NPE；要传 null 元素得 (T)null），且能直接传数组；④ 泛型可变参数因类型擦除+数组协变有「堆污染」警告，用 @SafeVarargs 声明安全压制。防御做法是方法开头判 args == null。一句话「可变参数是自动打包成数组的语法糖、放最后、重载精确优先、null 当空数组、泛型有堆污染用 @SafeVarargs」。

简化版

详细版