Java泛型只在编译期做类型检查，编译成字节码后类型信息就被擦除了。这意味着一个声明为Map<String, Integer>的集合，完全可能通过未经检查的旧代码、反射或者原始类型（raw type）引用塞进一个Double甚至StringBuilder对象。这种被"污染"的Map平时没有任何异常，直到某处代码执行强制类型转换时才会抛出ClassCastException，而报错位置往往离真正的污染源非常遥远，排查代价很高。JDK在Collections工具类中提供了checkedMap()方法，专门用来在运行时对每次插入的键和值做类型校验，把类型错误拦截在写入的那一刻。
一、为什么泛型Map会被污染：理解类型擦除的隐患
要理解checkedMap()存在的意义，首先要明白泛型擦除带来了什么。编译器在编译Map<String, Integer>时，实际上只保留了Map这个原始类型，泛型参数仅用于编译期的静态检查。一旦绕过编译器，运行时的JVM根本不知道这个Map里面"应该"装什么。
绕过编译器检查的途径比想象中多。最典型的是调用接收原始类型参数的遗留方法，比如某个老版本的三方库定义了void fillMap(Map raw)，向它传入泛型Map后，方法内部可以随意put任何对象而不产生任何报错。此外，通过反射调用put方法、使用@SuppressWarnings("unchecked")标注的未经检查转换，甚至是从Object流反序列化出来的Map，都可能成为污染源。
来看一个被污染的典型例子：
Map<String, Integer> scores = new HashMap<>();
// 借助原始类型引用绕过编译期检查
Map raw = scores;
raw.put("java", 90); // 正常
raw.put("python", "Ninety"); // 编译器不再检查，String被塞了进去
// 平时读取可能不报错（Object接收）
System.out.println(scores.size()); // 输出 2，毫无异常
// 一旦强转，炸了，且报错位置离污染源很远
int value = scores.get("python"); // ClassCastException
这段代码编译时只会有一个警告，运行时在get("python")处抛出ClassCastException: java.lang.String cannot be cast to java.lang.Integer。如果put和get分布在两个模块、两次请求中，定位起来会非常痛苦。checkedMap()的设计目标就是把报错时机从"读取时"提前到"写入时"，让异常堆栈直接指向污染源。
二、checkedMap() 的用法与底层实现原理
checkedMap()是java.util.Collections中的静态方法，签名如下：
public static <K, V> Map<K, V> checkedMap(Map<K, V> m,
Class<K> keyType,
Class<V> valueType)
它接收三个参数：被包装的原始Map、键的Class对象、值的Class对象，返回一个动态类型安全的视图。基本用法：
import java.util.*;
public class CheckedMapDemo {
public static void main(String[] args) {
Map<String, Integer> inner = new HashMap<>();
Map<String, Integer> scores =
Collections.checkedMap(inner, String.class, Integer.class);
scores.put("java", 95); // 通过校验，正常插入
System.out.println(scores); // {java=95}
// 试图绕过泛型检查插入非法类型
Map raw = scores;
try {
raw.put("python", "Ninety"); // 值类型不合法
} catch (ClassCastException e) {
// 插入瞬间立即报错，堆栈直接指向污染代码
System.out.println("插入被拦截: " + e.getMessage());
}
// 键类型不合法同样会被拦截
try {
raw.put(42, 100);
} catch (ClassCastException e) {
System.out.println("键被拦截: " + e.getMessage());
}
System.out.println(scores.size()); // 依然是 1
}
}
从实现角度看，checkedMap()返回的是Collections.CheckedMap这个内部包装类。它的put方法在委托给底层Map之前，会先执行typeCheck逻辑：对键和值分别调用keyType.cast(k)与valueType.cast(v)。Class.cast()会在对象不兼容时抛出ClassCastException，校验通过才执行真正的插入。同理，putAll会在遍历每一个待插入条目时逐项校验，任何一项不合法都会在操作完成前失败。
有几个细节值得注意。第一，包装类对entrySet、keySet、values返回的视图也做了保护，通过视图上的迭代器setValue修改值同样会触发校验。第二，null的处理：Class.cast(null)返回null且不抛异常，因此允许插入null键值（前提是底层Map本身支持null，例如HashMap）。第三，CheckedMap基于键和值的运行时类型做isInstance判断，所以传入的Class必须是具体类型；如果你声明的是Map<String, List<Integer>>，只能校验到值是List，无法校验List内部元素是Integer，这是泛型擦除决定的天然局限。
三、典型应用场景与常见误区
第一个典型场景是对接遗留代码或未经检查的外部输入。当你的泛型Map需要传递给老版本的库方法、或者通过反射框架填充时，用checkedMap()包装后，一旦对方插入非法数据立刻抛异常，堆栈会准确显示是哪一次put造成的污染，等于给Map装了一个实时报警器。
第二个场景是防止堆污染扩散到泛型API内部。假设你编写了一个公共工具方法process(Map<String, Integer> data)，调用方可能传入被污染的Map。此时可以在方法入口先包装再处理：
public static int sumValues(Map<String, Integer> data) {
// 内部使用校验视图，读取时也能防御已污染的数据
Map<String, Integer> safe =
Collections.checkedMap(new HashMap<>(data),
String.class, Integer.class);
int sum = 0;
for (int v : safe.values()) { // 若存在污染元素，构造时即失败
sum += v;
}
return sum;
}
第三个场景是配合序列化边界使用。从网络或磁盘反序列化得到的Map，其内容完全取决于字节流的来源，是不可信的。在反序列化之后立即用checkedMap()包装并做一次遍历，可以在业务逻辑使用数据之前完成类型净化。
关于常见误区，需要澄清几点。其一，checkedMap()与unmodifiableMap()是完全不同的两个东西：后者是禁止修改（写入直接抛UnsupportedOperationException），前者允许修改但强制类型合法，两者可以叠加使用。其二，checkedMap只在写入和视图修改时校验，不会主动扫描底层Map中已存在的旧数据。如果包装之前Map里已经混入了非法元素，这些脏数据仍会留在里面，只有当你通过校验视图读取它们时才可能暴露。其三，类型校验要求精确匹配或父子类兼容，Integer.class的Map无法接受Double，即使两者都是Number的子类，这一点和泛型的协变规则一致。
除了checkedMap()，Collections还提供了整套家族方法：用于Collection的checkedCollection()、用于List的checkedList()、用于Set的checkedSet()，以及JDK 5之后的checkedSortedMap()、checkedNavigableMap()等，用法和原理完全一致。在类型边界模糊、数据来源不可信的代码路径上，给集合加上这一层运行时防护，成本几乎为零，却能把隐蔽的堆污染问题转化为即时、可定位的异常，是提升Java代码健壮性的实用技巧。
Collections.checkedMapJava泛型类型安全修改时间：2026-09-13 03:36:38