Java 泛型 API：从静态约束到擦除与兼容演进
某个公共 SDK 最初返回 raw List，调用方一直靠强制转换取订单。后来库作者把签名收紧成 List<Order>，新代码编译得更漂亮，旧插件也还能加载。上线后，一批历史缓存里混入的字符串却在读取处变成 ClassCastException。更麻烦的是，堆栈只落在业务遍历代码上，真正写入错误数据的适配器早已执行完了。
这就是泛型在工程里最容易被误解的地方：源码签名更精确，不代表运行时对象突然携带了完整类型；旧二进制还能链接，也不代表数据和行为兼容。这个 SDK 升级必须同时检查公共 API 的读写方向、GenericsLab 的编译行为、javap 展示的擦除与桥方法，以及插件、序列化和旧客户端的真实结果。
List<String> 的价值仍然是把约束交给编译器，而不是少写一次强转。但只要 raw type、unchecked、反射或外部数据绕过了这份证明，问题就会推迟到运行时。Java 长期支持版本、JDK 发行版和 --release 的选择见Java 版本与运行基线。
SDK 升级要同时保住三层类型证据
公共 API 的类型参数与边界、不变性、PECS、擦除、桥方法、可具体化类型、反射类型令牌、泛型 varargs 和堆污染，最终都要落到源码、二进制和数据语义三层证据。
捕获转换与类型推断的完整求解过程、JVM 类加载、JIT 调用点优化、函数式接口和 Stream API 都有更合适的专题。复杂推断错误会给出定位入口，但编译器算法不会取代这条 API 兼容主线。
看擦除前先确认编译层和运行层
能阅读类、接口、继承、方法重载与覆盖的 Java 代码。本机有 JDK 17 或更高版本，且 java、javac、javap 来自同一套 JDK。知道编译期类型与运行时对象不是同一个观察层。
先确认工具链：
java -version
javac -version
javap -version下面的实验统一使用 javac --release 17，因此较新的编译器也可以生成面向 Java 17 的制品。但 --release 只约束编译目标，不能替代项目对 JDK、构建插件、依赖库和运行环境的完整兼容测试。
先把公共签名里的四种类型说清
声明 final class Box<T extends Comparable<? super T>> 时，T 是声明引入的类型变量，Comparable<? super T> 是它的上界；Box<String> 是一个参数化类型；String 是该次使用提供的类型实参。单写 Box 则是为了兼容旧代码保留的原始类型，不是 Box<Object> 的缩写。
final class Box<T> {
private T value;
Box(T value) { this.value = value; }
T get() { return value; }
void set(T value) { this.value = value; }
}T 让 set 的输入与 get 的输出保持同一种未知但确定的类型。若改成 Object，调用者每次读取都要转换，而且编译器无法阻止先写入 Integer、再当作 String 读取。泛型把错误尽量前移到编译期；它并不保证所有参数化类型在运行时各有一份类。
类型变量可以有交叉上界：
static <T extends Comparable<? super T> & java.io.Serializable>
T max(T left, T right) {
return left.compareTo(right) >= 0 ? left : right;
}若上界包含类，类必须写在第一个位置，后面才是接口。Comparable<? super T> 比 Comparable<T> 更宽：只要 T 能与自身或其某个父类型比较即可。边界应表达算法真正调用的能力，不应仅为了“看起来更严格”堆叠接口。
为什么整数列表不能直接交给 Number 接口
数组是协变的，Integer[] 可以赋给 Number[]，写入不兼容值时由运行时抛 ArrayStoreException。泛型参数化类型默认不变：虽然 Integer 是 Number 的子类型，List<Integer> 既不是 List<Number> 的子类型，也不是它的父类型。
假设下面赋值成立：
List<Integer> integers = new ArrayList<>();
List<Number> numbers = integers; // 实际上编译失败
numbers.add(3.14); // 将 Double 写进“整数列表”
Integer first = integers.get(0); // 契约被破坏编译器禁止第一步，从而不必等到读取处才爆炸。需要只读地接受多种 Number 子类型时，用 List<? extends Number>；需要向容器写入 Integer 时，用 List<? super Integer>。通配符表达的是“一族参数化类型”，不是绕开检查的任意类型。
复制接口只暴露真实的读写方向
PECS 是 “Producer Extends, Consumer Super”：对当前方法而言，来源生产 T，使用 ? extends T；目标消费 T，使用 ? super T。
static <T> void copy(
List<? extends T> source,
List<? super T> target) {
for (T item : source) {
target.add(item);
}
}调用 copy(List<Integer>, List<Number>) 时，源只能安全读成 T，目标可以安全写入 T。但规则不是“extends 永远只读、super 永远只写”：二者都允许读取，只是 ? extends T 的非空写入类型无法证明，而 ? super T 读取时通常只能得到 Object。任何 List<?> 仍可写入 null、清空或删除已有元素。
API 设计时先问“调用者要从参数中读什么、写什么”，再决定通配符。一个参数既读又写同一个精确类型时，通常保留 List<T>；多个参数需要共享同一种类型关系时，引入命名类型变量；返回值通常避免通配符，因为它会把捕获问题推给调用者。
公共 API 若依赖多层通配符、交叉边界和目标类型才能让常规调用编译，通常说明边界或重载承担了过多职责。遇到 CAP#1 或 inference variable has incompatible bounds，先缩小签名、拆分读写责任，或用显式类型实参定位冲突；不要用 unchecked 强转把编译器拒绝的证明移到运行时。捕获转换和推断算法可按 JLS 第 5、18 章排查，但不应成为业务 API 的日常认知负担。
到这里，编译器已经利用实参、目标类型和边界完成了静态检查。接下来生成 class 时，它不会为 List<Integer>、List<Number> 各复制一套集合实现，而会擦除大部分类型实参，并在必要的读取点插入转换。开头那次事故之所以能“旧插件照常加载、读取数据时才失败”，关键就藏在这个阶段。
源码写的是 String，class 里为什么还有 Object
Java 泛型采用擦除实现，以支持泛型出现前后的库和客户端迁移。无界 T 通常擦除为 Object；有界 T extends Number 擦除为最左上界 Number；参数化类型 List<String> 擦除为 List。编译器在读取点插入必要的类型转换，并在覆盖需要维持多态时生成桥方法。
class Node<T> {
T value() { return null; }
}
final class StringNode extends Node<String> {
@Override String value() { return "ok"; }
}Node.value() 擦除后的返回类型是 Object，而子类源码方法返回 String。编译器会在 StringNode 中合成一个形如 Object value() 的 bridge，转调真正的 String value()，使通过 Node 引用的虚方法分派仍然正确。桥方法是二进制适配器，不是业务作者需要手写的重载。
用前面的示例观察：
mkdir -p out
javac --release 17 -Xlint:all -d out src/example/GenericsLab.java
java -cp out example.GenericsLab
javap -classpath out -c -p -s example.GenericsLab\$StringNodePowerShell 中最后一个类名需用单引号，避免 $ 被当作变量：
javap -classpath out -c -p -s 'example.GenericsLab$StringNode'预期正常输出包含复制后的数字、最大值和 bridge=ok；javap 会显示返回 String 的实现以及返回 Object 的合成转调方法。是否有桥方法应以实际 class 证据为准，不要从源码方法数猜测。
序列化器只拿到 Class<List> 为什么不够
运行时能完整表示、从而可做精确类型检查的类型称为可具体化类型。原始类型、非泛型类型、基本类型、无界通配符参数化类型（如 List<?>）及其满足条件的数组属于此类；List<String>、T、List<String>[] 不是。
因此这些限制不是语法任性，而是运行时没有足够信息：
不能 new T()、new T[10] 或 T.class；构造对象应显式传入工厂、Class<T> 或 Supplier<T>。不能写 value instanceof List<String>，但可检查 value instanceof List<?>，再逐个验证元素。不能直接创建 new List<String>[10]；数组协变与运行时元素检查无法安全承载被擦除的元素类型。
不能用仅类型实参不同的方法做重载，因为擦除后的描述符相同。
反射 API 可能从类文件的 Signature 属性读到声明的泛型签名，但这不等于每个运行时对象都携带其实参。序列化、依赖注入和 JSON 框架需要 Type、类型令牌或显式 schema，正是为了补上这层信息。
反射只能恢复声明，还得重新验证数据
Class<List> 只能表示擦除后的原始类，无法区分 List<Order> 与 List<User>。框架通常让调用者传入 Type、匿名类型令牌或由 schema 生成的描述，再递归解析 ParameterizedType、通配符和数组组件。这个描述是“期望的声明”，不是数据已经正确的证明：解析器仍要验证 JSON 节点种类、元素数量、字段范围和未知类型允许列表。
Type type = Holder.class.getDeclaredField("orders").getGenericType();
if (type instanceof ParameterizedType parameterized) {
System.out.println(parameterized.getActualTypeArguments()[0]);
}如果字段声明为 List<Order> orders，这段代码可以从 Signature 中读到 Order。它证明的是“字段声明期望订单”，不是“当前列表里的每个对象已经验证为订单”。框架若把这两件事混为一谈，就会重演开头那种历史数据在读取处才失败的问题。
插件与多类加载器环境还多一层类身份问题：同名类由不同类加载器定义时并不是同一个运行时类型。宿主即使声明 Plugin<Message>，也不能仅凭泛型签名信任插件输入；它仍需校验接口由哪个加载器定义、插件元数据是否匹配、边界对象能否由宿主 schema 解码。把无法避免的 unchecked 转换收进单一适配器，先校验再转换，不让未知值穿过线程池、缓存或消息队列。
反射类型解析可能沿继承层次做变量替换，重复解析也会产生延迟和分配。框架可以按声明成员和类加载器缓存解析计划，但缓存键不能只用类名，也不能强引用可卸载插件的类加载器导致泄漏。性能优化仍以剖析为据；删掉泛型或改用 raw type 不会消除反射成本。
事故根因：unchecked 把污染推迟到读取处
堆污染发生时，一个参数化类型变量引用了不符合该参数化类型的对象。常见入口是原始类型、unchecked 转换、错误的 @SuppressWarnings，以及非可具体化元素类型的 varargs 数组别名。
反向实验放在独立编译单元中。先保留 lint 警告进行编译，再运行：
javac --release 17 -Xlint:all -cp out -d out src/example/UnsafeVarargsLab.java
java -cp out example.UnsafeVarargsLab编译时应先看到数组别名处的 [varargs] 警告；运行时，示例故意把 List<Integer> 经 Object[] 塞进声明为 List<String>[] 的 varargs 数组，随后在读取字符串时得到 ClassCastException。异常在读取处出现，污染却更早发生，这会让线上堆栈偏离真正根因。
static void unsafe(List<String>... groups) {
Object[] aliases = groups;
aliases[0] = List.of(42); // 污染发生
String value = groups[0].get(0); // 读取处失败
}对非可具体化 varargs 参数，编译器会发出警告。@SafeVarargs 是作者对调用方的安全承诺，不是“我不想看警告”：方法不得向数组写入不兼容元素，也不得把数组暴露给可能污染它的代码；javac -Xlint:varargs 仍可报告方法体内某些明显危险操作。安全聚合通常只遍历参数并复制元素；无法证明安全时，改收 List<List<T>> 或普通集合参数。
原始类型只应留在明确的旧边界。若不得不从旧 API 接收 List，应在一个很小的适配器内逐项校验和复制，局部抑制警告并解释不变量；不要让 raw type 穿过领域层。团队把 -Xlint:unchecked -Werror 设为门禁前，应先建立少量可审计的例外，而不是全局 @SuppressWarnings("unchecked")。
把公共 API 改成可以验证的版本
可运行示例位于 examples/backend-development/java/generics/，成功路径源码是 src/example/GenericsLab.java，故意制造 heap pollution 的反向源码是 src/example/UnsafeVarargsLab.java。核心方法分别展示 PECS、边界和安全 varargs：
static <T> List<T> copyOf(List<? extends T> source) {
return new ArrayList<>(source);
}
static <T extends Comparable<? super T>> T max(List<? extends T> source) {
if (source.isEmpty()) throw new IllegalArgumentException("source is empty");
T best = source.get(0);
for (int i = 1; i < source.size(); i++) {
if (source.get(i).compareTo(best) > 0) best = source.get(i);
}
return best;
}
@SafeVarargs
static <T> List<T> concat(List<? extends T>... sources) {
List<T> result = new ArrayList<>();
for (List<? extends T> source : sources) result.addAll(source);
return List.copyOf(result);
}copyOf 返回 List<T>，让调用者拿到可命名契约；max 的比较边界允许实现 Comparable 的父类型契约；concat 不写入、不泄露 varargs 数组，只把元素复制进新容器。复制会消耗时间和内存，但切断了调用方后续修改与内部状态的别名关系。
旧插件还能加载，不代表升级安全
擦除让许多“给旧 API 加泛型”的改造保持二进制兼容，但不保证源码兼容、迁移兼容或语义兼容。JLS 的二进制兼容规则会按擦除后的签名看涉及类型变量或参数化类型的方法；桥方法也用于维持覆盖关系。然而以下变化仍需谨慎：
把返回值从 raw List 收紧为 List<String>，旧二进制可能继续链接，新源码却会暴露既有 unchecked 使用；真实数据不满足契约时仍会失败。把 List<T> 参数改成 List<? extends T> 可能扩大读入能力，却失去方法体写入能力，也可能改变重载选择和类型推断结果。给类型变量增加上界会改变其擦除；最左上界变化可能改变方法描述符，破坏旧调用点链接。
仅靠不同泛型实参新增重载会形成相同擦除，直接编译失败；看似无冲突的泛型重载也可能让既有调用变得歧义。删除或改变编译器生成桥所依赖的覆盖关系，可能影响已编译客户端的虚调用。
库演进至少做三层验证：新源码编译与测试；旧客户端二进制直接运行；旧客户端源码用新库重新编译并审查新警告。公开签名还应纳入 API diff，检查擦除后描述符、Signature 属性和桥方法，而不是只比较格式化后的 Java 源码。
排查时先判断：错误发生在编译、链接还是读取
看到 inference variable has incompatible bounds，说明调用点收集到的上下界无法同时满足。这里先缩小方法签名或显式写出类型实参，不要用 unchecked 强转把编译错误变成运行错误。name clash ... have the same erasure 则更直接：两个源码方法擦除后落到了同一个描述符，换多少类型实参都不能构成重载。
如果异常已经是 ClassCastException，而且落在从集合读取元素的位置，就沿数据来源向上找 raw type、unchecked、varargs 数组别名和反序列化入口。反向实验故意让污染在写入时发生、异常在读取时出现，就是为了复现这段距离。javac -Xlint:all 能告诉你哪里绕过了静态证明，javap -v 能告诉你 class 中实际保存了什么描述符和 Signature；它们通常比继续补强制转换更接近根因。
这里还要拆掉一个常见的性能误区。参数化类型通常不会为每种实参生成一份类，所以删掉泛型并不会自动减少类或分派。真正可能有成本的是基本类型装箱、通用集合的对象分配，以及为了切断别名做的不可变复制。先用基准或生产剖析确认分配率、GC 与尾延迟，再考虑原生类型专用结构。raw type 不会消除装箱，只会拿走编译器本来能提供的保护。
对插件和序列化边界，泛型也不是安全校验。List<User> 只是期望的声明，JSON、数据库和反射构造出的每个元素仍要按 schema 检查。尤其是 @SuppressWarnings("unchecked")，应该把它当作一块需要解释的缺口：为什么这里能证明对象满足契约，证明依赖哪些前置校验，失败时会在当前边界拒绝还是继续传播。
公共接口也别追求“尖括号越多越通用”。读仓储可以返回 List<Order> 或只读抽象，不要泄露内部可变集合；只有真正服务多种类型的基础库，才值得承担复杂边界。签名越精确，编译器保护越强；签名越聪明，调用错误、跨语言接入和后续演进的成本也可能越高。一个普通调用者看不懂的类型谜题，通常不是高级设计，而是职责没有拆开。
把 SDK 升级检查真正跑进 CI
合并前，先让成功路径在严格告警下编译。这里使用的命令和前面的实验相同，只是增加 -Werror，确保新的 unchecked、rawtypes 或 varargs 告警不能悄悄进入主线：
rm -rf out
mkdir -p out
javac --release 17 -Xlint:all -Werror -d out src/example/GenericsLab.java
java -cp out example.GenericsLab
javap -classpath out -p -s example.GenericsLab\$StringNode这组命令通过以后，还没有完成兼容验证。把旧客户端二进制留一份，不重编译直接加载新库；再用新库重新编译旧客户端源码，审查新增告警；最后拿历史缓存或消息样本跑反序列化。只做其中一项，会漏掉另外两类问题。公共 API 的 diff 还要观察最左上界、擦除后描述符、重载集合和桥方法，而不是只比较源码文本。
成功运行的稳定输出应包含：
numbers=[3, 1, 2]
snapshot=[3, 1, 2]
combined=[3, 1, 2, 4.5]
max=3
bridge=ok前三行证明来源读取、不可变快照和目标写入的方向没有混淆，bridge=ok 与 javap 中出现的桥方法共同组成运行时证据。只断言列表内容而不检查描述符，无法发现公共签名的擦除变化；只检查 javap 而不运行旧数据，又无法发现 heap pollution 或反序列化污染。
@SuppressWarnings 与 @SafeVarargs 也需要逐处审查，而不是统计数量。抑制范围应该缩到边界适配方法，旁边能说明校验依据；集合参数则回到真实读写方向，来源用 extends、目标用 super，返回值不要把通配符捕获负担交给所有调用者。若为了类型安全复制大集合，再用真实容量测一次延迟和分配，决定这次复制是必要隔离还是需要改成流式处理。
反向实验故意保留编译警告并产生运行时错误，因此不要塞进默认 -Werror 成功路径。CI 可以单独断言它出现预期 lint、以非零状态退出并包含 ClassCastException。这样以后有人“清理示例”时，不会顺手删掉最重要的失败证据。
一项公共泛型 API 变更至少保留三条互不替代的门禁：新源码在 -Xlint:all -Werror 下无新增告警；旧客户端 class 不重编译可链接并通过契约样本；历史数据经新版适配器校验后要么得到正确类型，要么在边界稳定拒绝。三条分别覆盖静态约束、二进制链接和数据语义，不能用一个“编译通过率”汇总成绿色。
擦除、推断与二进制兼容继续查这些入口
JLS 25 第 4 章：类型、参数化类型、擦除与堆污染：类型变量、参数化类型、可具体化类型、原始类型和 heap pollution 的规范口径。JLS 25 第 5 章：转换与捕获转换：unchecked conversion、capture conversion 与运行时检查边界。
JLS 25 第 18 章：类型推断：约束公式、归约、求解与调用点推断。JLS 25 第 9.6.4.7 节：@SafeVarargs：安全承诺、合法声明位置与警告规则。
JLS 25 第 13 章：二进制兼容：按擦除签名理解库演进和已编译客户端兼容。dev.java：通配符 与 类型擦除：Oracle 官方学习入口中的 PECS、擦除和桥方法示例。
dev.java：泛型限制：实例化、数组、instanceof、静态上下文、异常与重载限制。
回到开头那次插件事故
现在可以把链路重新串起来了。类型参数先把订单元素之间的关系写进源码，通配符只描述接口真实的读写方向；编译器检查完成后，class 里保留的是擦除描述符、必要的 Signature 和桥方法。旧插件可能仍按相同描述符成功链接，但历史数据不会因此自动变成 Order，读取处的转换仍可能失败。
所以修复不能停在把 raw List 改成 List<Order>。适配器要先按 schema 验证历史元素，把不可避免的 unchecked 收在一个可审计位置；API 变更同时跑新源码、旧二进制和旧源码重编译；javap 证明确认桥和描述符没有意外变化。做到这些，泛型才真正把错误前移，而不是只让源码看起来更现代。