---
id: TK-GL-000
type: guideline
example: true
maturity: verified
tags: [spring-boot, dependency, optional]
created: 2026-04-01
last_referenced: 2026-04-28
reference_count: 2
contributors: [carol]
source_project: common-lib
evidence:
  - project: common-lib
    date: 2026-04-01
    description: "公共模块升版后下游服务启动失败排查"
  - project: project-alpha
    date: 2026-04-28
    description: "引用公共模块时遇到同样问题"
---

# 公共模块变更后的兼容性检查清单

## 规则（recommend）

公共模块（如 common-lib）发版前，必须执行以下检查：

### 必做

1. **接口兼容性**：新版本不能删除或修改已有 public 方法签名
2. **依赖传递检查**：新增的依赖是否会与下游项目冲突
   ```bash
   mvn dependency:tree -Dverbose | grep "omitted for conflict"
   ```
3. **Optional 依赖标记**：非核心依赖必须标记为 `<optional>true</optional>`
4. **版本号规范**：破坏性变更必须升大版本号

### 建议

- 发版前在至少一个下游项目中测试集成
- CHANGELOG 中注明破坏性变更和迁移指南

## 反例

common-lib 2.3.0 引入了 `guava:32.0`，与 project-alpha 中的 `guava:31.1` 冲突，导致 `NoSuchMethodError`。如果当时将 guava 标记为 optional，就不会传递到下游。

## 适用场景

任何公共模块/SDK 的版本发布。