error-prone 的 AvoidObjectArrays 检查：用集合代替对象数组的 API 设计规范-开发者社区

静态分析
代码质量
开发工具

【免费下载链接】error-prone

Catch common Java mistakes as compile-time errors

项目地址：https://gitcode.com/gh_mirrors/er/error-prone

本篇技术指南围绕 error-prone 内置检查器AvoidObjectArrays展开，讲解它为何要求开发者用List、Set、Iterable等集合替代方法参数与返回值中的对象数组，以及该检查器在源码中的实现规则、诊断消息格式、边界豁免场景和启用方式。阅读完成后，你将能准确理解该检查的触发条件，在自己的项目中正确启用并落实"集合优于数组"的 Java API 设计规范。

核心思想：为什么对象数组劣于集合

官方文档给出的论断非常直接：对象数组在几乎所有方面都劣于集合，只要可能，就优先使用Set、List或Multiset，而不是对象数组。这一问题在《Effective Java》第 28 条（"Prefer lists to arrays"）中有更详尽的阐述。

检查器的@BugPattern注解摘要（AvoidObjectArrays.java）也复述了同样的立场，并进一步明确推荐不可变集合：

Object arrays are inferior to collections in almost every way. Prefer immutable collections (e.g., ImmutableSet, ImmutableList, etc.) over an object array whenever possible.

从类型系统的角度，数组与集合的差异主要在于：

协变性的安全隐患：数组是协变的（String[]是Object[]的子类型），运行时才会抛出ArrayStoreException；而泛型集合是不变的，编译期就能捕获类型错误。
类型信息缺失：对象数组无法携带泛型参数，经过Object[]传递后元素类型信息会丢失。
可变性风险：普通数组可以被任意修改，而ImmutableList、ImmutableSet等不可变集合天然不可修改，更利于跨 API 边界传递。

注意这里的限定词是"对象数组"（object array）：原始类型数组（如int[]、double[]）不在本检查范围内，它们往往有无法被集合替代的性能与语义用途。这一点在源码和测试中都有明确体现，下文会详细说明。

检查规则全览：检查什么、放行什么

AvoidObjectArrays在源码中是一个实现了MethodTreeMatcher的BugChecker（AvoidObjectArrays.java），即它只针对方法声明（MethodTree）做检查，且只检查公开且未被重写的方法（methodIsPublicAndNotAnOverride，见shouldApplyApiChecks）。

可以把它理解为一道面向公开 API 形态的检查：它关注的是"别人调用你的方法时拿到的/传进来的是数组还是集合"。

检查维度	行为	诊断建议
方法返回类型是对象数组	报告	建议改为`ImmutableList`
方法参数是对象数组	报告	建议改为`Iterable`
原始类型数组（`int[]`等）	不报告	—
二维及以上对象数组（`String[][]`）	报告	只提示避免，不给出具体替代类型

同时，shouldApplyApiChecks（源码）定义了一组明确的豁免条件，满足任一条件即跳过检查：

main方法：public static void main(String[] args)的String[] args是 JVM 约定，必须保留；
框架参数化注解方法：被com.tngtech.java.junit.dataprovider.DataProvider、org.junit.runners.Parameterized.Parameters、org.junit.experimental.theories.DataPoints、junitparams.Parameters注解的方法（ANNOTATIONS_TO_IGNORE集合，源码）不检查——这类 JUnit/TestNG 数据提供方法天然以Object[]形式返回测试数据；
注解类型内部的方法：例如@interface TestAnnotation { String[] value(); }，注解元素的数组形态是注解语法要求；
被重写的方法：如果父类方法已经使用了数组返回类型，子类的@Override实现不再重复报告（测试注释明确写道 "we intentionally don't complain about this API since it's the parent class's fault"）。

在参数检查中还有两条参数级别的放行规则（matchMethod 实现）：

可变参数（varargs）：若对象数组参数是最后一个参数且方法声明为 varargs（如void varArgs(String... strings)），则放行，因为可变参数必须编译为数组形态；
已有Iterable重载：如果该类同时存在一个"仅有一个Iterable类型参数"的同名重载（如 Guava Truth 的containsAnyIn(Iterable<?>)与containsAnyIn(Object[])），则数组版本的重载被放行，避免与既有 API 冲突。

此外，源码注释中还留有一个未来可能的放宽方向：String[] args这类"命令行参数传递"用法或许会被允许作为方法参数，目前仍按常规报告。

场景一：方法参数不要使用对象数组

官方文档给出的反例与正例：

// 反例：不推荐 public void createUsers(User[] users) { ... } // 正例：改用 Iterable public void createUsers(Iterable<User> users) { ... }

参数建议使用Iterable而不是具体的List/Set，是因为Iterable是"可被遍历的集合"这一语义的最小抽象，调用方可以自由传入任何集合实现，方法的适用面最广。

该行为在测试中有完整覆盖。以 AvoidObjectArraysTest.java 的methodParam_instanceMethods为例：

public class ArrayUsage { // BUG: Diagnostic contains: consider an Iterable<Object> instead public void objectArray(Object[] objectArray) {} // BUG: Diagnostic contains: consider an Iterable<String> instead public void stringArray(String[] stringArray) {} public void intArray(int[] intArray) {} // 原始类型数组，不报告 public void objectValue(Object objectValue) {} // 非数组，不报告 }

静态方法（methodParam_staticMethods）的行为完全一致；varArgs测试则验证了"varargs 放行、非 varargs 数组参数仍报告"的规则：

public void varArgs(String... strings) {} // 放行 // BUG: Diagnostic contains: consider an Iterable<Class> instead public void varArgs(Class[] clazz, String... strings) {} // 第一个参数是数组，报告

另外stringArrayNamedArgs测试表明，即便参数名是args、argv、argz，只要不是main方法的形参，String[]依然会被报告：

// BUG: Diagnostic contains: consider an Iterable<String> instead public static void doSomething1(String[] args) {}

场景二：返回值不要使用对象数组

官方文档给出的反例与正例：

// 反例：不推荐 public User[] loadUsers() { ... } // 正例：改用不可变列表（或不可变集合） public ImmutableList<User> loadUsers() { ... }

返回值场景推荐的是ImmutableList（或ImmutableSet）而非Iterable：因为返回值需要向调用方承诺具体的行为能力（是否有序、是否去重、是否可变），不可变集合还能防止调用方篡改内部状态。检查器源码中的诊断建议默认使用ImmutableList，这与文档表述一致。

对应的测试（returnType_instanceMethods，测试源码）验证了返回值场景的诊断消息：

// BUG: Diagnostic contains: consider an ImmutableList<Object> instead public Object[] objectArray() { return new String[] {"a"}; } // BUG: Diagnostic contains: consider an ImmutableList<String> instead public String[] stringArray() { return new String[] {"a"}; } public int[] intArray() { return new int[] {42}; } // 原始类型数组，不报告

overridden测试则验证了重写豁免：父类抽象方法public abstract String[] stringArray();被报告，而子类的@Override实现不报告——问题出在父类的 API 设计，不应让每个子类重复承担诊断噪音。

场景三：二维数组的替代方案

文档在"Additional Alternatives"一节特别指出：如果你有一个二维数组（例如Foo[][]），可以考虑使用ImmutableTable<Integer, Integer, Foo>代替。

这是因为二维数组Foo[row][col]本质上是一张"行索引 → 列索引 → 元素"的二维映射表，而 Guava 的ImmutableTable<R, C, V>正是这种双键映射的不可变表达，语义更清晰、类型更安全。

不过要注意诊断消息的差异。对于多维数组，检查器不会给出具体的替代类型建议，只提示"避免"。测试twoDimensionalArrays（测试源码）验证了这一点：

// BUG: Diagnostic contains: Avoid returning a String[][] public String[][] returnValue() { return new String[2][2]; }

诊断消息的生成原理

createDescription方法（源码）负责构造具体的诊断文案，其逻辑可以概括为：

消息模板为"Avoid %s a %s"，其中动词（verb）在返回值场景是returning、在参数场景是accepting；
对一维对象数组，追加"; consider an %s<%s> instead"建议：参数场景填充Iterable，返回值场景填充ImmutableList，尖括号内是数组的元素类型；
对多维对象数组（判断依据是去掉一层后仍是ArrayType），不追加替代建议，只保留Avoid returning a String[][]形式的提示，避免给出不恰当的单集合替代方案。

因此实际生产中你看到的编译诊断大致是：

[AvoidObjectArrays] Avoid returning a User[]; consider an ImmutableList<User> instead [AvoidObjectArrays] Avoid accepting an Object[]; consider an Iterable<Object> instead [AvoidObjectArrays] Avoid returning a String[][]

isObjectArray判断（源码）则是：类型为ArrayType且元素类型非原始类型。这解释了为什么int[]永远不会被报告。

如何启用与抑制该检查

AvoidObjectArrays在 BuiltInCheckerSuppliers.java 中被注册在DISABLED_CHECKS（默认关闭的检查集合）中，也就是说默认情况下该检查不生效，需要显式开启。

在编译命令中加入以下任一 flag 即可：

# 以 WARNING 级别启用 -Xep:AvoidObjectArrays:WARN # 以 ERROR 级别启用（强制构建失败） -Xep:AvoidObjectArrays:ERROR # 显式关闭（默认即关闭，可用于覆盖上级配置） -Xep:AvoidObjectArrays:OFF

级别定义来自 BugPattern.java 的SeverityLevel枚举：ERROR、WARNING、SUGGESTION。检查器声明本身的级别为WARNING（源码），启用后默认按警告输出。

如果某个方法确实需要保留数组形态（例如兼容第三方框架），可以使用标准的@SuppressWarnings局部抑制：

@SuppressWarnings("AvoidObjectArrays") public Object[] legacyCompat() { ... }

抑制名称即检查器名称AvoidObjectArrays（@BugPattern未显式指定name时使用类名，参见 BugPattern.java）。

测试驱动：如何验证检查器行为

AvoidObjectArraysTest使用 error-prone 的 CompilationTestHelper 驱动真实 javac 编译过程，在测试源码中通过// BUG: Diagnostic contains: ...注释断言特定位置必须产生包含指定片段的诊断。这种"编译期断言"的测试模式保证了：

每个正例（应报告）与反例（不应报告）都有精确的源码级验证；
诊断消息的措辞（如consider an Iterable<Object> instead）被锁定，防止无意的文案漂移；
各类豁免边界（main方法、varargs、Iterable重载、注解方法、@Override、JUnit@Parameters等）都有独立的测试用例。

如果你要在自己的代码库中引入该规范，可以直接复用这套测试思路：把文档中的反例/正例跑一遍编译，确认期望的诊断产生于正确位置。

小结与源码索引

AvoidObjectArrays是 error-prone 中一道默认关闭、按需开启的 Java API 风格检查，核心主张是"公开方法签名中避免对象数组，参数用Iterable，返回值用ImmutableList/ImmutableSet，二维数组考虑ImmutableTable"。它的实现只针对公开且非重写的方法，并为main、varargs、已有Iterable重载、注解类型与参数化测试框架等场景提供了精确的豁免，兼顾了规范落地与真实生态的兼容性。

深入阅读建议按以下顺序展开：