PECS原则是泛型安全使用的底层契约，SDK必须严格遵循以保障可扩展性、降低误用成本并维持并发下的类型稳定性。
PECS 原则不是“高级技巧”，而是泛型安全使用的底层契约——尤其在 SDK 架构中，它直接决定接口的可扩展性、调用方的误用成本和并发场景下的类型稳定性。
为什么 SDK 必须严格遵循 PECS？
大型高并发 SDK（如分布式日志采集器、实时指标聚合器）常暴露泛型集合参数。若不按 PECS 设计：
- 方法声明
List<T>而非List<? extends T>，调用方被迫传入精确类型，丧失多态兼容性（例如无法传入ArrayList<MetricEventV2>给期望MetricEvent的接口）； - 写入型 API 使用
List<? extends T>，编译期就拒绝合法添加操作，迫使 SDK 用户绕过泛型、用原始类型或反射，破坏类型安全； - 并发容器（如
CopyOnWriteArrayList）若被错误泛型化，可能因擦除后运行时类型冲突引发ClassCastException，且堆栈难以定位。
SDK 接口设计中的 PECS 实战规范
所有泛型集合参数/返回值必须按角色标注通配符，禁止裸泛型（List<T>）直接暴露：
deep-java-review
下载
Java项目代码review工具。分析Git变更+完整调用链路上下文，推断业务需求，进行多维度评分和分类汇总，生成完整PRD文档。包含细粒度Java代码审查清单（Null安全、异常处理、Streams、并发、equals/hashCode、资源管理、API设计、性能、MyBatis/ORM、事务边界、SQL/DD...
-
只读数据流（如回调通知、批量查询结果）→ 用
? extends T：
例：void onEvents(List<? extends Event> events)，允许传入ArrayList<ClickEvent>、LinkedList<ErrorEvent>； -
只写数据流（如批量上报、缓冲区注入）→ 用
? super T：
例：boolean submitBatch(Collection<? super MetricPoint> points)，支持传入ArrayList<MetricPoint>或ArrayDeque<BaseMetricPoint>（假设BaseMetricPoint是父类）； -
读写混合场景 → 拆分为两个独立方法，而非妥协用
List<T>：
反例：void process(List<LogEntry> entries)（既遍历又修改）；
正例：void ingest(Collection<? super LogEntry> batch)+List<? extends ProcessedLog> drain()。
与并发容器协同的关键细节
泛型擦除在高并发下会放大类型风险，PECS 是唯一可控防线：
立即学习“Java免费学习笔记（深入）”；
-
ConcurrentHashMap<K, V>的 key/value 类型必须明确边界：缓存 key 若为业务 ID，应声明ConcurrentHashMap<? super BusinessId, ? extends CacheValue>，避免子类 ID（如OrderId）无法命中； - 避免在
Stream操作链中混用裸泛型：如list.parallelStream().map(...).collect(Collectors.toList())返回List<Object>，应在收集阶段显式指定Collectors.toCollection(() -> new CopyOnWriteArrayList<? extends Result>())； - 自定义并发集合（如带版本控制的
VersionedQueue<T>）的泛型参数必须用T extends Serializable & Comparable<T>等上界约束，而非依赖 PECS——PECS 解决的是“使用侧”，上界解决的是“实现侧”。
SDK 版本演进中的 PECS 兼容性保障
泛型变更极易导致二进制不兼容。规范做法：
- 新增方法优先用 PECS，旧方法若需升级，采用重载而非修改签名：
旧：void handle(List<Alert> alerts)；
新：void handle(List<? extends Alert> alerts)（保留旧方法，标注@Deprecated）； - 内部泛型工具类（如
SafeCollector）必须封装 PECS 逻辑：<T> Collector<? super T, ?, List<T>> toImmutableList()，确保下游无论传Stream<String>还是Stream<CharSequence>都能安全消费； - 文档强制标注每个泛型参数的“角色”：在 Javadoc 中明确写
@param events the <strong>producer</strong> list of events (use ? extends Event)，杜绝理解偏差。
