必码

Appearance

CAS 依赖冲突解决完全指南：从手动排除到 BOM 强制管理的进阶之路 ​

作者： 必码 ｜ bima.cc

前言 ​

在 Java 企业级开发领域，Apereo CAS（Central Authentication Service）作为最广泛使用的单点登录（SSO）解决方案之一，其部署和定制化过程中最令人头疼的问题莫过于依赖冲突。无论你是初次接触 CAS 的新手，还是已经维护 CAS 系统多年的资深工程师，依赖冲突始终是一个无法回避的挑战。

本文基于作者在实际项目中从 CAS 5.3 到 CAS 6.6 再到 CAS 7.3 的完整升级迁移经验，深度剖析 CAS 依赖冲突的根源、演变历程和解决方案。文章涵盖了从最原始的手动排除策略到现代化的 BOM 强制管理范式的完整进阶之路，旨在为读者提供一份全面、实用、可操作的依赖冲突解决指南。

本文的所有配置示例均来自实际生产项目的简化教学版本，保留了核心逻辑的同时去除了业务敏感信息。读者可以直接将这些配置模式应用到自己的 CAS Overlay 项目中。

第一章 CAS 依赖冲突的根源分析 ​

1.1 CAS 项目的架构特征 ​

Apereo CAS 是一个超大型单体项目，其代码仓库包含了上百个子模块。从核心认证引擎到 Web 层展示，从 LDAP 集成到 OAuth2 支持，从票务注册到审计日志，CAS 几乎涵盖了企业级身份认证的所有方面。这种"大而全"的架构设计带来了一个必然的副作用：极其复杂的依赖关系网。

让我们先通过数据来理解 CAS 的规模。以 CAS 6.6.x 为例，其 Maven Central 上的 cas-server-support-bom 就管理了超过 200 个直接依赖的版本。而每个 CAS 子模块自身又会传递引入更多的第三方库。当我们构建一个包含 30 多个 CAS 子模块的 Overlay 项目时，最终的依赖树中往往包含上千个 JAR 包。

这种规模的依赖管理本身就极具挑战性，而 CAS 的以下架构特征进一步加剧了依赖冲突的风险：

第一，CAS 基于 Spring Boot 构建。 CAS 从 5.x 版本开始全面拥抱 Spring Boot，这意味着 CAS 的依赖管理必须与 Spring Boot 的依赖管理体系协调一致。Spring Boot 通过其 BOM（Bill of Materials）管理了数百个第三方库的版本，而 CAS 又在此基础上引入了大量额外的依赖。两套版本管理体系之间的协调，是依赖冲突的首要来源。

第二，CAS 使用了大量的 Java 安全和加密库。 作为一个身份认证系统，CAS 深度集成了 BouncyCastle、Shibboleth、OpenSAML 等安全和加密相关的库。这些库往往对版本有严格的要求，且它们自身也会传递引入其他依赖，形成复杂的版本依赖链。

第三，CAS 的多协议支持。 CAS 同时支持 CAS 协议、SAML、OAuth2、OpenID Connect 等多种认证协议，每种协议的实现都依赖不同的第三方库。这些库之间可能存在版本冲突，例如不同版本的 XML 解析库、JSON 处理库等。

第四，CAS 的 Overlay 架构。 CAS 官方推荐使用 Overlay 的方式进行定制化部署。Overlay 项目本质上是一个 Gradle 或 Maven 项目，它通过引入 CAS 的各个子模块来构建最终的 WAR/JAR 包。这意味着 Overlay 项目的构建者必须自行管理 CAS 子模块之间的依赖关系，而 CAS 官方提供的 BOM 并不总是能够完美地解决所有冲突。

第五，多仓库依赖解析的复杂性。 CAS 的某些依赖托管在非标准的 Maven 仓库中，如 Shibboleth 仓库、Sonatype 快照仓库等。这些仓库中的依赖版本可能与 Maven Central 中的版本不一致，增加了依赖解析的不确定性。

第六，安全补丁的紧急性。 CAS 作为身份认证系统，安全漏洞的修复往往非常紧急。例如 Log4Shell 漏洞（CVE-2021-44228）要求立即升级 Log4j2 版本，但紧急升级可能引入与 CAS 其他组件不兼容的问题。

1.2 传递依赖的雪崩效应 ​

在 Java 的依赖管理体系中，传递依赖（Transitive Dependency）是一个双刃剑。它极大地简化了开发者的工作——你只需要声明直接依赖，构建工具会自动下载所有间接依赖。但与此同时，传递依赖也是依赖冲突的主要来源。

让我们通过一个具体的例子来理解传递依赖的雪崩效应。假设你的 CAS Overlay 项目引入了以下直接依赖：

cas-server-core
cas-server-support-oauth
cas-server-support-redis-ticket-registry
spring-boot-starter-web
spring-boot-starter-log4j2

这 5 个直接依赖会传递引入数百个间接依赖。例如：

  • cas-server-core 会传递引入 spring-core、spring-web、spring-security-core、commons-lang3、guava 等
  • cas-server-support-oauth 会传递引入 pac4j-core、pac4j-oauth、nimbus-jose-jwt、json-smart 等
  • cas-server-support-redis-ticket-registry 会传递引入 spring-data-redis、jedis、commons-pool2 等
  • spring-boot-starter-web 会传递引入 spring-boot-starter-json、spring-boot-starter-tomcat、spring-webmvc、jackson-databind 等
  • spring-boot-starter-log4j2 会传递引入 log4j-core、log4j-slf4j-impl、slf4j-api 等

问题在于，这些间接依赖中可能存在版本冲突。例如：

  • cas-server-core 可能传递引入 jackson-databind:2.12.3
  • spring-boot-starter-web 可能传递引入 jackson-databind:2.13.4
  • pac4j-core 可能传递引入 jackson-databind:2.11.0

三个不同版本的 jackson-databind 同时出现在依赖树中，构建工具必须选择其中一个版本。如果选择了不兼容的版本，就可能在运行时出现 NoSuchMethodError、ClassNotFoundException 等错误。

更糟糕的是，某些依赖冲突并不会在编译期暴露，而是在运行时才表现出来。这种"编译通过但运行失败"的情况，往往是最难排查的。

1.3 Spring Boot BOM vs CAS BOM 的版本协调 ​

在 CAS Overlay 项目中，通常需要同时导入两个 BOM：Spring Boot BOM 和 CAS BOM。这两个 BOM 都管理了大量相同库的版本，但它们管理的版本可能不同。

以 CAS 5.3.16 为例，该项目基于 Spring Boot 2.7.x 构建。Spring Boot 2.7.x 的 BOM 管理了 log4j:2.17.2 的版本，而 CAS 5.3.16 内部可能需要 log4j:2.12.4。这种版本差异在大多数情况下不会造成问题，但在某些极端情况下，版本不匹配可能导致不可预期的行为。

在 Gradle 中，BOM 的导入方式如下：

groovy
// CAS 5.3 的 BOM 导入方式（使用 dependencyManagement 插件）
dependencyManagement {
    imports {
        mavenBom "org.apereo.cas:cas-server-support-bom:${project['cas.version']}"
        mavenBom 'org.apache.logging.log4j:log4j-bom:2.12.4'
    }
}
groovy
// CAS 6.6 的 BOM 导入方式（使用 platform()）
dependencies {
    implementation platform(org.springframework.boot.gradle.plugin.SpringBootPlugin.BOM_COORDINATES)
    implementation platform("org.apereo.cas:cas-server-support-bom:${project.'cas.version'}")
}
groovy
// CAS 7.3 的 BOM 导入方式（使用 enforcedPlatform()）
dependencies {
    implementation enforcedPlatform("org.apereo.cas:cas-server-support-bom:${project.'cas.version'}")
    implementation platform(org.springframework.boot.gradle.plugin.SpringBootPlugin.BOM_COORDINATES)
}

注意这三个版本中 BOM 导入方式的演变：从 CAS 5.3 的 dependencyManagement 插件方式，到 CAS 6.6 的 platform() 方式，再到 CAS 7.3 的 enforcedPlatform() 方式。这个演变过程本身就是依赖管理策略不断优化的缩影，我们将在后续章节中详细讨论。

BOM 导入顺序的重要性： 当多个 BOM 管理同一个库的不同版本时，BOM 的导入顺序决定了哪个版本会胜出。在 Gradle 中，后导入的 BOM 中的版本会覆盖先导入的 BOM 中的版本。因此，在 CAS 7.3 中，enforcedPlatform("org.apereo.cas:cas-server-support-bom:...") 放在前面，确保 CAS BOM 的版本优先级高于 Spring Boot BOM，这对于保证 CAS 内部组件的兼容性至关重要。

1.4 日志框架冲突：最顽固的敌人 ​

在所有类型的依赖冲突中，日志框架冲突是最常见、最顽固、也最难彻底解决的问题。Java 生态中有多种日志框架并存，包括：

日志框架类型说明
SLF4J门面（Facade）日志抽象层，不提供实际日志实现
Log4j2实现Apache 的日志框架，性能优异
Logback实现Log4j 的继任者，由同一作者开发
java.util.logging (JUL)实现JDK 自带的日志框架
Commons Logging (JCL)门面Apache 的日志抽象层

CAS 项目选择 Log4j2 作为其日志实现，而 Spring Boot 默认使用 Logback。这两者的冲突是 CAS 项目中最常见的依赖冲突类型。

日志框架冲突之所以难以解决，原因在于：

第一，桥接器的复杂性。 SLF4J 提供了多种桥接器，允许将其他日志框架的调用重定向到 SLF4J。例如 jcl-over-slf4j 将 Commons Logging 的调用重定向到 SLF4J，jul-to-slf4j 将 JUL 的调用重定向到 SLF4J。但如果同时存在多个桥接器和多个实现，就可能形成循环调用，导致栈溢出。

第二，log4j-slf4j-impl vs log4j-to-slf4j 的混淆。 这两个名字相似的库实际上功能完全相反：log4j-slf4j-impl 是将 SLF4J 的日志调用路由到 Log4j2（即 Log4j2 作为 SLF4J 的实现），而 log4j-to-slf4j 是将 Log4j2 的日志调用路由到 SLF4J（即 SLF4J 作为 Log4j2 的门面）。如果两者同时存在，就会形成无限递归。

第三，Spring Boot 的默认日志配置。 spring-boot-starter-logging 默认引入了 Logback 作为日志实现。在 CAS 项目中，必须排除这个默认依赖，并替换为 spring-boot-starter-log4j2。但如果某些 CAS 子模块也传递引入了 Logback，就需要在全局范围内排除 Logback。

我们将在第五章中深入分析日志框架冲突的每一个细节。在此，读者只需要理解：日志框架冲突是 CAS 依赖冲突中最核心、最复杂的问题，贯穿了 CAS 5.3、6.6、7.3 三个版本的整个演进历程。

1.5 依赖冲突的三大表现形式 ​

在深入探讨具体的依赖冲突解决策略之前，我们需要先理解依赖冲突的三大表现形式。只有准确识别冲突的类型，才能选择正确的解决方案。

第一类：编译期冲突（Compile-time Conflicts）

编译期冲突是最容易发现的依赖冲突类型。当两个依赖提供了相同包名和类名但不同签名的类时，Java 编译器会报错。编译期冲突通常表现为：

error: reference to xxx is ambiguous

或者：

error: cannot access xxx
class file for xxx not found

编译期冲突的一个典型案例是 javax.annotation 包的冲突。在 Java 8 中，javax.annotation.Resource 等注解由 JDK 提供；但在 Java 9+ 中，这些注解被从 JDK 中移除，需要通过 javax.annotation-api 依赖引入。如果项目中同时存在多个版本的 javax.annotation-api，就可能导致编译期冲突。

在 CAS 项目中，编译期冲突相对较少，因为大部分版本冲突不会改变类的签名。但随着 CAS 从 Java 8（CAS 5.3）迁移到 Java 11（CAS 6.6）再到 Java 21（CAS 7.3），某些 JDK 内置类的变化可能导致编译期冲突。

第二类：运行时冲突（Runtime Conflicts）

运行时冲突是最常见、也最难排查的依赖冲突类型。当构建工具选择了某个版本的依赖，但运行时实际加载的是另一个版本时，就会出现运行时冲突。运行时冲突通常表现为以下几种错误：

NoSuchMethodError：调用的方法在运行时的类版本中不存在。这是最常见的运行时冲突错误，通常发生在依赖升级后，新版本移除或改变了某个方法的签名。

java.lang.NoSuchMethodError: org.springframework.data.redis.connection.RedisConnectionFactory.getConnection()Lorg/springframework/data/redis/connection/RedisConnection;

ClassNotFoundException：运行时需要的类在类路径上找不到。这通常发生在某个依赖被意外排除或版本不匹配时。

java.lang.ClassNotFoundException: org.apache.logging.log4j.spi.ExtendedLoggerWrapper

NoClassDefFoundError：编译时类存在，但运行时找不到。这通常发生在依赖的传递依赖缺失时。

java.lang.NoClassDefFoundError: org/dom4j/DocumentException

AbstractMethodError：子类没有实现父类或接口要求的方法。这通常发生在接口定义发生了变化，但实现类还是旧版本时。

java.lang.AbstractMethodError: org.springframework.data.repository.query.QueryLookupStrategy$Key

LinkageError：类的二进制兼容性问题。这通常发生在同一个类被多个类加载器加载，或者类的定义在运行时发生了变化。

运行时冲突之所以难以排查，是因为它们可能在应用程序启动很久之后才出现，而且错误信息往往不能直接指向冲突的根源。例如，一个 NoSuchMethodError 可能是由完全无关的依赖版本变化间接导致的。

第三类：语义冲突（Semantic Conflicts）

语义冲突是最隐蔽的依赖冲突类型。它不会导致编译错误或运行时异常，但会导致应用程序的行为与预期不符。语义冲突通常发生在两个依赖对同一个功能有不同的实现或配置时。

在 CAS 项目中，语义冲突的典型案例包括：

  1. 日志路由错误： 日志消息被路由到了错误的日志实现，导致日志丢失或格式不正确
  2. XML 解析行为不一致： 不同的 XML 解析器对同一个 XML 文档的解析结果不同，导致 SAML 断言验证失败
  3. 加密算法不一致： 不同的加密库对同一个算法的实现可能存在细微差异，导致票务加密/解密失败
  4. 序列化/反序列化不兼容： 不同版本的 Jackson 对同一个 JSON 字符串的反序列化结果可能不同

语义冲突的排查难度最高，因为它们不会产生任何错误信息。你需要通过仔细的行为分析和对比测试来发现它们。

1.6 为什么 CAS Overlay 项目更容易出现依赖冲突 ​

CAS Overlay 项目相比普通的 Spring Boot 项目，更容易出现依赖冲突。这不仅仅是由于 CAS 自身的复杂性，还与 Overlay 架构的特殊性有关。

第一，Overlay 项目是一个"依赖聚合器"。 Overlay 项目本身不包含 CAS 的源代码，而是通过 Gradle/Maven 依赖引入 CAS 的各个子模块。这意味着 Overlay 项目需要管理所有 CAS 子模块的传递依赖，而 CAS 官方的 BOM 并不总是能够完美覆盖所有场景。

第二，Overlay 项目通常需要引入额外的第三方依赖。 在实际项目中，CAS Overlay 通常需要集成企业内部的用户系统、数据库、消息队列、缓存等。这些额外的依赖可能与 CAS 的依赖产生冲突。例如，企业内部的用户系统可能依赖特定版本的 Jackson 或 Spring Data，与 CAS 使用的版本不一致。

第三，Overlay 项目的构建环境多样性。 不同的开发团队可能使用不同的 IDE、不同的 JDK 版本、不同的 Gradle/Maven 版本。这些环境差异可能导致依赖解析结果不一致——在 A 开发者的机器上构建成功，在 B 开发者的机器上构建失败。

第四，CAS 版本升级的复杂性。 CAS 的版本升级通常涉及大量的依赖版本变化。从 CAS 5.3 升级到 CAS 6.6，不仅 CAS 自身的依赖版本发生了变化，Spring Boot 的版本也可能升级（虽然 CAS 5.3 和 6.6 都基于 Spring Boot 2.7.x，但具体的 Spring Boot 小版本可能不同）。这种连锁反应使得版本升级成为一个高风险的操作。

第五，多模块 CAS 依赖的排列组合。 一个典型的 CAS Overlay 项目可能引入 30-40 个 CAS 子模块。每个子模块都有自己的传递依赖，这些传递依赖之间可能存在版本冲突。随着引入的子模块数量增加，版本冲突的概率呈指数级增长。

第六，CAS 的内部依赖不是完全透明的。 CAS 的某些子模块之间存在内部依赖关系，这些关系并不总是被 BOM 完全覆盖。例如，cas-server-support-oauth 可能内部依赖了特定版本的 pac4j，但这个版本与 BOM 中声明的版本可能不同。这种"隐藏"的依赖关系使得依赖冲突的排查更加困难。

理解了 CAS Overlay 项目容易产生依赖冲突的根本原因，我们才能在后续章节中有针对性地讨论解决方案。接下来，让我们深入分析 CAS 5.3、6.6、7.3 三个版本的依赖管理策略及其演进历程。

第二章 CAS 5.3 的依赖冲突地狱 ​

2.1 CAS 5.3 的技术栈背景 ​

CAS 5.3.x 是一个具有里程碑意义的版本系列。它基于 Spring Boot 2.x 构建，要求 Java 8 运行环境，使用 Gradle 作为主要构建工具（同时也支持 Maven）。CAS 5.3.16 是该系列的一个重要安全更新版本，至今仍有不少生产环境在使用。

CAS 5.3 的技术栈可以概括为：

  • Java 版本： 1.8（Java 8）
  • Spring Boot 版本： 2.7.x
  • Gradle 版本： 7.x
  • 日志框架： Log4j2 2.12.4
  • Servlet API： javax.servlet（Java EE）
  • 嵌入式容器： Tomcat 8.5.x / 9.0.x

在这个技术栈下，CAS 5.3 的依赖管理面临着多重挑战。首先，Spring Boot 2.7.x 的 BOM 与 CAS 5.3 的 BOM 之间存在版本差异；其次，CAS 5.3 的某些子模块内部依赖了较老版本的第三方库；最后，Log4j2 2.12.4 与 Spring Boot 默认的 Logback 之间存在根本性的冲突。

2.2 每个模块 5-7 个 exclude 的噩梦 ​

在 CAS 5.3 的 Overlay 项目中，最显著的特征就是每个 CAS 模块依赖都带有大量的 exclude 声明。让我们看一个真实的例子：

groovy
// CAS 5.3 中典型的模块依赖声明
implementation('org.apereo.cas:cas-server-support-rest-authentication') {
    exclude group: 'org.springframework.boot', module: 'spring-boot-devtools'
    exclude group: 'org.apache.logging.log4j', module: 'log4j-slf4j-impl'
    exclude group: 'org.apache.logging.log4j', module: 'log4j-web'
    exclude group: 'org.slf4j', module: 'slf4j-api'
    exclude group: 'org.slf4j', module: 'jul-to-slf4j'
    exclude group: 'dom4j', module: 'dom4j'
}

一个模块就需要 6 个 exclude！而在一个典型的 CAS 5.3 Overlay 项目中，往往需要引入 30-40 个 CAS 子模块。这意味着你需要编写 180-240 个 exclude 声明。这不仅极其繁琐，而且容易出错——漏掉任何一个 exclude 都可能导致运行时的依赖冲突。

在我们的实际项目中，CAS 5.3 的 build.gradle 文件中包含了超过 35 个 CAS 模块依赖，每个模块都带有 5-7 个 exclude 声明。整个 dependencies 块的代码量超过了 500 行，其中大部分都是重复的 exclude 声明。

这种"复制粘贴"式的依赖管理方式带来了严重的问题：

  1. 维护成本极高： 每次新增一个 CAS 模块，都需要复制粘贴一整套 exclude 声明
  2. 容易遗漏： 人工复制粘贴很容易漏掉某个 exclude，导致隐蔽的依赖冲突
  3. 难以审计： 当依赖冲突发生时，很难快速定位是哪个模块的哪个 exclude 没有生效
  4. 升级困难： 当 CAS 版本升级时，可能需要调整 exclude 列表，但很难确保所有模块都正确更新

2.3 典型排除项详解 ​

让我们逐一分析 CAS 5.3 中每个典型排除项的原因和作用。

2.3.1 spring-boot-devtools ​

groovy
exclude group: 'org.springframework.boot', module: 'spring-boot-devtools'

spring-boot-devtools 是 Spring Boot 的开发工具模块，它提供了热重载、自动重启、LiveReload 等开发时便利功能。然而，在 CAS 的生产环境中，这个模块是不需要的，而且它可能导致以下问题：

  • 类加载器冲突： devtools 使用两个类加载器（base classloader 和 restart classloader），这在 CAS 的复杂类加载环境中可能引发问题
  • 自动重启干扰： 在生产环境中，devtools 的自动重启功能可能导致不可预期的服务中断
  • 安全风险： devtools 暴露了一些调试端点，在生产环境中不应启用

2.3.2 log4j-slf4j-impl ​

groovy
exclude group: 'org.apache.logging.log4j', module: 'log4j-slf4j-impl'

这是 CAS 5.3 中最关键的排除项之一。log4j-slf4j-impl 是 Log4j2 的 SLF4J 绑定实现，它将 SLF4J 的日志调用路由到 Log4j2。

为什么需要排除它？因为在 CAS 5.3 中，某些 CAS 子模块传递引入了 log4j-slf4j-impl 的特定版本，而我们的 Overlay 项目通过 spring-boot-starter-log4j2 已经引入了统一版本的 log4j-slf4j-impl。如果两个版本同时存在，可能导致日志绑定混乱。

此外，在 CAS 5.3 的某些场景中，我们需要更精细地控制 Log4j2 的版本（例如锁定为 2.12.4），因此需要排除子模块传递引入的版本，由 BOM 统一管理。

2.3.3 log4j-web ​

groovy
exclude group: 'org.apache.logging.log4j', module: 'log4j-web'

log4j-web 是 Log4j2 的 Web 模块，它提供了在 Servlet 容器中自动初始化 Log4j2 的功能。在 Spring Boot 的嵌入式容器环境中，Log4j2 的初始化由 Spring Boot 负责，不需要 log4j-web 的介入。如果两者同时存在，可能导致 Log4j2 被初始化两次，引发不可预期的行为。

2.3.4 slf4j-api ​

groovy
exclude group: 'org.slf4j', module: 'slf4j-api'

slf4j-api 是 SLF4J 的核心 API 包。在正常情况下，排除 slf4j-api 似乎不合理——毕竟它是日志门面的核心。但在 CAS 5.3 的上下文中，某些子模块传递引入了与项目不兼容的 slf4j-api 版本。通过排除这些传递依赖，确保使用由 BOM 统一管理的 slf4j-api 版本。

需要注意的是，这个排除项在 CAS 6.6 和 7.3 中已经不再需要，因为 BOM 已经能够正确地统一管理 slf4j-api 的版本。

2.3.5 jul-to-slf4j ​

groovy
exclude group: 'org.slf4j', module: 'jul-to-slf4j'

jul-to-slf4j 是 SLF4J 的 JUL 桥接器，它将 java.util.logging 的日志调用重定向到 SLF4J。在 CAS 5.3 中，某些子模块传递引入了这个桥接器，而 Spring Boot 也通过 spring-boot-starter-logging 引入了它。重复的桥接器可能导致日志路由混乱。

2.3.6 dom4j ​

groovy
exclude group: 'dom4j', module: 'dom4j'

dom4j 是一个 XML 解析库，CAS 内部大量使用了它。然而，不同版本的 dom4j 之间存在 API 不兼容的问题。在 CAS 5.3 中，某些子模块传递引入了旧版本的 dom4j（group 为 dom4j），而我们的项目需要使用新版本的 org.dom4j:dom4j:2.1.3（group 为 org.dom4j）。注意这里的 groupId 变化：旧版本使用 dom4j:dom4j，新版本使用 org.dom4j:dom4j。通过排除旧版本的传递依赖，确保使用统一的 dom4j 版本。

2.4 显式版本锁定的必要性 ​

在 CAS 5.3 中，仅靠 BOM 和 exclude 还不足以解决所有依赖冲突。某些关键依赖需要显式锁定版本，以确保运行时的兼容性。以下是最常见的需要显式锁定版本的依赖：

groovy
dependencyManagement {
    dependencies {
        // Log4j2 版本锁定
        dependency 'org.apache.logging.log4j:log4j-core:2.12.4'

        // Spring Data Redis 版本锁定（与 CAS 5.3.16 兼容）
        // 注意：CAS 5.3 内部使用的 Spring Data Redis 版本较老
        // 必须显式指定，否则可能引入不兼容的新版本
        dependency 'org.springframework.data:spring-data-redis:1.8.23.RELEASE'
        dependency 'redis.clients:jedis:2.9.3'

        // Tomcat 版本锁定
        dependency 'org.apache.tomcat.embed:tomcat-embed-core:8.5.32'
        dependency 'org.apache.tomcat.embed:tomcat-embed-websocket:8.5.32'

        // 其他关键依赖版本锁定
        dependency 'commons-beanutils:commons-beanutils:1.9.4'
        dependency 'org.dom4j:dom4j:2.1.3'
        dependency 'org.apache.commons:commons-configuration2:2.8.0'
        dependency 'org.jsoup:jsoup:1.15.3'
        dependency 'ch.qos.logback:logback-core:1.1.11'
        dependency 'ch.qos.logback:logback-classic:1.1.11'
        dependency 'org.quartz-scheduler:quartz:2.3.2'

        // Jackson 版本锁定
        dependency 'com.fasterxml.jackson.core:jackson-databind:2.13.4.2'
        dependency 'com.fasterxml.jackson.core:jackson-core:2.13.4'
        dependency 'com.fasterxml.jackson.core:jackson-annotations:2.13.4'
    }
}

为什么 spring-data-redis 需要锁定为 1.8.23.RELEASE？

这是一个非常典型的问题。CAS 5.3.16 内部使用的 Spring Framework 版本较老（Spring 5.x），而 spring-data-redis:1.8.x 是与之兼容的版本。如果让 BOM 自动解析版本，可能会引入 spring-data-redis:2.x，这个版本需要 Spring Framework 5.2+ 和 Spring Data Key Value 2.x，与 CAS 5.3 内部的 Spring 版本不兼容。

不兼容的表现可能包括：

  • NoSuchMethodError: org.springframework.data.repository.query.QueryLookupStrategy$Key
  • NoClassDefFoundError: org/springframework/data/redis/connection/RedisConnectionFactory
  • Redis 连接池初始化失败

为什么 jedis 需要锁定为 2.9.3？

jedis:2.9.3 与 spring-data-redis:1.8.x 是配套使用的。jedis:3.x 改变了连接池的实现方式，不再使用 commons-pool2，而是使用了自己的连接池实现。如果使用 jedis:3.x 配合 spring-data-redis:1.8.x，可能导致连接池配置失效或连接泄漏。

为什么 tomcat-embed-core 需要锁定为 8.5.32？

CAS 5.3 最初设计时基于 Tomcat 8.5.x。虽然 Spring Boot 2.7.x 默认使用 Tomcat 9.0.x，但 CAS 5.3 的某些内部组件（如 CAS WebApp Config）可能依赖于 Tomcat 8.5.x 的特定行为。锁定 Tomcat 版本可以避免因 Tomcat 升级导致的 Servlet API 不兼容问题。

2.5 Log4j BOM 独立导入 ​

在 CAS 5.3 中，Log4j2 的版本管理是一个特别需要关注的问题。由于 CAS BOM 和 Spring Boot BOM 管理的 Log4j2 版本可能不同，我们需要独立导入 Log4j BOM 来确保版本一致性：

groovy
dependencyManagement {
    imports {
        mavenBom "org.apereo.cas:cas-server-support-bom:${project['cas.version']}"
        // 独立导入 Log4j BOM，确保所有 Log4j2 组件使用同一版本
        mavenBom 'org.apache.logging.log4j:log4j-bom:2.12.4'
    }
    dependencies {
        dependency 'org.apache.logging.log4j:log4j-core:2.12.4'
    }
}

Log4j BOM 管理了所有 Log4j2 相关组件的版本，包括：

  • log4j-api：Log4j2 的 API 模块
  • log4j-core：Log4j2 的核心实现
  • log4j-slf4j-impl：SLF4J 到 Log4j2 的绑定
  • log4j-web：Servlet 容器集成模块
  • log4j-jul：JUL 到 Log4j2 的桥接器

通过导入 Log4j BOM，可以确保所有这些组件使用同一个版本（2.12.4），避免因版本不一致导致的 API 不兼容问题。

为什么选择 Log4j2 2.12.4 而不是更新的版本？

CAS 5.3.16 发布时，Log4j2 2.12.4 是经过充分验证的稳定版本。虽然 Log4j2 后续发布了 2.17.x（修复了 Log4Shell 漏洞 CVE-2021-44228），但在 CAS 5.3 的环境中升级 Log4j2 版本需要谨慎评估：

  1. CAS 5.3 的某些内部组件可能依赖于 Log4j2 2.12.x 的特定行为
  2. Log4j2 2.17.x 引入了一些配置格式的变化
  3. 在生产环境中升级日志框架版本需要充分的回归测试

在实际项目中，如果安全合规要求必须使用 Log4j2 2.17.x，建议先在测试环境中进行全面的回归测试，确认没有兼容性问题后再升级。

2.6 configurations.all 全局排除策略 ​

在 CAS 5.3 的 Gradle 配置中，除了逐个模块的 exclude 之外，还使用了 configurations.all 来进行全局排除：

groovy
// 全局排除 xpp3 依赖，避免 XML 解析器冲突
configurations.all {
    exclude group: 'xpp3', module: 'xpp3'
    exclude group: 'xpp3', module: 'xpp3_min'
}

configurations.all 是 Gradle 提供的一种全局配置机制，它会对项目中所有的 configuration（包括 compileClasspath、runtimeClasspath、testCompileClasspath 等）生效。这意味着，无论哪个模块传递引入了 xpp3 依赖，都会被自动排除。

在 CAS 5.3 中，xpp3 的全局排除是一个典型的 XML 解析器冲突解决方案。xpp3（XML Pull Parser 3）是一个轻量级的 XML 解析器，某些 CAS 子模块（特别是与 XML 配置相关的模块）会传递引入它。然而，xpp3 与 CAS 使用的其他 XML 解析库（如 xercesImpl、dom4j）可能存在冲突，导致 XML 解析行为不一致。

通过全局排除 xpp3，可以确保项目中只使用统一的 XML 解析器（xercesImpl），避免解析器冲突。

configurations.all vs 逐个 exclude 的优劣对比：

维度configurations.all逐个 exclude
作用范围所有 configuration仅指定的依赖
维护成本低（一处修改）高（多处修改）
精确度较低（可能误排）高（精确控制）
可读性好（集中管理）差（分散在各处）
灵活性低（全局生效）高（按需排除）

在 CAS 5.3 中，configurations.all 主要用于排除那些在所有模块中都不应该出现的依赖（如 xpp3），而逐个 exclude 则用于处理特定模块的依赖冲突。

2.7 xpp3 排除与 XML 解析器冲突 ​

XML 解析器冲突是 Java 项目中一类特殊的依赖冲突。在 CAS 5.3 中，这个问题尤为突出，因为 CAS 大量使用了 XML 配置（如 Spring XML 配置、SAML 元数据、票务注册表配置等）。

Java 生态中常见的 XML 解析器包括：

解析器说明使用场景
XercesApache 的 XML 解析器SAX/DOM 解析
dom4j易用的 XML 解析框架XML 文档操作
JDOMJava 的 XML APIXML 文档操作
xpp3XML Pull Parser流式 XML 解析
StAX (JSR-173)流式 XML 处理 API高性能 XML 处理

在 CAS 5.3 中，XML 解析器冲突主要表现在以下几个方面：

第一，SAX 解析器冲突。 不同的 XML 解析器都提供了 SAX 解析器的实现，它们通过 META-INF/services/javax.xml.parsers.SAXParserFactory SPI 机制注册。当多个解析器同时存在时，Java 的 ServiceLoader 会选择其中一个，但选择的结果可能不是我们期望的。

第二，DOM 解析器冲突。 类似地，不同的 XML 解析器也提供了 DOM 解析器的实现，通过 META-INF/services/javax.xml.parsers.DocumentBuilderFactory 注册。多个解析器同时存在时，可能导致 DOM 解析行为不一致。

第三，XPath 引擎冲突。 不同的 XML 解析器对 XPath 的支持程度不同，某些 XPath 表达式在一个解析器中可以正常工作，但在另一个解析器中可能失败。

在 CAS 5.3 中，我们通过以下方式解决 XML 解析器冲突：

groovy
// 排除 xpp3，避免与 xercesImpl 冲突
configurations.all {
    exclude group: 'xpp3', module: 'xpp3'
    exclude group: 'xpp3', module: 'xpp3_min'
}

// 显式引入 xercesImpl 和 xalan
dependencies {
    implementation 'xalan:xalan:2.7.3'
    implementation 'xalan:serializer:2.7.2'
    implementation 'xerces:xercesImpl:2.12.2'
}

通过排除 xpp3 并显式引入 xercesImpl，确保项目中使用统一的 XML 解析器。xalan 和 serializer 则提供了 XSLT 转换功能，CAS 的某些功能（如主题渲染）依赖于它们。

2.8 CAS 5.3 完整配置示例（教学简化版） ​

以下是一个教学用途的简化版 CAS 5.3 Gradle 配置，展示了核心的依赖管理策略：

groovy
// ========================================
// CAS 5.3 Overlay - 教学简化版 build.gradle
// ========================================

buildscript {
    repositories {
        mavenCentral()
        maven {
            url 'https://build.shibboleth.net/nexus/content/repositories/releases'
        }
    }
    dependencies {
        classpath "org.springframework.boot:spring-boot-gradle-plugin:${springBootVersion}"
    }
}

apply plugin: 'eclipse'
apply plugin: 'java'
apply plugin: 'org.springframework.boot'
apply plugin: 'io.spring.dependency-management'

group = 'com.example.cas'
version = '1.0-SNAPSHOT'
description = 'CAS 5.3 Overlay - 教学简化版'
archivesBaseName = 'cas-overlay'

java {
    sourceCompatibility = JavaVersion.VERSION_1_8
    targetCompatibility = JavaVersion.VERSION_1_8
}

tasks.withType(JavaCompile) {
    options.encoding = 'UTF-8'
}

repositories {
    mavenCentral()
    maven {
        url 'https://build.shibboleth.net/nexus/content/repositories/releases'
    }
}

// ========================================
// 依赖版本管理（核心）
// ========================================
dependencyManagement {
    imports {
        // CAS BOM
        mavenBom "org.apereo.cas:cas-server-support-bom:${project['cas.version']}"
        // Log4j BOM - 独立导入，确保版本一致
        mavenBom 'org.apache.logging.log4j:log4j-bom:2.12.4'
    }
    dependencies {
        // Log4j2 核心版本锁定
        dependency 'org.apache.logging.log4j:log4j-core:2.12.4'
        // Spring Data Redis 版本锁定（与 CAS 5.3 兼容）
        dependency 'org.springframework.data:spring-data-redis:1.8.23.RELEASE'
        dependency 'redis.clients:jedis:2.9.3'
        // Tomcat 版本锁定
        dependency 'org.apache.tomcat.embed:tomcat-embed-core:8.5.32'
        dependency 'org.apache.tomcat.embed:tomcat-embed-websocket:8.5.32'
        // 关键依赖版本锁定
        dependency 'commons-beanutils:commons-beanutils:1.9.4'
        dependency 'org.dom4j:dom4j:2.1.3'
        dependency 'org.apache.commons:commons-configuration2:2.8.0'
        dependency 'org.jsoup:jsoup:1.15.3'
        dependency 'ch.qos.logback:logback-core:1.1.11'
        dependency 'ch.qos.logback:logback-classic:1.1.11'
        dependency 'org.quartz-scheduler:quartz:2.3.2'
        // Jackson 版本锁定
        dependency 'com.fasterxml.jackson.core:jackson-databind:2.13.4.2'
        dependency 'com.fasterxml.jackson.core:jackson-core:2.13.4'
        dependency 'com.fasterxml.jackson.core:jackson-annotations:2.13.4'
    }
}

// ========================================
// 全局排除策略
// ========================================
configurations.all {
    exclude group: 'xpp3', module: 'xpp3'
    exclude group: 'xpp3', module: 'xpp3_min'
}

// ========================================
// 依赖声明（每个模块都需要大量 exclude）
// ========================================
dependencies {
    // --- CAS 核心模块（每个都需要 5-7 个 exclude）---
    implementation('org.apereo.cas:cas-server-core') {
        exclude group: 'org.springframework.boot', module: 'spring-boot-devtools'
        exclude group: 'org.apache.logging.log4j', module: 'log4j-slf4j-impl'
        exclude group: 'dom4j', module: 'dom4j'
    }

    implementation('org.apereo.cas:cas-server-support-rest-authentication') {
        exclude group: 'org.springframework.boot', module: 'spring-boot-devtools'
        exclude group: 'org.apache.logging.log4j', module: 'log4j-slf4j-impl'
        exclude group: 'org.apache.logging.log4j', module: 'log4j-web'
        exclude group: 'org.slf4j', module: 'slf4j-api'
        exclude group: 'org.slf4j', module: 'jul-to-slf4j'
        exclude group: 'dom4j', module: 'dom4j'
    }

    implementation('org.apereo.cas:cas-server-support-rest') {
        exclude group: 'org.springframework.boot', module: 'spring-boot-devtools'
        exclude group: 'org.apache.logging.log4j', module: 'log4j-slf4j-impl'
        exclude group: 'org.apache.logging.log4j', module: 'log4j-web'
        exclude group: 'org.slf4j', module: 'slf4j-api'
        exclude group: 'org.slf4j', module: 'jul-to-slf4j'
        exclude group: 'dom4j', module: 'dom4j'
    }

    implementation('org.apereo.cas:cas-server-support-redis-ticket-registry') {
        exclude group: 'org.springframework.boot', module: 'spring-boot-devtools'
        exclude group: 'org.apache.logging.log4j', module: 'log4j-slf4j-impl'
        exclude group: 'org.apache.logging.log4j', module: 'log4j-web'
        exclude group: 'org.slf4j', module: 'slf4j-api'
        exclude group: 'org.slf4j', module: 'jul-to-slf4j'
        exclude group: 'dom4j', module: 'dom4j'
    }

    // ... 更多 CAS 模块，每个都需要类似的 exclude 声明 ...

    // --- 显式版本声明的依赖 ---
    implementation 'org.springframework.data:spring-data-redis:1.8.23.RELEASE'
    implementation 'redis.clients:jedis:2.9.3'

    // --- XML 解析器 ---
    implementation 'xalan:xalan:2.7.3'
    implementation 'xalan:serializer:2.7.2'
    implementation 'xerces:xercesImpl:2.12.2'

    // --- Spring Boot Starters ---
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.boot:spring-boot-starter-tomcat'

    implementation('org.springframework.boot:spring-boot-starter-thymeleaf') {
        exclude group: 'ch.qos.logback', module: 'logback-classic'
        exclude group: 'org.springframework.boot', module: 'spring-boot-starter-logging'
    }

    // --- 日志框架 ---
    implementation 'org.apache.logging.log4j:log4j-api'
    implementation 'org.apache.logging.log4j:log4j-core'

    implementation('org.springframework.boot:spring-boot-starter-log4j2') {
        exclude group: 'org.apache.logging.log4j', module: 'log4j-slf4j-impl'
        exclude group: 'org.apache.logging.log4j', module: 'log4j-jul'
    }

    // --- 其他依赖 ---
    implementation 'org.dom4j:dom4j'
    implementation 'org.bouncycastle:bcprov-jdk15on'
}

// ========================================
// 打包配置
// ========================================
tasks.named('bootJar') {
    archiveFileName = 'cas-overlay.jar'
    requiresUnpack '**/*.jar'
}

springBoot {
    mainClass = 'com.example.cas.CasWebApplication'
}

配置要点总结：

  1. BOM 导入： 使用 dependencyManagement 插件导入 CAS BOM 和 Log4j BOM
  2. 版本锁定： 在 dependencyManagement.dependencies 中显式声明关键依赖的版本
  3. 全局排除： 使用 configurations.all 全局排除 xpp3
  4. 逐个排除： 每个 CAS 模块都需要 5-7 个 exclude 声明
  5. 日志框架： 排除 spring-boot-starter-logging，使用 spring-boot-starter-log4j2

2.9 CAS 5.3 Maven 版本的依赖管理 ​

CAS 5.3 同时支持 Gradle 和 Maven 两种构建工具。虽然 Gradle 是 CAS 官方推荐的构建工具，但许多企业团队仍然使用 Maven。Maven 版本的依赖管理与 Gradle 版本有着显著的差异。

Maven 的 dependencyManagement 机制：

Maven 通过 <dependencyManagement> 元素来管理依赖版本。与 Gradle 的 platform() 不同，Maven 的 dependencyManagement 是一种"建议"机制——如果子 POM 或依赖中显式指定了版本，显式版本会优先。

xml
<!-- CAS 5.3 Maven 版本的 dependencyManagement -->
<dependencyManagement>
    <dependencies>
        <!-- CAS BOM -->
        <dependency>
            <groupId>org.apereo.cas</groupId>
            <artifactId>cas-server-support-bom</artifactId>
            <version>${cas.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
        <!-- Log4j BOM -->
        <dependency>
            <groupId>org.apache.logging.log4j</groupId>
            <artifactId>log4j-bom</artifactId>
            <version>2.12.4</version>
            <scope>import</scope>
            <type>pom</type>
        </dependency>
        <!-- 显式版本声明 -->
        <dependency>
            <groupId>org.apache.logging.log4j</groupId>
            <artifactId>log4j-core</artifactId>
            <version>2.12.4</version>
        </dependency>
        <dependency>
            <groupId>commons-beanutils</groupId>
            <artifactId>commons-beanutils</artifactId>
            <version>1.9.4</version>
        </dependency>
        <dependency>
            <groupId>org.dom4j</groupId>
            <artifactId>dom4j</artifactId>
            <version>2.1.3</version>
        </dependency>
        <!-- 更多版本声明... -->
    </dependencies>
</dependencyManagement>

Maven 的排除机制：

Maven 使用 <exclusions> 元素来排除传递依赖。与 Gradle 不同，Maven 的排除是针对单个依赖的，不支持全局排除（除非使用 Maven Enforcer 插件）。

xml
<!-- Maven 中每个依赖都需要单独声明排除 -->
<dependency>
    <groupId>org.apereo.cas</groupId>
    <artifactId>cas-server-support-rest-authentication</artifactId>
    <exclusions>
        <exclusion>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-devtools</artifactId>
        </exclusion>
        <exclusion>
            <groupId>org.apache.logging.log4j</groupId>
            <artifactId>log4j-slf4j-impl</artifactId>
        </exclusion>
        <exclusion>
            <groupId>org.apache.logging.log4j</groupId>
            <artifactId>log4j-web</artifactId>
        </exclusion>
        <exclusion>
            <groupId>org.slf4j</groupId>
            <artifactId>slf4j-api</artifactId>
        </exclusion>
        <exclusion>
            <groupId>org.slf4j</groupId>
            <artifactId>jul-to-slf4j</artifactId>
        </exclusion>
        <exclusion>
            <groupId>dom4j</groupId>
            <artifactId>dom4j</artifactId>
        </exclusion>
    </exclusions>
</dependency>

Gradle vs Maven 排除机制对比：

特性GradleMaven
全局排除configurations.all { exclude ... }不支持（需用 Enforcer 插件）
逐个排除exclude group:..., module:...<exclusions><exclusion>...</exclusion></exclusions>
排除传递依赖的传递依赖自动递归排除只排除直接传递依赖
排除语法简洁度高（一行）低（多行 XML）

Maven 的排除机制有一个重要的限制：它只能排除直接传递依赖，不能排除传递依赖的传递依赖。例如，如果 A 依赖 B，B 依赖 C，C 依赖 D，你在 A 中排除 C，那么 D 也会被排除。但如果你只想排除 D 而保留 C，Maven 做不到（Gradle 可以通过更精细的配置实现）。

2.10 CAS 5.3 中常见的运行时错误与排查 ​

在 CAS 5.3 的实际项目中，以下运行时错误是最常见的依赖冲突表现。我们逐一分析其根本原因和解决方案。

错误一：Log4j2 初始化失败

ERROR StatusLogger Log4j2 could not find a logging implementation.
Please add log4j-core to the classpath.

根本原因： log4j-slf4j-impl 被排除或版本不匹配，导致 SLF4J 无法找到 Log4j2 的绑定实现。

解决方案： 确保 log4j-slf4j-impl 和 log4j-core 在类路径上，且版本一致：

groovy
implementation 'org.apache.logging.log4j:log4j-api'
implementation 'org.apache.logging.log4j:log4j-core'
// 确保使用正确版本的 log4j-slf4j-impl
implementation('org.springframework.boot:spring-boot-starter-log4j2') {
    exclude group: 'org.apache.logging.log4j', module: 'log4j-slf4j-impl'
}
// 显式引入正确版本
implementation 'org.apache.logging.log4j:log4j-slf4j-impl:2.12.4'

错误二：Redis 连接失败

org.springframework.data.redis.RedisConnectionFailureException:
Unable to connect to Redis; nested exception is io.lettuce.core.RedisConnectionException:
Unable to connect to localhost:6379

根本原因： 在 CAS 5.3 中，这通常不是网络问题，而是 spring-data-redis 版本不匹配导致的。如果 spring-data-redis 的版本与 jedis 的版本不兼容，连接池的初始化可能失败。

解决方案： 显式指定兼容的版本：

groovy
implementation 'org.springframework.data:spring-data-redis:1.8.23.RELEASE'
implementation 'redis.clients:jedis:2.9.3'

错误三：SAML 断言解析失败

org.opensaml.core.xml.XMLParserException: Failed to unmarshal XML

根本原因： XML 解析器冲突。多个 XML 解析器同时存在于类路径上，导致 SAML 断言的 XML 解析使用了错误的解析器。

解决方案： 排除 xpp3，确保使用 xercesImpl：

groovy
configurations.all {
    exclude group: 'xpp3', module: 'xpp3'
    exclude group: 'xpp3', module: 'xpp3_min'
}
implementation 'xerces:xercesImpl:2.12.2'

错误四：Spring Boot 启动失败

org.springframework.beans.factory.BeanCreationException:
Error creating bean with name 'entityManagerFactory' defined in class path resource [...]

根本原因： 多种可能，包括 Hibernate 版本不兼容、JPA 配置冲突、或者 spring-boot-devtools 导致的类加载器问题。

解决方案： 排除 spring-boot-devtools，检查 Hibernate 和 JPA 的版本兼容性。

错误排查的通用方法论：

  1. 查看完整的堆栈跟踪： 不要只看异常消息，要查看完整的堆栈跟踪，找到异常的根源
  2. 使用 dependencyInsight 分析： 确定冲突依赖的来源
  3. 对比已知正常的依赖树： 如果有正常工作的环境，对比两者的依赖树差异
  4. 逐步排除法： 注释掉一半的依赖，看问题是否消失，然后逐步缩小范围
  5. 使用 -verbose:class JVM 参数： 查看类加载的详细信息，确认实际加载的类来自哪个 JAR

第三章 CAS 6.6 的依赖管理优化 ​

3.1 从手动排除到 platform() BOM 导入 ​

CAS 6.6.x 是一个承上启下的版本系列。它基于 Spring Boot 2.7.x 构建，要求 Java 11 运行环境。相比 CAS 5.3，CAS 6.6 在依赖管理方面做出了重大改进，最核心的变化就是引入了 platform() BOM 导入方式。

在 CAS 5.3 中，BOM 的导入使用的是 io.spring.dependency-management 插件的 mavenBom 方式：

groovy
// CAS 5.3 的 BOM 导入方式
dependencyManagement {
    imports {
        mavenBom "org.apereo.cas:cas-server-support-bom:${project['cas.version']}"
        mavenBom 'org.apache.logging.log4j:log4j-bom:2.12.4'
    }
}

而在 CAS 6.6 中，BOM 的导入方式改为了 Gradle 原生的 platform()：

groovy
// CAS 6.6 的 BOM 导入方式
dependencies {
    implementation platform(org.springframework.boot.gradle.plugin.SpringBootPlugin.BOM_COORDINATES)
    implementation platform("org.apereo.cas:cas-server-support-bom:${project.'cas.version'}")
}

这个变化看似简单，但意义重大。platform() 是 Gradle 5.0+ 引入的原生 BOM 支持功能，相比 io.spring.dependency-management 插件，它有以下优势：

第一，原生支持。 platform() 是 Gradle 内置的功能，不需要额外的插件。这意味着它能够更好地与 Gradle 的其他功能（如 resolutionStrategy）集成。

第二，更精确的版本控制。 platform() 导入的 BOM 只影响版本管理，不会将 BOM 本身作为依赖引入。而 mavenBom 方式在某些情况下可能会产生副作用。

第三，更好的冲突解决。 platform() 与 Gradle 的依赖解析引擎深度集成，能够更智能地处理版本冲突。

第四，支持 enforcedPlatform()。 platform() 有一个强化版本 enforcedPlatform()，它不仅提供版本建议，还强制要求使用 BOM 中指定的版本。这个功能在 CAS 7.3 中得到了广泛应用。

3.2 configurations.all 全局排除策略 ​

CAS 6.6 在全局排除策略上相比 CAS 5.3 有了显著的改进。在 CAS 5.3 中，全局排除只针对 xpp3，而大部分排除工作仍然需要逐个模块处理。在 CAS 6.6 中，configurations.all 的排除范围大大扩展：

groovy
// CAS 6.6 的全局排除策略
configurations {
    all {
        resolutionStrategy {
            cacheChangingModulesFor 0, "seconds"
            cacheDynamicVersionsFor 0, "seconds"
            preferProjectModules()

            // 可选：开启版本冲突严格模式
            def failIfConflict = project.hasProperty("failOnVersionConflict") &&
                Boolean.valueOf(project.getProperty("failOnVersionConflict"))
            if (failIfConflict) {
                failOnVersionConflict()
            }

            // 可选：Tomcat 版本覆盖
            if (project.hasProperty("tomcatVersion")) {
                eachDependency { DependencyResolveDetails dependency ->
                    def requested = dependency.requested
                    if (requested.group.startsWith("org.apache.tomcat") &&
                        requested.name != "jakartaee-migration") {
                        dependency.useVersion("${tomcatVersion}")
                    }
                }
            }
        }

        // 全局排除日志框架冲突
        exclude(group: "cglib", module: "cglib")
        exclude(group: "cglib", module: "cglib-full")
        exclude(group: "org.slf4j", module: "slf4j-log4j12")
        exclude(group: "org.slf4j", module: "slf4j-simple")
        exclude(group: "org.slf4j", module: "jcl-over-slf4j")
        exclude(group: "org.apache.logging.log4j", module: "log4j-to-slf4j")
        exclude(group: "ch.qos.logback", module: "logback-core")
        exclude(group: "ch.qos.logback", module: "logback-classic")
    }
}

让我们逐一分析这些全局排除项的作用：

cglib 排除：

groovy
exclude(group: "cglib", module: "cglib")
exclude(group: "cglib", module: "cglib-full")

cglib 是一个代码生成库，Spring Framework 使用它来实现 CGLIB 代理。然而，cglib 已经停止维护，Spring Framework 5.x 开始使用 spring-core 内置的 Objenesis 和 CglibAopProxy 来替代。某些旧版本的第三方库仍然依赖 cglib，全局排除可以避免版本冲突。

SLF4J 桥接器排除：

groovy
exclude(group: "org.slf4j", module: "slf4j-log4j12")
exclude(group: "org.slf4j", module: "slf4j-simple")
exclude(group: "org.slf4j", module: "jcl-over-slf4j")

这三个排除项确保了 SLF4J 的日志路由不会产生冲突。slf4j-log4j12 是 SLF4J 到 Log4j 1.x 的绑定（注意不是 Log4j2），如果它与 log4j-slf4j-impl（SLF4J 到 Log4j2 的绑定）同时存在，会导致 SLF4J 绑定冲突。slf4j-simple 是一个简单的日志实现，不适合生产环境。jcl-over-slf4j 将 Commons Logging 重定向到 SLF4J，在某些场景下可能与 Spring 的 JCL 集成产生冲突。

Log4j2 桥接器排除：

groovy
exclude(group: "org.apache.logging.log4j", module: "log4j-to-slf4j")

log4j-to-slf4j 将 Log4j2 的日志调用路由到 SLF4J。在 CAS 项目中，我们使用 Log4j2 作为最终日志实现，不需要这个反向桥接器。如果它与 log4j-slf4j-impl 同时存在，会形成循环调用。

Logback 排除：

groovy
exclude(group: "ch.qos.logback", module: "logback-core")
exclude(group: "ch.qos.logback", module: "logback-classic")

CAS 使用 Log4j2 而非 Logback。全局排除 Logback 可以确保不会有任何子模块意外引入 Logback，从而避免两个日志实现同时存在的问题。

resolutionStrategy 配置：

groovy
resolutionStrategy {
    cacheChangingModulesFor 0, "seconds"
    cacheDynamicVersionsFor 0, "seconds"
    preferProjectModules()
}
  • cacheChangingModulesFor 0, "seconds"：不缓存动态版本模块，确保每次构建都获取最新版本
  • cacheDynamicVersionsFor 0, "seconds"：不缓存变化中的模块，确保每次构建都检查更新
  • preferProjectModules()：优先使用项目模块而非外部依赖

failOnVersionConflict 严格模式：

groovy
def failIfConflict = project.hasProperty("failOnVersionConflict") &&
    Boolean.valueOf(project.getProperty("failOnVersionConflict"))
if (failIfConflict) {
    failOnVersionConflict()
}

这是一个非常有用的调试功能。当开启 failOnVersionConflict 时，Gradle 会在发现版本冲突时立即失败，而不是静默地选择一个版本。这对于发现和解决隐蔽的依赖冲突非常有帮助。

可以通过以下方式启用：

bash
./gradlew build -PfailOnVersionConflict=true

3.3 不再需要显式指定 spring-data-redis 和 jedis 版本 ​

CAS 6.6 的一个重要改进是，不再需要像 CAS 5.3 那样显式指定 spring-data-redis 和 jedis 的版本。在 CAS 5.3 中，我们需要：

groovy
// CAS 5.3 中必须显式指定版本
implementation 'org.springframework.data:spring-data-redis:1.8.23.RELEASE'
implementation 'redis.clients:jedis:2.9.3'

而在 CAS 6.6 中，只需要：

groovy
// CAS 6.6 中不需要指定版本，由 BOM 管理
implementation "org.apereo.cas:cas-server-support-redis-ticket-registry"
// spring-data-redis 和 jedis 的版本由 CAS BOM 自动管理

这是因为 CAS 6.6 的 BOM 已经正确地管理了 spring-data-redis 和 jedis 的版本。CAS 6.6 基于 Spring Boot 2.7.x，其 BOM 中已经包含了与 Spring Data Redis 2.x 和 Jedis 3.x 兼容的版本声明。

这个改进的意义在于：

  1. 减少了手动版本管理的工作量
  2. 避免了版本不匹配的风险
  3. 使得 CAS 版本升级更加平滑——升级 CAS 版本时，所有相关依赖的版本会自动更新

3.4 依赖冲突的显著减少 ​

CAS 6.6 相比 CAS 5.3，依赖冲突的数量显著减少。这得益于以下几个因素：

第一，BOM 的完善。 CAS 6.6 的 BOM 相比 CAS 5.3 更加完善，覆盖了更多的第三方库版本。这意味着大部分版本冲突可以在 BOM 层面得到解决，而不需要手动干预。

第二，全局排除策略的扩展。 CAS 6.6 将大部分日志框架相关的排除提升到了全局级别，不再需要逐个模块处理。这大大减少了 exclude 声明的数量。

第三，Spring Boot 2.7.x 的成熟度。 Spring Boot 2.7.x 是一个长期支持（LTS）版本，其依赖管理已经非常成熟。CAS 6.6 基于 Spring Boot 2.7.x 构建，能够充分利用其成熟的依赖管理体系。

第四，Java 11 的模块化。 Java 9 引入了模块系统（JPMS），虽然 CAS 并没有完全采用模块化，但 Java 11 的类加载机制相比 Java 8 有所改进，某些在 Java 8 中可能出现的依赖冲突在 Java 11 中不再出现。

量化对比：

指标CAS 5.3CAS 6.6改善幅度
每个模块的平均 exclude 数量5-7 个0-1 个减少 85%+
需要显式锁定版本的依赖数量10+ 个2-3 个减少 70%+
全局 exclude 数量2 个8 个集中管理
dependencyManagement 中的版本声明15+ 个0 个完全消除
BOM 导入数量2 个2 个不变

3.5 CAS 6.6 完整配置示例（教学简化版） ​

以下是一个教学用途的简化版 CAS 6.6 Gradle 配置：

groovy
// ========================================
// CAS 6.6 Overlay - 教学简化版 build.gradle
// ========================================

buildscript {
    repositories {
        mavenLocal()
        mavenCentral()
        gradlePluginPortal()
        maven {
            url 'https://oss.sonatype.org/content/repositories/snapshots'
        }
        maven {
            url "https://repo.spring.io/milestone"
        }
    }
    dependencies {
        classpath "org.springframework.boot:spring-boot-gradle-plugin:${project.springBootVersion}"
        classpath "io.freefair.gradle:maven-plugin:${project.gradleFreeFairPluginVersion}"
        classpath "io.freefair.gradle:lombok-plugin:${project.gradleFreeFairPluginVersion}"
        classpath "io.spring.gradle:dependency-management-plugin:${project.gradleDependencyManagementPluginVersion}"
        classpath "de.undercouch:gradle-download-task:${project.gradleDownloadTaskVersion}"
        classpath "org.apereo.cas:cas-server-core-api-configuration-model:${project.'cas.version'}"
        classpath "org.apereo.cas:cas-server-core-configuration-metadata-repository:${project.'cas.version'}"
    }
}

repositories {
    mavenLocal()
    mavenCentral()
    maven { url 'https://oss.sonatype.org/content/repositories/releases' }
    maven { url 'https://oss.sonatype.org/content/repositories/snapshots' }
    maven { url "https://repository.apache.org/content/repositories/snapshots" }
    maven { url 'https://build.shibboleth.net/nexus/content/repositories/releases/' }
    maven { url "https://build.shibboleth.net/nexus/content/repositories/snapshots" }
    maven { url "https://repo.spring.io/milestone" }
}

apply plugin: 'eclipse'
apply plugin: "java"
apply plugin: "org.springframework.boot"
apply plugin: "io.freefair.lombok"

sourceSets {
    main {
        java { srcDirs = ['src/main/java'] }
        resources { srcDirs = ['src/main/resources'] }
    }
    test {
        java { srcDirs = ['src/test/java'] }
        resources { srcDirs = ['src/test/resources'] }
    }
}

apply from: rootProject.file("gradle/springboot.gradle")
apply from: rootProject.file("gradle/tasks.gradle")

// ========================================
// 全局排除策略（核心改进）
// ========================================
configurations {
    all {
        resolutionStrategy {
            cacheChangingModulesFor 0, "seconds"
            cacheDynamicVersionsFor 0, "seconds"
            preferProjectModules()

            // 可选：版本冲突严格模式
            def failIfConflict = project.hasProperty("failOnVersionConflict") &&
                Boolean.valueOf(project.getProperty("failOnVersionConflict"))
            if (failIfConflict) {
                failOnVersionConflict()
            }

            // 可选：Tomcat 版本覆盖
            if (project.hasProperty("tomcatVersion")) {
                eachDependency { DependencyResolveDetails dependency ->
                    def requested = dependency.requested
                    if (requested.group.startsWith("org.apache.tomcat") &&
                        requested.name != "jakartaee-migration") {
                        dependency.useVersion("${tomcatVersion}")
                    }
                }
            }
        }

        // 全局排除 - 日志框架冲突
        exclude(group: "cglib", module: "cglib")
        exclude(group: "cglib", module: "cglib-full")
        exclude(group: "org.slf4j", module: "slf4j-log4j12")
        exclude(group: "org.slf4j", module: "slf4j-simple")
        exclude(group: "org.slf4j", module: "jcl-over-slf4j")
        exclude(group: "org.apache.logging.log4j", module: "log4j-to-slf4j")
        exclude(group: "ch.qos.logback", module: "logback-core")
        exclude(group: "ch.qos.logback", module: "logback-classic")
    }
}

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(11)
    }
}

// ========================================
// 依赖声明（不再需要逐个 exclude）
// ========================================
dependencies {
    /**
     * BOM 导入 - 使用 platform() 替代 dependencyManagement
     * 注意：不要修改以下两行，否则可能破坏依赖管理
     **/
    implementation platform(org.springframework.boot.gradle.plugin.SpringBootPlugin.BOM_COORDINATES)
    implementation platform("org.apereo.cas:cas-server-support-bom:${project.'cas.version'}")

    /**
     * 必需的基础依赖
     **/
    implementation "org.apereo.cas:cas-server-core-api-configuration-model"
    implementation "org.apereo.cas:cas-server-webapp-init"

    /**
     * CAS 模块依赖 - 不需要指定版本号，由 BOM 管理
     * 注意：不再需要逐个 exclude！
     **/
    // OAuth2.0 支持
    implementation "org.apereo.cas:cas-server-support-oauth"
    implementation "org.apereo.cas:cas-server-support-oauth-core"
    implementation "org.apereo.cas:cas-server-support-oauth-webflow"
    implementation "org.apereo.cas:cas-server-support-oauth-services"
    implementation "org.apereo.cas:cas-server-support-oauth-api"
    implementation "org.apereo.cas:cas-server-support-oauth-core-api"

    // CAS 核心模块
    implementation "org.apereo.cas:cas-server-core"
    implementation "org.apereo.cas:cas-server-support-rest"
    implementation "org.apereo.cas:cas-server-support-rest-authentication"
    implementation "org.apereo.cas:cas-server-core-monitor"
    implementation "org.apereo.cas:cas-server-core-services-api"
    implementation "org.apereo.cas:cas-server-core-authentication"
    implementation "org.apereo.cas:cas-server-core-services"
    implementation "org.apereo.cas:cas-server-core-logout"
    implementation "org.apereo.cas:cas-server-core-audit"
    implementation "org.apereo.cas:cas-server-core-logging"
    implementation "org.apereo.cas:cas-server-core-tickets"
    implementation "org.apereo.cas:cas-server-core-web"
    implementation "org.apereo.cas:cas-server-core-validation"
    implementation "org.apereo.cas:cas-server-core-util"
    implementation "org.apereo.cas:cas-server-core-events"
    implementation "org.apereo.cas:cas-server-core-events-configuration"
    implementation "org.apereo.cas:cas-server-core-configuration"
    implementation "org.apereo.cas:cas-server-core-configuration-metadata-repository"
    implementation "org.apereo.cas:cas-server-support-throttle"
    implementation "org.apereo.cas:cas-server-support-person-directory"
    implementation "org.apereo.cas:cas-server-support-geolocation"
    implementation "org.apereo.cas:cas-server-support-actions"
    implementation "org.apereo.cas:cas-server-core-cookie"
    implementation "org.apereo.cas:cas-server-support-themes"
    implementation "org.apereo.cas:cas-server-support-ldap"
    implementation "org.apereo.cas:cas-server-support-pm-webflow"
    implementation "org.apereo.cas:cas-server-core-webflow"
    implementation "org.apereo.cas:cas-server-core-authentication-api"
    implementation "org.apereo.cas:cas-server-core-webflow-api"
    implementation "org.apereo.cas:cas-server-core-web-api"
    implementation "org.apereo.cas:cas-server-core-cookie-api"
    implementation "org.apereo.cas:cas-server-support-thymeleaf"
    implementation "org.apereo.cas:cas-server-core-authentication-attributes"
    implementation "org.apereo.cas:cas-server-core-services-registry"
    implementation "org.apereo.cas:cas-server-support-json-service-registry"
    implementation "org.apereo.cas:cas-server-webapp-config"
    implementation "org.apereo.cas:cas-server-webapp-resources"
    implementation "org.apereo.cas:cas-server-webapp-init-tomcat"

    // Redis 票务注册表
    implementation "org.apereo.cas:cas-server-support-redis-ticket-registry"

    // Spring Boot Starters
    implementation("org.springframework.boot:spring-boot-starter-web") {
        exclude group: "org.springframework.boot", module: "spring-boot-starter-logging"
    }
    implementation "org.springframework.boot:spring-boot-starter-tomcat"
    implementation("org.springframework.boot:spring-boot-starter-thymeleaf") {
        exclude group: "org.springframework.boot", module: "spring-boot-starter-logging"
    }
    implementation "org.springframework.boot:spring-boot-starter-jdbc"
    implementation "org.springframework.boot:spring-boot-starter-mail"
    implementation "org.springframework.boot:spring-boot-starter-log4j2"

    // 数据库相关
    implementation "org.mybatis:mybatis:3.5.6"
    implementation "org.mybatis:mybatis-spring:1.3.1"
    implementation "mysql:mysql-connector-java:8.0.33"
    implementation "commons-dbcp:commons-dbcp:1.4"

    // 其他依赖
    implementation "org.pac4j:pac4j-core"
    implementation "org.pac4j:pac4j-http"
    implementation "org.pac4j:pac4j-cas"
    implementation "org.pac4j:pac4j-javaee"
    implementation "xalan:xalan:2.7.3"
    implementation "xalan:serializer:2.7.2"
    implementation "com.fasterxml:classmate"
    implementation "org.projectlombok:lombok"
    implementation "javax.mail:mail:1.4.7"
    implementation "com.nimbusds:lang-tag:1.6"
    implementation "javax.xml.bind:jaxb-api"
    implementation "org.dom4j:dom4j"
    implementation "org.bouncycastle:bcprov-jdk15on"

    // WebJars
    implementation "org.webjars:font-awesome"
    implementation "org.webjars:jquery"
    implementation "org.webjars:bootstrap"

    // 测试依赖
    testImplementation "org.springframework.boot:spring-boot-starter-test"
    testImplementation "junit:junit"
}

springBoot {
    mainClass = "com.example.cas.CasWebApplication"
}

配置要点总结：

  1. BOM 导入： 使用 platform() 替代 dependencyManagement 插件
  2. 全局排除： 8 个全局 exclude 替代了数百个逐个 exclude
  3. 版本管理： CAS 模块不需要指定版本号，由 BOM 统一管理
  4. 日志框架： 全局排除 Logback，使用 spring-boot-starter-log4j2
  5. 简化程度： 相比 CAS 5.3，配置代码量减少约 60%

3.6 CAS 6.6 Maven 版本的依赖管理对比 ​

CAS 6.6 的 Maven 版本在依赖管理方面相比 CAS 5.3 也有显著改进，但由于 Maven 本身的限制，改进幅度不如 Gradle 版本大。

CAS 6.6 Maven 的关键改进：

  1. BOM 导入更加完善： CAS 6.6 的 BOM 覆盖了更多的第三方库版本
  2. 减少了需要显式排除的依赖： 大部分日志框架冲突通过 BOM 的版本管理得到解决
  3. CAS 模块不需要显式排除： 大部分 CAS 模块可以直接引入，不需要 <exclusions>
xml
<!-- CAS 6.6 Maven - CAS 模块不再需要大量排除 -->
<dependency>
    <groupId>org.apereo.cas</groupId>
    <artifactId>cas-server-core</artifactId>
    <!-- 不再需要 <exclusions>！ -->
</dependency>

<!-- Spring Boot Starter 仍然需要排除默认日志 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <exclusions>
        <exclusion>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-logging</artifactId>
        </exclusion>
        <exclusion>
            <groupId>cglib</groupId>
            <artifactId>cglib</artifactId>
        </exclusion>
        <exclusion>
            <groupId>cglib</groupId>
            <artifactId>cglib-full</artifactId>
        </exclusion>
        <!-- 更多排除... -->
    </exclusions>
</dependency>

Maven 中实现全局排除的替代方案：

由于 Maven 原生不支持全局排除，CAS 6.6 的 Maven 版本通常使用以下替代方案：

  1. Maven Enforcer 插件： 通过 banDuplicateClasses 规则禁止重复的类
  2. 父 POM 集中管理排除： 将常用的排除声明放在父 POM 的 <dependencyManagement> 中
  3. 自定义 Maven 插件： 编写自定义插件来自动处理排除逻辑

3.7 CAS 6.6 中 resolutionStrategy 的高级用法 ​

CAS 6.6 的 configurations.all 块中包含了一些高级的 resolutionStrategy 配置，这些配置在日常开发中很少使用，但在特定场景下非常有用。

缓存策略配置：

groovy
resolutionStrategy {
    cacheChangingModulesFor 0, "seconds"
    cacheDynamicVersionsFor 0, "seconds"
}

这两行配置的作用是禁用 Gradle 的依赖缓存。在正常情况下，Gradle 会缓存动态版本（如 1.0.+）和变化中的模块（如 SNAPSHOT 版本），以提高构建速度。但在 CAS 项目中，由于依赖版本由 BOM 严格管理，禁用缓存可以确保每次构建都使用最新的依赖版本，避免因缓存导致的版本不一致。

Tomcat 版本覆盖：

groovy
if (project.hasProperty("tomcatVersion")) {
    eachDependency { DependencyResolveDetails dependency ->
        def requested = dependency.requested
        if (requested.group.startsWith("org.apache.tomcat") &&
            requested.name != "jakartaee-migration") {
            dependency.useVersion("${tomcatVersion}")
        }
    }
}

这个配置允许通过命令行参数覆盖 Tomcat 的版本。这在以下场景中非常有用：

  1. 安全补丁： 当 Tomcat 发现安全漏洞时，可以临时覆盖版本而不修改构建脚本
  2. 兼容性测试： 在不同的 Tomcat 版本上测试 CAS 的兼容性
  3. 生产环境定制： 某些生产环境可能要求使用特定版本的 Tomcat

使用方式：

bash
./gradlew build -PtomcatVersion=9.0.90

注意 requested.name != "jakartaee-migration" 这个条件——jakartaee-migration 是 Tomcat 提供的一个工具，用于将 javax 命名空间迁移到 jakarta。这个工具的版本应该独立于 Tomcat 的版本，因此不应该被覆盖。

preferProjectModules() 配置：

groovy
resolutionStrategy {
    preferProjectModules()
}

这个配置告诉 Gradle 在解析依赖时，优先使用项目模块（即多项目构建中的子项目）而非外部依赖。在 CAS Overlay 的单项目构建中，这个配置通常没有实际效果。但在某些复杂的多项目构建场景中，它可以确保项目内部的模块依赖优先于外部仓库中的同名依赖。

第四章 CAS 7.3 的依赖管理范式 ​

4.1 enforcedPlatform() 强制版本一致性 ​

CAS 7.3.x 是 CAS 项目的最新主要版本系列。它基于 Spring Boot 3.x 构建，要求 Java 21 运行环境，代表了 CAS 依赖管理的最新范式。CAS 7.3 最核心的依赖管理变化就是引入了 enforcedPlatform() 替代 platform()。

groovy
// CAS 7.3 的 BOM 导入方式
dependencies {
    // enforcedPlatform() - 强制版本一致性
    implementation enforcedPlatform("org.apereo.cas:cas-server-support-bom:${project.'cas.version'}")
    // platform() - 普通版本建议
    implementation platform(org.springframework.boot.gradle.plugin.SpringBootPlugin.BOM_COORDINATES)
}

注意这里的关键区别：CAS BOM 使用 enforcedPlatform()，而 Spring Boot BOM 使用 platform()。这个顺序和选择是有深意的——CAS BOM 的版本优先级必须高于 Spring Boot BOM，以确保 CAS 内部组件的版本一致性。

4.2 platform() 与 enforcedPlatform() 的本质区别 ​

要理解 CAS 7.3 的依赖管理策略，必须深入理解 platform() 和 enforcedPlatform() 的本质区别。

platform()（普通平台依赖）：

platform() 的行为类似于 Maven 的 <dependencyManagement> 中的 BOM 导入。它为依赖声明提供版本建议，但不会强制使用。如果项目中显式声明了某个依赖的版本，那么显式声明的版本会优先于 platform() 中的版本。

groovy
dependencies {
    // platform() 提供版本建议
    implementation platform("org.apereo.cas:cas-server-support-bom:7.3.4")

    // 显式声明的版本会覆盖 platform() 中的版本
    implementation "org.dom4j:dom4j:2.1.4"  // 使用 2.1.4，而非 BOM 中的版本
}

enforcedPlatform()（强制平台依赖）：

enforcedPlatform() 的行为更加严格。它不仅提供版本建议，还会强制要求所有依赖使用 BOM 中指定的版本。即使项目中显式声明了某个依赖的版本，enforcedPlatform() 中的版本也会覆盖显式声明的版本。

groovy
dependencies {
    // enforcedPlatform() 强制版本一致性
    implementation enforcedPlatform("org.apereo.cas:cas-server-support-bom:7.3.4")

    // 即使显式声明了版本，也会被 enforcedPlatform() 覆盖
    implementation "org.dom4j:dom4j:2.1.4"  // 实际使用 BOM 中的版本，而非 2.1.4
}

两者的核心区别总结：

特性platform()enforcedPlatform()
版本建议是是
版本强制否是
显式版本优先是（显式版本胜出）否（BOM 版本胜出）
版本冲突处理选择最高版本强制使用 BOM 版本
适用场景辅助版本管理严格的版本一致性要求

为什么 CAS 7.3 选择 enforcedPlatform()？

CAS 作为一个超大型单体项目，其内部组件之间的版本兼容性至关重要。使用 enforcedPlatform() 可以确保所有 CAS 子模块使用完全一致的依赖版本，消除因版本不一致导致的运行时错误。

考虑以下场景：假设 cas-server-core 依赖 jackson-databind:2.15.0，而 cas-server-support-oauth 依赖 jackson-databind:2.16.0。如果使用 platform()，Gradle 可能会选择 2.16.0（最高版本），但 cas-server-core 可能不兼容 2.16.0。而使用 enforcedPlatform()，CAS BOM 中指定的版本（假设是 2.15.0）会强制应用于所有模块，确保版本一致性。

注意事项：

使用 enforcedPlatform() 时需要特别注意：如果确实需要使用与 BOM 不同的版本（例如安全补丁），需要使用 resolutionStrategy.eachDependency 来强制覆盖：

groovy
configurations.all {
    resolutionStrategy {
        eachDependency { DependencyResolveDetails details ->
            if (details.requested.group == 'org.dom4j' &&
                details.requested.name == 'dom4j') {
                details.useVersion '2.1.4'  // 强制覆盖 BOM 版本
            }
        }
    }
}

4.3 几乎零手动排除 ​

CAS 7.3 最令人印象深刻的改进就是几乎不再需要手动排除依赖。在 CAS 5.3 中，每个模块需要 5-7 个 exclude；在 CAS 6.6 中，通过全局排除将 exclude 数量减少到了 8 个；而在 CAS 7.3 中，虽然仍然保留了全局排除（主要是日志框架相关的），但 CAS 模块本身不再需要任何 exclude。

groovy
// CAS 7.3 的全局排除策略（与 CAS 6.6 基本相同）
configurations {
    all {
        resolutionStrategy {
            cacheChangingModulesFor 0, "seconds"
            cacheDynamicVersionsFor 0, "seconds"
            preferProjectModules()
        }

        // 全局排除 - 日志框架冲突
        exclude(group: "cglib", module: "cglib")
        exclude(group: "cglib", module: "cglib-full")
        exclude(group: "org.slf4j", module: "slf4j-log4j12")
        exclude(group: "org.slf4j", module: "slf4j-simple")
        exclude(group: "org.slf4j", module: "jcl-over-slf4j")
        exclude(group: "org.apache.logging.log4j", module: "log4j-to-slf4j")
        exclude(group: "ch.qos.logback", module: "logback-core")
        exclude(group: "ch.qos.logback", module: "logback-classic")
    }
}

为什么 CAS 7.3 能够实现几乎零手动排除？

这得益于以下几个因素：

  1. CAS BOM 的完善： CAS 7.3 的 BOM 经过多年的迭代，已经非常完善，覆盖了几乎所有第三方库的版本管理
  2. Spring Boot 3.x 的改进： Spring Boot 3.x 的依赖管理更加成熟，与 CAS 的集成更加紧密
  3. Java 21 的模块化： Java 21 的模块系统（虽然 CAS 没有完全采用）提供了更好的类隔离机制
  4. javax 到 jakarta 的迁移： Spring Boot 3.x 完成了从 javax 到 jakarta 的迁移，消除了大量命名空间冲突
  5. CAS 内部的依赖管理改进： CAS 7.3 的构建脚本自身已经处理了大部分依赖冲突，不再传递给 Overlay 项目

4.4 依赖声明极简化 ​

CAS 7.3 的依赖声明达到了前所未有的简洁程度。每个 CAS 模块的声明只需要一行代码，不需要任何 exclude 或版本号：

groovy
// CAS 7.3 的依赖声明 - 极致简化
dependencies {
    // BOM 导入
    implementation enforcedPlatform("org.apereo.cas:cas-server-support-bom:${project.'cas.version'}")
    implementation platform(org.springframework.boot.gradle.plugin.SpringBootPlugin.BOM_COORDINATES)

    // CAS 模块 - 只需要声明名称，不需要版本号和 exclude
    implementation "org.apereo.cas:cas-server-core"
    implementation "org.apereo.cas:cas-server-support-oauth"
    implementation "org.apereo.cas:cas-server-support-redis-ticket-registry"
    implementation "org.apereo.cas:cas-server-support-redis-core"
    // ... 更多模块
}

对比三个版本的依赖声明方式：

CAS 5.3（每个模块 5-7 行）：

groovy
implementation('org.apereo.cas:cas-server-core') {
    exclude group: 'org.springframework.boot', module: 'spring-boot-devtools'
    exclude group: 'org.apache.logging.log4j', module: 'log4j-slf4j-impl'
    exclude group: 'dom4j', module: 'dom4j'
}

CAS 6.6（每个模块 1 行，全局排除 8 个）：

groovy
// 全局排除在 configurations.all 中声明
implementation "org.apereo.cas:cas-server-core"

CAS 7.3（每个模块 1 行，全局排除 8 个，enforcedPlatform）：

groovy
// enforcedPlatform 确保版本一致性
implementation "org.apereo.cas:cas-server-core"

虽然 CAS 6.6 和 CAS 7.3 的依赖声明看起来相同，但 CAS 7.3 的 enforcedPlatform() 提供了更强的版本一致性保证。

4.5 版本冲突由 Gradle 自动解决 ​

在 CAS 7.3 中，版本冲突的解决几乎完全由 Gradle 自动完成。enforcedPlatform() 确保了 BOM 中声明的版本优先级最高，而 Gradle 的依赖解析引擎会自动处理剩余的版本冲突。

当确实出现版本冲突时（例如第三方库引入了与 BOM 不兼容的版本），Gradle 会根据以下规则解决：

  1. enforcedPlatform() 的版本优先级最高
  2. 显式声明的版本优先于传递依赖的版本
  3. 最高版本优先（当没有 enforcedPlatform() 约束时）

如果需要调试版本冲突，可以使用以下 Gradle 命令：

bash
# 查看完整的依赖树
./gradlew dependencies --configuration compileClasspath

# 查看特定依赖的版本解析过程
./gradlew dependencyInsight --dependency jackson-databind --configuration compileClasspath

# 开启版本冲突严格模式
./gradlew build -PfailOnVersionConflict=true

4.6 CAS 7.3 完整配置示例（教学简化版） ​

以下是一个教学用途的简化版 CAS 7.3 Gradle 配置：

groovy
// ========================================
// CAS 7.3 Overlay - 教学简化版 build.gradle
// ========================================

buildscript {
    repositories {
        mavenLocal()
        mavenCentral()
        gradlePluginPortal()
        maven {
            url = 'https://central.sonatype.com/repository/maven-snapshots/'
            mavenContent { snapshotsOnly() }
        }
        maven {
            url = "https://repo.spring.io/milestone"
            mavenContent { releasesOnly() }
        }
    }
    dependencies {
        classpath "org.springframework.boot:spring-boot-gradle-plugin:${project.springBootVersion}"
        classpath "io.freefair.gradle:maven-plugin:${project.gradleFreeFairPluginVersion}"
        classpath "io.freefair.gradle:lombok-plugin:${project.gradleFreeFairPluginVersion}"
        classpath "com.google.cloud.tools:jib-gradle-plugin:${project.jibVersion}"
        classpath "de.undercouch:gradle-download-task:${project.gradleDownloadTaskVersion}"
        classpath "org.apereo.cas:cas-server-core-api-configuration-model:${project.'cas.version'}"
        classpath "org.apereo.cas:cas-server-support-configuration-metadata-repository:${project.'cas.version'}"
    }
}

repositories {
    mavenLocal()
    mavenCentral()
    maven { url = 'https://oss.sonatype.org/content/repositories/releases' }
    maven { url = 'https://build.shibboleth.net/nexus/content/repositories/releases/' }
    maven { url = "https://repo.spring.io/milestone" }
}

apply plugin: 'eclipse'
apply plugin: "java"
apply plugin: "org.springframework.boot"
apply plugin: "io.freefair.lombok"

lombok {
    version = "${project.lombokVersion}"
}

sourceSets {
    main {
        java { srcDirs = ['src/main/java'] }
        resources { srcDirs = ['src/main/resources'] }
    }
    test {
        java { srcDirs = ['src/test/java'] }
        resources { srcDirs = ['src/test/resources'] }
    }
}

apply from: rootProject.file("gradle/springboot.gradle")
apply from: rootProject.file("gradle/tasks.gradle")

// ========================================
// 全局排除策略（保留日志框架排除）
// ========================================
configurations {
    all {
        resolutionStrategy {
            cacheChangingModulesFor 0, "seconds"
            cacheDynamicVersionsFor 0, "seconds"
            preferProjectModules()
        }

        // 全局排除 - 日志框架冲突
        exclude(group: "cglib", module: "cglib")
        exclude(group: "cglib", module: "cglib-full")
        exclude(group: "org.slf4j", module: "slf4j-log4j12")
        exclude(group: "org.slf4j", module: "slf4j-simple")
        exclude(group: "org.slf4j", module: "jcl-over-slf4j")
        exclude(group: "org.apache.logging.log4j", module: "log4j-to-slf4j")
        exclude(group: "ch.qos.logback", module: "logback-core")
        exclude(group: "ch.qos.logback", module: "logback-classic")
    }
}

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(project.targetCompatibility)
    }
}

// ========================================
// 依赖声明（极致简化）
// ========================================
dependencies {
    /**
     * BOM 导入 - enforcedPlatform() 确保版本一致性
     * 注意：不要修改以下两行！
     **/
    implementation enforcedPlatform("org.apereo.cas:cas-server-support-bom:${project.'cas.version'}")
    implementation platform(org.springframework.boot.gradle.plugin.SpringBootPlugin.BOM_COORDINATES)

    /**
     * 必需的基础依赖
     **/
    implementation "org.apereo.cas:cas-server-core-api-configuration-model"
    implementation "org.apereo.cas:cas-server-webapp-init"
    implementation "org.apereo.cas:cas-server-webapp-init-tomcat"

    /**
     * CAS 模块依赖 - 只需声明名称，版本由 enforcedPlatform 管理
     * 不需要任何 exclude！
     **/
    // OAuth2.0 支持
    implementation "org.apereo.cas:cas-server-support-oauth"
    implementation "org.apereo.cas:cas-server-support-oauth-api"
    implementation "org.apereo.cas:cas-server-support-oauth-core-api"
    implementation "org.apereo.cas:cas-server-support-oauth-uma"
    implementation "org.apereo.cas:cas-server-support-oauth-webflow"

    // CAS 核心模块
    implementation "org.apereo.cas:cas-server-core"
    implementation "org.apereo.cas:cas-server-support-rest"
    implementation "org.apereo.cas:cas-server-support-rest-authentication"
    implementation "org.apereo.cas:cas-server-core-monitor"
    implementation "org.apereo.cas:cas-server-core-services-api"
    implementation "org.apereo.cas:cas-server-core-authentication"
    implementation "org.apereo.cas:cas-server-core-services"
    implementation "org.apereo.cas:cas-server-core-logout"
    implementation "org.apereo.cas:cas-server-core-audit"
    implementation "org.apereo.cas:cas-server-core-logging"
    implementation "org.apereo.cas:cas-server-core-tickets"
    implementation "org.apereo.cas:cas-server-core-web"
    implementation "org.apereo.cas:cas-server-core-validation"
    implementation "org.apereo.cas:cas-server-core-util"
    implementation "org.apereo.cas:cas-server-core-events"
    implementation "org.apereo.cas:cas-server-core-events-configuration"
    implementation "org.apereo.cas:cas-server-core-configuration"
    implementation "org.apereo.cas:cas-server-support-throttle"
    implementation "org.apereo.cas:cas-server-support-person-directory"
    implementation "org.apereo.cas:cas-server-support-geolocation"
    implementation "org.apereo.cas:cas-server-support-actions"
    implementation "org.apereo.cas:cas-server-core-cookie"
    implementation "org.apereo.cas:cas-server-support-themes"
    implementation "org.apereo.cas:cas-server-support-ldap"
    implementation "org.apereo.cas:cas-server-support-pm-webflow"
    implementation "org.apereo.cas:cas-server-core-webflow"
    implementation "org.apereo.cas:cas-server-core-authentication-api"
    implementation "org.apereo.cas:cas-server-core-webflow-api"
    implementation "org.apereo.cas:cas-server-core-web-api"
    implementation "org.apereo.cas:cas-server-core-cookie-api"
    implementation "org.apereo.cas:cas-server-support-thymeleaf"
    implementation "org.apereo.cas:cas-server-core-authentication-attributes"
    implementation "org.apereo.cas:cas-server-core-services-registry"
    implementation "org.apereo.cas:cas-server-support-json-service-registry"
    implementation "org.apereo.cas:cas-server-support-webconfig"
    implementation "org.apereo.cas:cas-server-webapp-resources"

    // Redis 票务注册表
    implementation "org.apereo.cas:cas-server-support-redis-ticket-registry"
    implementation "org.apereo.cas:cas-server-support-redis-core"

    // Spring Boot Starters
    implementation("org.springframework.boot:spring-boot-starter-web") {
        exclude group: "org.springframework.boot", module: "spring-boot-starter-logging"
    }
    implementation "org.springframework.boot:spring-boot-starter-tomcat"
    implementation("org.springframework.boot:spring-boot-starter-thymeleaf") {
        exclude group: "org.springframework.boot", module: "spring-boot-starter-logging"
    }
    implementation "org.springframework.boot:spring-boot-starter-jdbc"
    implementation "org.springframework.boot:spring-boot-starter-mail"
    implementation "org.springframework.boot:spring-boot-starter-log4j2"

    // 数据库相关
    implementation "org.mybatis:mybatis:3.5.16"
    implementation "org.mybatis:mybatis-spring:3.0.3"
    implementation "mysql:mysql-connector-java:8.0.33"
    implementation "org.apache.commons:commons-dbcp2:2.10.0"

    // 其他依赖
    implementation "org.pac4j:pac4j-core"
    implementation "org.pac4j:pac4j-http"
    implementation "org.pac4j:pac4j-cas"
    implementation "xalan:xalan:2.7.3"
    implementation "xalan:serializer:2.7.2"
    implementation "com.fasterxml:classmate:1.3.4"
    implementation "org.projectlombok:lombok:1.18.24"
    implementation "javax.mail:mail:1.4.7"
    implementation "com.nimbusds:lang-tag:1.6"
    implementation "javax.xml.bind:jaxb-api:2.3.1"
    implementation "org.dom4j:dom4j"
    implementation "org.bouncycastle:bcprov-jdk15on"

    // WebJars
    implementation 'org.webjars:font-awesome:4.7.0'
    implementation 'org.webjars:jquery:3.7.1'
    implementation 'org.webjars:bootstrap:5.3.3'

    // 测试依赖
    testImplementation "org.springframework.boot:spring-boot-starter-test"
}

springBoot {
    mainClass = "com.example.cas.CasWebApplication"
}

4.7 CAS 7.3 Maven 版本的依赖管理对比 ​

CAS 7.3 的 Maven 版本展示了与 Gradle 版本相似的依赖管理简化效果。由于 enforcedPlatform() 是 Gradle 特有的概念，Maven 通过 BOM 的导入顺序和 dependencyManagement 的优先级机制来实现类似的效果。

xml
<!-- CAS 7.3 Maven 的 dependencyManagement -->
<dependencyManagement>
    <dependencies>
        <!-- CAS BOM - 放在前面，确保优先级 -->
        <dependency>
            <groupId>org.apereo.cas</groupId>
            <artifactId>cas-server-support-bom</artifactId>
            <version>${cas.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
        <!-- Spring Boot BOM -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-dependencies</artifactId>
            <version>${spring.boot.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Maven 中 CAS 7.3 的依赖声明极简化：

xml
<!-- CAS 模块 - 不需要版本号，不需要排除 -->
<dependency>
    <groupId>org.apereo.cas</groupId>
    <artifactId>cas-server-core</artifactId>
</dependency>
<dependency>
    <groupId>org.apereo.cas</groupId>
    <artifactId>cas-server-support-oauth</artifactId>
</dependency>

<!-- Spring Boot Starters - 仅需排除默认日志 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <exclusions>
        <exclusion>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-logging</artifactId>
        </exclusion>
    </exclusions>
</dependency>

对比 CAS 5.3 的 Maven 版本，CAS 7.3 的每个 CAS 模块从 6 行（1 行依赖 + 5 行排除）减少到 3 行（1 行依赖，无排除），代码量减少了 50%。

4.8 CAS 7.3 中的 Docker 与容器化依赖管理 ​

CAS 7.3 在容器化支持方面做了大量改进，这些改进也影响了依赖管理策略。

Jib 插件集成：

CAS 7.3 内置了 Google Jib 插件，可以直接从 Gradle 构建生成 Docker 镜像，无需 Dockerfile：

groovy
jib {
    from {
        image = project.baseDockerImage  // 例如：azul/zulu-openjdk:21
        platforms {
            imagePlatforms.each {
                def given = it.split(":")
                platform {
                    architecture = given[0]
                    os = given[1]
                }
            }
        }
    }
    to {
        image = "${project.'containerImageOrg'}/${project.'containerImageName'}:${project.version}"
    }
    container {
        creationTime = "USE_CURRENT_TIMESTAMP"
        entrypoint = ['/docker/entrypoint.sh']
        ports = ['80', '443', '8080', '8443', '8761']
        workingDirectory = '/docker/cas/war'
    }
}

容器化环境中的依赖管理注意事项：

  1. 基础镜像的 JDK 版本必须与 targetCompatibility 一致： CAS 7.3 要求 Java 21，基础镜像也必须使用 JDK 21
  2. Docker 镜像的层缓存： 合理安排依赖的声明顺序，将不常变化的依赖放在前面，利用 Docker 的层缓存机制加速构建
  3. 多架构支持： CAS 7.3 的 Jib 配置支持多架构构建（如 amd64:linux 和 arm64:linux），但需要注意不同架构的 JDK 可能存在细微的依赖行为差异
  4. CycloneDX SBOM 生成： CAS 7.3 集成了 CycloneDX 插件，可以在构建 Docker 镜像的同时生成 SBOM，用于容器镜像的安全扫描

第五章 日志框架冲突深度解析 ​

5.1 SLF4J 门面模式原理 ​

SLF4J（Simple Logging Facade for Java）是 Java 生态中最广泛使用的日志门面。它的核心设计模式是门面模式（Facade Pattern），通过提供一个统一的日志 API，将应用程序代码与具体的日志实现解耦。

+------------------+
|   应用程序代码    |
|  logger.info()   |
+--------+---------+
         |
         v
+------------------+
|    SLF4J API     |  <-- 门面（Facade）
|  (slf4j-api.jar) |
+--------+---------+
         |
    +----+----+
    |         |
    v         v
+-------+ +--------+
|Log4j2 | |Logback |  <-- 实现（Implementation）
+-------+ +--------+

SLF4J 的工作原理可以概括为：

  1. 编译期绑定： 应用程序代码只依赖 slf4j-api.jar，不直接依赖任何日志实现
  2. 运行时发现： SLF4J 在运行时通过 StaticLoggerBinder 或 ServiceLoader 机制发现类路径上的日志实现
  3. 自动路由： SLF4J 将日志调用路由到发现的日志实现

SLF4J 的绑定规则：

  • 类路径上只能有一个 SLF4J 绑定实现
  • 如果存在多个绑定实现，SLF4J 会发出警告，并选择其中一个（选择结果不确定）
  • 如果没有任何绑定实现，SLF4J 会使用 NOPLogger（不输出任何日志）

SLF4J 的桥接器（Bridge）：

SLF4J 提供了多种桥接器，用于将其他日志框架的调用重定向到 SLF4J：

桥接器作用
jcl-over-slf4j将 Commons Logging (JCL) 的调用重定向到 SLF4J
jul-to-slf4j将 java.util.logging (JUL) 的调用重定向到 SLF4J
log4j-over-slf4j将 Log4j 1.x 的调用重定向到 SLF4J

这些桥接器本质上是对原有日志框架 API 的"伪装"实现。例如，jcl-over-slf4j 提供了与 Commons Logging 相同的类名和包名，但其内部实现是将日志调用转发给 SLF4J。

5.2 Log4j2 vs Logback 的桥接器选择 ​

在 CAS 项目中，选择 Log4j2 还是 Logback 作为日志实现，是一个关键的架构决策。CAS 官方选择 Log4j2，而 Spring Boot 默认使用 Logback。这个选择带来了桥接器配置的复杂性。

CAS 选择 Log4j2 的原因：

  1. 性能优势： Log4j2 的异步日志（AsyncLogger）基于 LMAX Disruptor 库实现，在多线程环境下的吞吐量远超 Logback
  2. 配置灵活性： Log4j2 支持 JSON、YAML、XML 等多种配置格式，且支持配置热重载
  3. 插件生态： Log4j2 的插件架构更加灵活，支持自定义 Appender、Filter、Layout 等
  4. 低延迟： Log4j2 的 LogEvent 对象设计减少了 GC 压力，适合高并发场景

Log4j2 的 SLF4J 绑定：

当选择 Log4j2 作为日志实现时，需要使用 log4j-slf4j-impl 作为 SLF4J 的绑定：

应用程序代码
    |
    v
SLF4J API (slf4j-api)
    |
    v  (log4j-slf4j-impl)
Log4j2 (log4j-core)

Logback 的 SLF4J 绑定：

当选择 Logback 作为日志实现时，需要使用 logback-classic 作为 SLF4J 的绑定（logback-classic 原生实现了 SLF4J 的接口）：

应用程序代码
    |
    v
SLF4J API (slf4j-api)
    |
    v  (logback-classic，原生实现 SLF4J)
Logback (logback-core)

冲突场景：

如果 log4j-slf4j-impl 和 logback-classic 同时出现在类路径上，SLF4J 会发出警告：

SLF4J: Class path contains multiple SLF4J bindings.
SLF4J: Found binding in [jar:.../log4j-slf4j-impl-2.12.4.jar!/org/slf4j/impl/StaticLoggerBinder.class]
SLF4J: Found binding in [jar:.../logback-classic-1.2.11.jar!/org/slf4j/impl/StaticLoggerBinder.class]
SLF4J: See http://www.slf4j.org/codes.html#multiple_bindings for an explanation.
SLF4J: Actual binding is of type [org.apache.logging.slf4j.Log4jLoggerFactory]

虽然 SLF4J 会选择其中一个绑定，但选择结果不确定，可能导致日志输出行为不可预期。

5.3 log4j-slf4j-impl vs log4j-to-slf4j 的区别 ​

这是日志框架冲突中最容易混淆的一对库。它们的名字非常相似，但功能完全相反。

log4j-slf4j-impl（SLF4J -> Log4j2）：

  • 方向： SLF4J 到 Log4j2
  • 作用： 作为 SLF4J 的绑定实现，将 SLF4J 的日志调用路由到 Log4j2
  • 场景： 当你选择 Log4j2 作为日志实现时使用
  • 坐标： org.apache.logging.log4j:log4j-slf4j-impl
SLF4J API --[log4j-slf4j-impl]--> Log4j2 Core

log4j-to-slf4j（Log4j2 -> SLF4J）：

  • 方向： Log4j2 到 SLF4J
  • 作用： 作为 Log4j2 API 的路由层，将 Log4j2 API 的日志调用路由到 SLF4J
  • 场景： 当你选择 Logback（或其他 SLF4J 实现）作为日志实现，但某些库直接使用 Log4j2 API 时使用
  • 坐标： org.apache.logging.log4j:log4j-to-slf4j
Log4j2 API --[log4j-to-slf4j]--> SLF4J API --> Logback

冲突场景：

如果 log4j-slf4j-impl 和 log4j-to-slf4j 同时存在，会形成无限递归：

SLF4J API --> Log4j2 (via log4j-slf4j-impl)
    |
    v
Log4j2 --> SLF4J (via log4j-to-slf4j)
    |
    v
SLF4J --> Log4j2 (via log4j-slf4j-impl)
    |
    v
... 无限递归 ...

这会导致 StackOverflowError，应用程序无法启动。

在 CAS 项目中的正确配置：

CAS 使用 Log4j2 作为日志实现，因此应该：

  • 保留 log4j-slf4j-impl（SLF4J -> Log4j2）
  • 排除 log4j-to-slf4j（Log4j2 -> SLF4J）

这也是为什么在 CAS 6.6 和 7.3 的全局排除中包含了：

groovy
exclude(group: "org.apache.logging.log4j", module: "log4j-to-slf4j")

5.4 spring-boot-starter-logging 的排除策略 ​

spring-boot-starter-logging 是 Spring Boot 的默认日志 Starter，它引入了以下依赖：

spring-boot-starter-logging
    +-- logback-classic
    |   +-- logback-core
    |   +-- slf4j-api
    +-- log4j-to-slf4j
    +-- jul-to-slf4j

注意：spring-boot-starter-logging 引入了 logback-classic 和 log4j-to-slf4j，这两者都与 CAS 的 Log4j2 日志策略冲突。

解决方案：排除 spring-boot-starter-logging，使用 spring-boot-starter-log4j2。

在 Gradle 中：

groovy
// 排除默认的 logging starter
implementation("org.springframework.boot:spring-boot-starter-web") {
    exclude group: "org.springframework.boot", module: "spring-boot-starter-logging"
}

// 使用 Log4j2 starter
implementation "org.springframework.boot:spring-boot-starter-log4j2"

spring-boot-starter-log4j2 引入了以下依赖：

spring-boot-starter-log4j2
    +-- log4j-core
    +-- log4j-to-slf4j  <-- 注意：这个也需要排除！
    +-- slf4j-api
    +-- jul-to-slf4j

有趣的是，spring-boot-starter-log4j2 也引入了 log4j-to-slf4j。这是因为 Spring Boot 的设计假设你可能想要将 Log4j2 的日志路由到 SLF4J（进而使用 Logback）。但在 CAS 的场景中，我们想要 Log4j2 作为最终实现，因此也需要排除 log4j-to-slf4j。

在 CAS 5.3 中，这个排除是显式的：

groovy
// CAS 5.3 中显式排除
implementation('org.springframework.boot:spring-boot-starter-log4j2') {
    exclude group: 'org.apache.logging.log4j', module: 'log4j-slf4j-impl'
    exclude group: 'org.apache.logging.log4j', module: 'log4j-jul'
}

在 CAS 6.6 和 7.3 中，由于全局排除已经覆盖了 log4j-to-slf4j，不需要再显式排除。

Maven 中的排除方式：

xml
<!-- Maven 中排除 spring-boot-starter-logging -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <exclusions>
        <exclusion>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-logging</artifactId>
        </exclusion>
    </exclusions>
</dependency>

<!-- 使用 Log4j2 starter -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-log4j2</artifactId>
</dependency>

5.5 CAS 5.3 中 log4j2.xml 的 AsyncLogger 配置 ​

CAS 5.3 的 log4j2.xml 配置文件大量使用了 AsyncLogger，这是 Log4j2 的异步日志功能。以下是实际项目中的配置分析：

xml
<?xml version="1.0" encoding="UTF-8"?>
<Configuration monitorInterval="5" packages="org.apereo.cas.logging">
    <Properties>
        <Property name="baseDir">src/main/resources/etc/logs</Property>
    </Properties>

    <Appenders>
        <!-- 控制台输出 -->
        <Console name="console" target="SYSTEM_OUT">
            <PatternLayout pattern="%d %p [%c] - &lt;%m&gt;%n" />
        </Console>

        <!-- 滚动文件输出 -->
        <RollingFile name="file" fileName="${baseDir}/cas.log" append="true"
            filePattern="${baseDir}/cas-%d{yyyy-MM-dd-HH}-%i.log">
            <PatternLayout pattern="%highlight{%d %p [%c] - &lt;%m&gt;}%n" />
            <Policies>
                <OnStartupTriggeringPolicy />
                <SizeBasedTriggeringPolicy size="10 MB" />
                <TimeBasedTriggeringPolicy />
            </Policies>
            <DefaultRolloverStrategy max="5" compressionLevel="9">
                <Delete basePath="${baseDir}" maxDepth="2">
                    <IfFileName glob="*/*.log.gz" />
                    <IfLastModified age="7d" />
                </Delete>
            </DefaultRolloverStrategy>
        </RollingFile>

        <!-- CAS 自定义 Appender -->
        <CasAppender name="casAudit">
            <AppenderRef ref="auditlogfile" />
        </CasAppender>
        <CasAppender name="casFile">
            <AppenderRef ref="file" />
        </CasAppender>
        <CasAppender name="casConsole">
            <AppenderRef ref="console" />
        </CasAppender>
    </Appenders>

    <Loggers>
        <!-- 大量使用 AsyncLogger -->
        <AsyncLogger name="org.apereo.cas.web.CasWebApplication" level="info"
            additivity="false" includeLocation="true">
            <AppenderRef ref="casConsole" />
            <AppenderRef ref="casFile" />
        </AsyncLogger>

        <AsyncLogger name="org.apereo" level="info" additivity="false"
            includeLocation="true">
            <AppenderRef ref="casConsole" />
            <AppenderRef ref="casFile" />
        </AsyncLogger>

        <!-- 大量第三方库的日志级别设置为 off -->
        <AsyncLogger name="org.springframework" level="off" additivity="false">
            <AppenderRef ref="casConsole" />
            <AppenderRef ref="casFile" />
        </AsyncLogger>

        <AsyncLogger name="org.springframework.boot" level="off" additivity="false">
            <AppenderRef ref="casConsole" />
            <AppenderRef ref="casFile" />
        </AsyncLogger>

        <AsyncLogger name="org.thymeleaf" level="off" additivity="false">
            <AppenderRef ref="casConsole" />
            <AppenderRef ref="casFile" />
        </AsyncLogger>

        <!-- 根日志配置 -->
        <AsyncRoot level="error">
            <AppenderRef ref="casConsole" />
        </AsyncRoot>
    </Loggers>
</Configuration>

AsyncLogger 的配置要点：

  1. includeLocation="true"： 在日志中包含调用位置信息（类名、方法名、行号）。这有一定的性能开销，但在调试时非常有用。CAS 对关键模块启用了此选项。

  2. additivity="false"： 禁止日志事件向上传播到父 Logger。这确保了每个 Logger 的日志输出完全由其自身配置控制，避免重复输出。

  3. 大量 level="off" 配置： CAS 将大量第三方库的日志级别设置为 off，这是为了减少日志噪音。在 CAS 的生产环境中，通常只关心 CAS 自身的日志和错误级别的日志。

  4. CasAppender： 这是 CAS 自定义的 Log4j2 Appender，它提供了 CAS 特有的日志功能，如审计日志、性能统计等。

  5. monitorInterval="5"： 每 5 秒检查一次配置文件是否变更，支持配置热重载。

  6. packages="org.apereo.cas.logging"： 指定 Log4j2 插件的搜索包，使得 CasAppender 等自定义插件能够被发现。

AsyncLogger 的性能优势：

Log4j2 的 AsyncLogger 基于 LMAX Disruptor 库实现，使用无锁化环形缓冲区（Ring Buffer）来处理日志事件。相比传统的同步日志和 Logback 的 AsyncAppender，AsyncLogger 的吞吐量可以提升 10-20 倍，延迟降低几个数量级。

在 CAS 的高并发场景中（如大量用户同时登录），AsyncLogger 的性能优势尤为明显。它确保了日志输出不会成为系统的性能瓶颈。

5.6 日志框架冲突的排查方法论 ​

当遇到日志框架冲突时，可以按照以下方法论进行排查：

第一步：检查 SLF4J 绑定警告。

启动应用程序时，检查控制台输出中是否有 SLF4J 的多绑定警告：

SLF4J: Class path contains multiple SLF4J bindings.

如果有这个警告，说明类路径上存在多个 SLF4J 绑定实现，需要排除多余的。

第二步：使用 gradle dependencies 分析日志相关依赖。

bash
# 查看所有日志相关的依赖
./gradlew dependencies --configuration runtimeClasspath | grep -E "(log4j|logback|slf4j|jul)"

第三步：检查是否存在循环桥接。

确认以下组合不会同时存在：

  • log4j-slf4j-impl + log4j-to-slf4j（SLF4J <-> Log4j2 循环）
  • logback-classic + log4j-over-slf4j（SLF4J <-> Logback 循环）

第四步：验证日志输出。

如果日志没有输出，或者输出到了错误的日志框架，检查：

  1. log4j2.xml 配置文件是否在类路径上
  2. log4j-slf4j-impl 是否在类路径上
  3. 是否存在 log4j-to-slf4j 导致日志被路由到错误的框架

第五步：使用 -Dlog4j2.debug 调试。

启动时添加 JVM 参数 -Dlog4j2.debug=true，可以输出 Log4j2 的详细初始化信息，帮助定位配置问题。

5.7 日志框架冲突的真实案例分析 ​

以下案例来自我们实际项目中的真实经历，展示了日志框架冲突的排查过程。

案例背景： CAS 5.3 项目在添加阿里云日志 SDK 后，启动时出现日志输出丢失的问题。CAS 自身的日志（如 org.apereo.cas 包下的日志）正常输出，但阿里云 SDK 的日志完全丢失。

排查过程：

第一步，检查 SLF4J 绑定警告。启动日志中出现了以下警告：

SLF4J: Class path contains multiple SLF4J bindings.
SLF4J: Found binding in [jar:.../log4j-slf4j-impl-2.12.4.jar]
SLF4J: Found binding in [jar:.../logback-classic-1.2.11.jar]

第二步，使用 gradle dependencies 分析：

bash
./gradlew dependencies --configuration runtimeClasspath | grep -E "(log4j|logback|slf4j)"

发现阿里云日志 SDK 传递引入了 logback-classic:1.2.11。

第三步，解决方案：在全局排除中添加 logback-classic 和 logback-core：

groovy
configurations.all {
    exclude group: 'ch.qos.logback', module: 'logback-core'
    exclude group: 'ch.qos.logback', module: 'logback-classic'
}

案例教训： 当引入新的第三方 SDK 时，一定要检查其传递依赖中是否包含了与项目日志框架冲突的日志实现。使用 ./gradlew dependencies 进行检查应该成为引入新依赖的标准流程。

5.8 日志性能调优与依赖选择的关系 ​

日志框架的选择不仅影响依赖管理的复杂度，还直接影响应用程序的性能。在高并发的 CAS 场景中，日志性能尤为重要。

Log4j2 AsyncLogger 的性能优势数据：

根据 Log4j2 官方发布的性能基准测试数据，在不同线程数下，AsyncLogger 的吞吐量表现如下：

线程数Logback (sync)Log4j2 (sync)Log4j2 (AsyncLogger)
12,500 msg/s2,800 msg/s12,000 msg/s
48,000 msg/s9,500 msg/s40,000 msg/s
1625,000 msg/s30,000 msg/s120,000 msg/s
6460,000 msg/s75,000 msg/s300,000 msg/s

可以看到，AsyncLogger 在高并发场景下的吞吐量是 Logback 的 4-5 倍。这对于 CAS 的高并发登录场景（如开学季集中认证）具有重要意义。

AsyncLogger 的依赖要求：

使用 AsyncLogger 需要确保以下依赖在类路径上：

groovy
implementation 'com.lmax:disruptor:3.4.4'  // LMAX Disruptor（Log4j2 AsyncLogger 的依赖）
implementation 'org.apache.logging.log4j:log4j-core:2.12.4'

如果 disruptor 不在类路径上，Log4j2 会回退到同步模式，性能会大幅下降。这也是为什么在 CAS 项目中，确保 Log4j2 相关依赖的版本一致性如此重要——如果 log4j-core 的版本与 disruptor 的版本不兼容，AsyncLogger 可能无法正常工作。

第六章 常见依赖冲突场景与解决方案 ​

6.1 dom4j 版本冲突 ​

dom4j 是 CAS 项目中最常见的依赖冲突源之一。CAS 内部大量使用了 dom4j 来处理 XML 配置和 SAML 元数据。

冲突原因：

dom4j 的版本迁移经历了一个 groupId 的变化：

  • 旧版本：dom4j:dom4j:1.6.1（groupId 为 dom4j）
  • 新版本：org.dom4j:dom4j:2.1.3（groupId 为 org.dom4j）

由于 groupId 不同，Maven 和 Gradle 的依赖解析器会将它们视为不同的依赖。这意味着两个版本可能同时出现在类路径上，导致运行时的类加载冲突。

在 CAS 5.3 中的解决方案：

groovy
// 在 dependencyManagement 中锁定版本
dependency 'org.dom4j:dom4j:2.1.3'

// 在每个 CAS 模块中排除旧版本
implementation('org.apereo.cas:cas-server-core') {
    exclude group: 'dom4j', module: 'dom4j'  // 排除旧 groupId 的 dom4j
}

// 显式引入新版本
implementation 'org.dom4j:dom4j'

在 CAS 6.6 和 7.3 中的解决方案：

在 CAS 6.6 和 7.3 中，BOM 已经管理了 dom4j 的版本，通常不需要手动排除：

groovy
// BOM 会管理 dom4j 的版本
implementation platform("org.apereo.cas:cas-server-support-bom:${project.'cas.version'}")

// 直接使用，不需要指定版本
implementation "org.dom4j:dom4j"

dom4j 冲突的典型错误：

java.lang.NoSuchMethodError: org.dom4j.DocumentHelper.createDocument()Lorg/dom4j/Document;

这个错误通常发生在旧版本的 dom4j 被加载时，因为旧版本的 DocumentHelper.createDocument() 方法签名与新版本不同。

6.2 Jackson 版本不一致 ​

Jackson 是 Java 生态中最广泛使用的 JSON 处理库，CAS 和 Spring Boot 都深度依赖它。Jackson 的版本冲突可能导致 JSON 序列化/反序列化失败。

冲突原因：

CAS 的不同子模块可能依赖不同版本的 Jackson：

  • cas-server-core 可能依赖 jackson-databind:2.12.3
  • cas-server-support-oauth 可能依赖 jackson-databind:2.13.0
  • spring-boot-starter-web 可能依赖 jackson-databind:2.13.4

Jackson 版本冲突的典型错误：

com.fasterxml.jackson.databind.exc.InvalidDefinitionException:
Cannot construct instance of `com.example.MyClass` (no Creators, like default constructor, exist):
cannot deserialize from Object value (no delegate- or property-based Creator)

这个错误可能是因为不同版本的 Jackson 对注解的处理方式不同。

解决方案：

在 CAS 5.3 中，需要在 dependencyManagement 中显式锁定 Jackson 版本：

groovy
dependencyManagement {
    dependencies {
        dependency 'com.fasterxml.jackson.core:jackson-databind:2.13.4.2'
        dependency 'com.fasterxml.jackson.core:jackson-core:2.13.4'
        dependency 'com.fasterxml.jackson.core:jackson-annotations:2.13.4'
    }
}

在 CAS 6.6 和 7.3 中，BOM 已经管理了 Jackson 的版本，通常不需要手动干预。

Jackson 版本兼容性规则：

Jackson 遵循语义化版本控制，同一个主版本内的升级（如 2.12.x 到 2.13.x）通常是向后兼容的。但跨主版本的升级（如 1.x 到 2.x，或 2.x 到 3.x）可能包含破坏性变更。

6.3 Spring Framework 版本冲突 ​

Spring Framework 的版本冲突是 CAS 项目中最严重的冲突类型之一，因为 CAS 的核心功能完全基于 Spring Framework 构建。

冲突原因：

CAS 使用的 Spring Framework 版本由 Spring Boot 的版本决定：

  • CAS 5.3（Spring Boot 2.7.x）-> Spring Framework 5.3.x
  • CAS 6.6（Spring Boot 2.7.x）-> Spring Framework 5.3.x
  • CAS 7.3（Spring Boot 3.5.x）-> Spring Framework 6.x

如果项目中引入了与 CAS 使用的 Spring Framework 版本不兼容的第三方库，就可能出现版本冲突。

Spring Framework 版本冲突的典型错误：

java.lang.NoSuchMethodError: org.springframework.context.ApplicationContext.getBean(Ljava/lang/Class;)Ljava/lang/Object;

这个错误通常发生在第三方库期望的 Spring Framework 版本与实际使用的版本不一致时。

解决方案：

  1. 优先使用 CAS BOM 管理的版本： 不要显式指定 Spring Framework 的版本
  2. 检查第三方库的兼容性： 确保引入的第三方库与 CAS 使用的 Spring Framework 版本兼容
  3. 使用 dependencyInsight 排查：
bash
./gradlew dependencyInsight --dependency spring-core --configuration compileClasspath

6.4 Servlet API 版本（javax vs jakarta） ​

从 Java EE 到 Jakarta EE 的迁移是 CAS 7.3 面临的最大变化之一。这个迁移影响了所有与 Servlet API 相关的依赖。

版本对应关系：

CAS 版本Spring Boot 版本Servlet API命名空间
CAS 5.32.7.xServlet 3.1 / 4.0javax.servlet
CAS 6.62.7.xServlet 3.1 / 4.0javax.servlet
CAS 7.33.5.xServlet 6.0jakarta.servlet

冲突场景：

如果在 CAS 7.3 项目中引入了依赖 javax.servlet 的第三方库，就会出现命名空间冲突。javax.servlet.HttpServlet 和 jakarta.servlet.HttpServlet 是两个完全不同的类，虽然它们的包名和类名几乎相同，但在 JVM 层面是完全不同的类型。

典型错误：

java.lang.NoClassDefFoundError: javax/servlet/http/HttpServletRequest

这个错误在 CAS 7.3 中表示某个库仍然在使用 javax.servlet，而 CAS 7.3 已经迁移到了 jakarta.servlet。

解决方案：

  1. 升级第三方库： 使用支持 Jakarta EE 的版本
  2. 使用 Tomcat 的迁移工具： Tomcat 提供了 jakartaee-migration 工具，可以自动将 javax 替换为 jakarta
  3. 检查依赖树： 确保没有 javax.servlet 相关的依赖
bash
# 检查是否存在 javax.servlet 依赖
./gradlew dependencies --configuration runtimeClasspath | grep javax.servlet

6.5 BouncyCastle 加密库冲突 ​

BouncyCastle 是 Java 生态中最广泛使用的加密库，CAS 使用它来实现票务加密、密码哈希等功能。

冲突原因：

BouncyCastle 有两个主要的 artifact：

  • bcprov-jdk15on：基于 JDK 1.5+ 的提供者
  • bcprov-jdk18on：基于 JDK 1.8+ 的提供者

不同版本的 CAS 和第三方库可能依赖不同的 BouncyCastle artifact，导致冲突。

在 CAS 5.3 和 6.6 中的解决方案：

groovy
// 使用 bcprov-jdk15on（兼容 Java 8）
implementation 'org.bouncycastle:bcprov-jdk15on'

在 CAS 7.3 中的解决方案：

groovy
// 使用 bcprov-jdk15on（仍然兼容 Java 21）
// 注意：BouncyCastle 的 groupId 和 artifactId 可能随版本变化
implementation 'org.bouncycastle:bcprov-jdk15on:1.70'

BouncyCastle 冲突的典型错误：

java.lang.SecurityException: The provider BC may not be signed by a trusted signer

或者：

java.lang.NoSuchProviderException: BC provider not available

这些错误通常发生在 BouncyCastle 的版本不兼容或多个版本同时存在时。

6.6 Spring Data Redis 版本冲突 ​

Spring Data Redis 的版本冲突是 CAS 项目中使用 Redis 票务注册表时最常见的问题。

CAS 5.3 中的版本要求：

CAS 5.3 基于 Spring Framework 5.3.x，需要 spring-data-redis:1.8.x：

groovy
// CAS 5.3 中必须显式指定版本
implementation 'org.springframework.data:spring-data-redis:1.8.23.RELEASE'
implementation 'redis.clients:jedis:2.9.3'

CAS 6.6 中的版本要求：

CAS 6.6 同样基于 Spring Framework 5.3.x，但 BOM 已经管理了 spring-data-redis 的版本，通常不需要手动指定：

groovy
// CAS 6.6 中由 BOM 管理
implementation "org.apereo.cas:cas-server-support-redis-ticket-registry"

CAS 7.3 中的版本要求：

CAS 7.3 基于 Spring Framework 6.x，需要 spring-data-redis:3.x：

groovy
// CAS 7.3 中由 enforcedPlatform 管理
implementation "org.apereo.cas:cas-server-support-redis-ticket-registry"
implementation "org.apereo.cas:cas-server-support-redis-core"

版本冲突的典型错误：

org.springframework.beans.factory.BeanCreationException:
Error creating bean with name 'redisTicketRegistry' defined in class path resource [...]:
Bean instantiation via factory method failed; nested exception is
org.springframework.beans.BeanInstantiationException:
Failed to instantiate [...]: Factory method 'redisTicketRegistry' threw exception;
nested exception is java.lang.AbstractMethodError

AbstractMethodError 通常表示接口方法签名不匹配，即 spring-data-redis 的版本与 CAS 期望的版本不一致。

6.7 Hibernate Validator 冲突 ​

Hibernate Validator 是 Java Bean Validation (JSR 380) 的参考实现。CAS 使用它来验证用户输入和配置参数。

冲突原因：

不同版本的 Hibernate Validator 实现了不同版本的 Bean Validation API：

  • hibernate-validator:6.x -> Bean Validation 2.0 (JSR 380)
  • hibernate-validator:7.x -> Bean Validation 3.0 (JSR 380)

CAS 7.3 基于 Spring Boot 3.x，使用 hibernate-validator:8.x，它实现了 Bean Validation 3.0。

解决方案：

在 CAS 7.3 中，hibernate-validator 的版本由 BOM 管理：

groovy
// CAS 7.3 中由 BOM 管理
implementation "org.hibernate.validator:hibernate-validator"

如果需要显式声明（例如在 CAS 5.3 或 6.6 中），确保版本与 Spring Boot 版本兼容。

6.8 Pac4j 版本冲突 ​

Pac4j 是 CAS 中用于协议支持（如 OAuth、CAS、SAML、OpenID Connect）的核心库。CAS 不同版本对 Pac4j 的版本要求不同。

冲突原因：

  • CAS 5.3 使用 Pac4j 3.x
  • CAS 6.6 使用 Pac4j 4.x 或 5.x
  • CAS 7.3 使用 Pac4j 5.x 或 6.x

如果项目中同时引入了多个 Pac4j 模块（如 pac4j-core、pac4j-http、pac4j-cas），但它们的版本不一致，就可能导致运行时错误。

典型错误：

java.lang.NoSuchMethodError: org.pac4j.core.context.WebContext.getRequestParameter(Ljava/lang/String;)Ljava/lang/String;

解决方案：

确保所有 Pac4j 模块使用同一版本，由 CAS BOM 管理：

groovy
// 不要指定版本，由 BOM 管理
implementation "org.pac4j:pac4j-core"
implementation "org.pac4j:pac4j-http"
implementation "org.pac4j:pac4j-cas"

6.9 Thymeleaf 模板引擎冲突 ​

CAS 使用 Thymeleaf 作为其页面模板引擎。Thymeleaf 的版本冲突可能导致页面渲染失败。

冲突原因：

  • CAS 5.3 使用 Thymeleaf 3.0.x
  • CAS 6.6 使用 Thymeleaf 3.1.x
  • CAS 7.3 使用 Thymeleaf 3.1.x（与 Spring Boot 3.x 兼容）

如果项目中引入了与 CAS 不兼容的 Thymeleaf 版本，可能导致模板解析错误。

典型错误：

org.thymeleaf.exceptions.TemplateInputException:
An error happened during template parsing (template: "classpath:/templates/casLoginView.html")

解决方案：

在 CAS 6.6 的 Maven 版本中，我们遇到了 Thymeleaf Layout Dialect 的版本冲突。解决方案是显式指定兼容的版本：

xml
<dependency>
    <groupId>nz.net.ultraq.thymeleaf</groupId>
    <artifactId>thymeleaf-layout-dialect</artifactId>
    <version>3.4.0</version>
</dependency>

6.10 Netty 与 Servlet 容器的冲突 ​

在某些 CAS 部署场景中，可能需要同时使用 Netty（例如用于 WebSocket 或响应式编程）和 Servlet 容器（如 Tomcat）。这两者之间存在依赖冲突。

冲突原因：

Netty 和 Tomcat 都提供了 HTTP 服务器功能，但它们的实现方式完全不同。如果两者同时存在，可能导致端口冲突或请求路由混乱。

解决方案：

在 CAS 项目中，通常不需要直接引入 Netty。如果某些第三方库传递引入了 Netty，可以通过以下方式排除：

groovy
configurations.all {
    exclude group: 'io.netty', module: 'netty-all'
    // 或者只排除特定的 Netty 模块
    exclude group: 'io.netty', module: 'netty-transport-native-epoll'
}

注意： 在 CAS 7.3 中，如果使用了 Spring WebFlux（响应式编程），可能需要 Netty 作为运行时容器。在这种情况下，不应该排除 Netty，而是需要确保不使用 Tomcat 作为嵌入式容器。CAS 7.3 通过 appServer 属性来控制容器选择。

第七章 依赖分析工具与技巧 ​

7.1 Gradle 依赖树分析 ​

Gradle 提供了强大的依赖分析命令，可以帮助我们理解和排查依赖冲突。

查看完整依赖树：

bash
# 查看编译类路径的依赖树
./gradlew dependencies --configuration compileClasspath

# 查看运行时类路径的依赖树
./gradlew dependencies --configuration runtimeClasspath

# 查看测试类路径的依赖树
./gradlew dependencies --configuration testCompileClasspath

输出示例（简化）：

+--- org.apereo.cas:cas-server-core:6.6.15.2
|    +--- org.apereo.cas:cas-server-core-api:6.6.15.2
|    |    +--- org.springframework:spring-core:5.3.31
|    |    |    \--- org.springframework:spring-jcl:5.3.31
|    |    +--- org.apereo.cas:cas-server-core-api-authentication:6.6.15.2
|    |    \--- com.google.guava:guava:32.1.3-jre
|    +--- org.apereo.cas:cas-server-core-util:6.6.15.2
|    |    +--- org.apache.commons:commons-lang3:3.14.0
|    |    \--- org.springframework:spring-beans:5.3.31
|    \--- org.springframework.security:spring-security-core:5.7.11
|         +--- org.springframework:spring-aop:5.3.31
|         \--- org.springframework:spring-expression:5.3.31

过滤特定依赖：

bash
# 只查看 log4j 相关的依赖
./gradlew dependencies --configuration runtimeClasspath | grep log4j

# 只查看 jackson 相关的依赖
./gradlew dependencies --configuration runtimeClasspath | grep jackson

理解依赖树中的符号：

  • +---：直接依赖
  • \---：最后一个子依赖
  • (*)：已在上面的路径中显示过（省略重复）
  • (n)：版本号（当存在版本冲突时显示）

7.2 Gradle 依赖洞察 ​

dependencyInsight 是 Gradle 提供的另一个强大的依赖分析工具，它可以显示特定依赖的版本解析过程。

查看特定依赖的版本解析：

bash
# 查看 jackson-databind 的版本解析过程
./gradlew dependencyInsight --dependency jackson-databind --configuration compileClasspath

# 查看 log4j-core 的版本解析过程
./gradlew dependencyInsight --dependency log4j-core --configuration runtimeClasspath

# 查看 dom4j 的版本解析过程
./gradlew dependencyInsight --dependency dom4j --configuration compileClasspath

输出示例：

org.apereo.cas:cas-server-core:6.6.15.2
+--- org.apereo.cas:cas-server-core:6.6.15.2
|    \--- com.fasterxml.jackson.core:jackson-databind:2.13.4.2
|
\--- compileClasspath

这个输出告诉我们：

  1. jackson-databind:2.13.4.2 是由 cas-server-core:6.6.15.2 传递引入的
  2. 最终解析的版本是 2.13.4.2

如果存在版本冲突，dependencyInsight 会显示所有请求该依赖的路径，以及最终选择了哪个版本。

7.3 Maven 依赖树分析 ​

对于使用 Maven 构建的 CAS Overlay 项目，Maven 也提供了类似的依赖分析工具。

查看完整依赖树：

bash
# 查看完整的依赖树
mvn dependency:tree

# 查看包含特定关键字的依赖
mvn dependency:tree -Dincludes=org.apache.logging.log4j

# 查看详细输出（包含版本冲突信息）
mvn dependency:tree -Dverbose

依赖分析：

bash
# 分析未使用的已声明依赖
mvn dependency:analyze

# 分析未声明的已使用依赖（应该声明但未声明的依赖）
mvn dependency:analyze -DignoreNonCompile=true

输出示例：

[INFO] --- maven-dependency-plugin:3.6.1:tree (default-cli) @ cas-overlay ---
[INFO] com.example.cas:cas-overlay:jar:1.0-SNAPSHOT
[INFO] +- org.apereo.cas:cas-server-core:jar:5.3.16
[INFO] |  +- org.apereo.cas:cas-server-core-api:jar:5.3.16
[INFO] |  |  \- org.springframework:spring-core:jar:5.3.31
[INFO] |  |     \- org.springframework:spring-jcl:jar:5.3.31
[INFO] |  \- com.google.guava:guava:jar:32.1.3-jre
[INFO] +- org.apereo.cas:cas-server-support-oauth:jar:5.3.16
[INFO] |  \- org.pac4j:pac4j-core:jar:4.5.6

Maven Enforcer 插件：

Maven Enforcer 插件可以在构建时强制执行依赖管理规则：

xml
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-enforcer-plugin</artifactId>
    <version>3.4.1</version>
    <executions>
        <execution>
            <id>enforce-dependency-convergence</id>
            <goals>
                <goal>enforce</goal>
            </goals>
            <configuration>
                <rules>
                    <dependencyConvergence/>
                    <banDuplicateClasses>
                        <ignoreClasses>
                            <ignoreClass>org.slf4j.*</ignoreClass>
                        </ignoreClasses>
                    </banDuplicateClasses>
                </rules>
            </configuration>
        </execution>
    </executions>
</plugin>

7.4 IntelliJ IDEA 依赖分析工具 ​

IntelliJ IDEA 提供了可视化的依赖分析工具，对于排查依赖冲突非常有帮助。

打开依赖分析器：

  1. 打开 File -> Project Structure -> Libraries
  2. 或者右键点击 pom.xml / build.gradle -> Maven / Gradle -> Show Dependencies

依赖分析器的功能：

  1. 依赖树可视化： 以图形方式展示依赖关系
  2. 版本冲突高亮： 自动标记版本冲突
  3. 搜索和过滤： 快速定位特定依赖
  4. 排除操作： 直接在 UI 中添加排除

Maven Helper 插件：

对于 Maven 项目，推荐安装 IntelliJ IDEA 的 "Maven Helper" 插件：

  1. 打开 pom.xml 文件
  2. 切换到 "Dependency Analyzer" 标签页
  3. 点击 "Conflicts" 按钮查看所有版本冲突
  4. 右键点击冲突项可以快速排除

Gradle 依赖分析：

对于 Gradle 项目，IntelliJ IDEA 的 Gradle 插件也提供了依赖分析功能：

  1. 打开 Gradle 工具窗口（View -> Tool Windows -> Gradle）
  2. 右键点击项目 -> Show Dependencies 或 Dependency Analyzer

7.5 持续集成中的依赖检查 ​

在 CI/CD 流水线中集成依赖检查，可以及早发现依赖冲突和安全漏洞。

Gradle 依赖检查任务：

groovy
// 在 build.gradle 中添加依赖检查任务
tasks.register('checkDependencyConflicts') {
    doLast {
        configurations.runtimeClasspath.resolutionResult.allDependencies.each { dep ->
            if (dep instanceof ResolvedDependencyResult) {
                def selected = dep.selected
                println "${selected.moduleVersion}: ${selected.moduleVersion.version}"
            }
        }
    }
}

使用 CycloneDX 生成 SBOM：

CAS 7.3 已经集成了 CycloneDX 插件，可以生成软件物料清单（SBOM）：

groovy
// CAS 7.3 中的 CycloneDX 配置
apply plugin: "org.cyclonedx.bom"

cyclonedxBom {
    includeConfigs = ["runtimeClasspath"]
    schemaVersion = "1.5"
    destination = file("build/reports")
    outputName = "sbom"
    outputFormat = "json"
}

生成的 SBOM 可以用于：

  1. 依赖版本审计
  2. 安全漏洞扫描
  3. 许可证合规检查

GitHub Actions 中的依赖检查：

yaml
name: Dependency Check
on: [push, pull_request]
jobs:
  dependency-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          java-version: '21'
          distribution: 'temurin'
      - name: Check dependencies
        run: |
          chmod +x gradlew
          ./gradlew dependencies --configuration runtimeClasspath > dependency-tree.txt
          # 检查是否存在版本冲突
          if grep -q "FAILED" dependency-tree.txt; then
            echo "Dependency conflict detected!"
            exit 1
          fi
      - name: Generate SBOM
        run: ./gradlew cyclonedxBom

7.6 依赖冲突的自动化检测与修复 ​

在现代软件开发实践中，依赖冲突的检测和修复应该尽可能自动化。以下是一些自动化策略。

Gradle 的自动版本冲突检测：

groovy
// 在 build.gradle 中添加版本冲突检测任务
tasks.register('detectVersionConflicts') {
    doLast {
        def conflicts = []
        configurations.runtimeClasspath.resolutionResult.allDependencies.each { result ->
            if (result instanceof ResolvedDependencyResult) {
                def selected = result.selected
                result.allSelections.each { selection ->
                    if (selection.moduleVersion.version != selected.moduleVersion.version) {
                        conflicts << "${selected.moduleVersion}: " +
                            "selected=${selected.moduleVersion.version}, " +
                            "rejected=${selection.moduleVersion.version}"
                    }
                }
            }
        }
        if (conflicts) {
            println "=== Version Conflicts Detected ==="
            conflicts.each { println "  - ${it}" }
            println "================================="
            if (project.hasProperty("failOnVersionConflict") &&
                Boolean.valueOf(project.getProperty("failOnVersionConflict"))) {
                throw new GradleException("${conflicts.size()} version conflicts detected!")
            }
        } else {
            println "No version conflicts detected."
        }
    }
}

OWASP Dependency-Check 集成：

OWASP Dependency-Check 是一个开源的工具，可以扫描项目的依赖，检测已知的安全漏洞：

groovy
// 在 build.gradle 中集成 OWASP Dependency-Check
plugins {
    id 'org.owasp.dependencycheck' version '9.0.9'
}

dependencyCheck {
    scanConfigurations = ['runtimeClasspath', 'compileClasspath']
    failBuildOnCVSS = 7
    format = 'HTML'
    outputDirectory = file('build/reports/dependency-check')
}

持续监控策略：

  1. 定期扫描： 每周运行一次 OWASP Dependency-Check，及时发现新的安全漏洞
  2. 版本锁定文件： 使用 Gradle 的依赖锁定文件，确保构建的可复现性
  3. 自动化 PR： 当发现新的安全漏洞时，自动创建 PR 来更新依赖版本
  4. 依赖更新机器人： 使用 Dependabot 或 Renovate Bot 自动创建依赖更新 PR

第八章 最佳实践总结 ​

8.1 优先使用 BOM 管理版本 ​

BOM（Bill of Materials）是 Java 依赖管理的最佳实践。通过 BOM，可以将版本管理集中化，避免版本不一致的问题。

BOM 的使用原则：

  1. 优先使用项目提供的 BOM： CAS 提供了 cas-server-support-bom，应该优先使用它来管理所有 CAS 相关依赖的版本
  2. BOM 导入顺序很重要： 在多个 BOM 管理同一个库的不同版本时，后导入的 BOM 优先级更高
  3. 使用 enforcedPlatform() 确保版本一致性： 对于需要严格版本控制的场景，使用 enforcedPlatform() 替代 platform()
  4. 不要在 BOM 之外随意覆盖版本： 如果必须覆盖 BOM 中的版本，使用 resolutionStrategy.eachDependency 并添加注释说明原因

Gradle 中的 BOM 使用模式：

groovy
dependencies {
    // CAS BOM - 使用 enforcedPlatform 确保版本一致性
    implementation enforcedPlatform("org.apereo.cas:cas-server-support-bom:${casVersion}")

    // Spring Boot BOM - 使用 platform 提供版本建议
    implementation platform(org.springframework.boot.gradle.plugin.SpringBootPlugin.BOM_COORDINATES)

    // CAS 模块 - 不需要指定版本
    implementation "org.apereo.cas:cas-server-core"
    implementation "org.apereo.cas:cas-server-support-oauth"
}

Maven 中的 BOM 使用模式：

xml
<dependencyManagement>
    <dependencies>
        <!-- CAS BOM -->
        <dependency>
            <groupId>org.apereo.cas</groupId>
            <artifactId>cas-server-support-bom</artifactId>
            <version>${cas.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
        <!-- Spring Boot BOM -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-dependencies</artifactId>
            <version>${spring.boot.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

8.2 全局排除优于逐个排除 ​

全局排除（configurations.all）是管理日志框架等通用排除的最佳方式。相比逐个模块排除，全局排除具有以下优势：

  1. 维护成本低： 只需要在一个地方声明排除规则
  2. 不易遗漏： 所有模块自动应用排除规则
  3. 可读性好： 排除规则集中管理，一目了然
  4. 升级友好： 新增模块时不需要额外的排除配置

全局排除的最佳实践配置：

groovy
configurations {
    all {
        resolutionStrategy {
            cacheChangingModulesFor 0, "seconds"
            cacheDynamicVersionsFor 0, "seconds"
            preferProjectModules()
        }

        // 日志框架冲突 - 全局排除
        exclude(group: "cglib", module: "cglib")
        exclude(group: "cglib", module: "cglib-full")
        exclude(group: "org.slf4j", module: "slf4j-log4j12")
        exclude(group: "org.slf4j", module: "slf4j-simple")
        exclude(group: "org.slf4j", module: "jcl-over-slf4j")
        exclude(group: "org.apache.logging.log4j", module: "log4j-to-slf4j")
        exclude(group: "ch.qos.logback", module: "logback-core")
        exclude(group: "ch.qos.logback", module: "logback-classic")
    }
}

何时使用逐个排除：

虽然全局排除是首选，但在以下场景中仍然需要逐个排除：

  1. 特定模块的特殊需求： 某个模块需要与全局排除不同的配置
  2. 第三方库的已知问题： 某个特定版本的第三方库引入了有问题的依赖
  3. 临时调试： 在排查特定模块的依赖冲突时，临时添加排除

8.3 显式声明关键依赖版本 ​

虽然 BOM 能够管理大部分依赖的版本，但对于以下类型的依赖，建议显式声明版本：

  1. 安全敏感的依赖： 如 BouncyCastle、加密库等
  2. 已知有兼容性问题的依赖： 如 Spring Data Redis、Jedis 等
  3. 项目直接使用的依赖： 如 MyBatis、MySQL Connector 等
  4. 非 CAS BOM 管理的依赖： 如某些第三方库

显式版本声明的最佳实践：

groovy
dependencies {
    // 由 BOM 管理的 CAS 模块 - 不需要版本号
    implementation "org.apereo.cas:cas-server-core"
    implementation "org.apereo.cas:cas-server-support-oauth"

    // 项目直接使用的依赖 - 显式声明版本
    implementation "org.mybatis:mybatis:3.5.16"
    implementation "org.mybatis:mybatis-spring:3.0.3"
    implementation "mysql:mysql-connector-java:8.0.33"
    implementation "org.apache.commons:commons-dbcp2:2.10.0"

    // 安全敏感的依赖 - 显式声明版本
    implementation "org.bouncycastle:bcprov-jdk15on:1.70"
}

8.4 持续集成中的依赖检查 ​

在 CI/CD 流水线中集成依赖检查，可以及早发现依赖冲突和安全漏洞。

推荐的 CI/CD 依赖检查流程：

  1. 构建阶段： 运行 ./gradlew build，确保编译通过
  2. 依赖分析阶段： 运行 ./gradlew dependencies，检查依赖树
  3. 版本冲突检查： 运行 ./gradlew build -PfailOnVersionConflict=true，确保无版本冲突
  4. SBOM 生成阶段： 运行 ./gradlew cyclonedxBom，生成软件物料清单
  5. 安全扫描阶段： 使用 OWASP Dependency-Check 或 Snyk 扫描安全漏洞

Gradle 构建脚本中的依赖检查配置：

groovy
// 在 gradle.properties 中配置
failOnVersionConflict=false  // 日常开发中关闭
// 在 CI 中通过 -PfailOnVersionConflict=true 开启

8.5 版本升级的策略与节奏 ​

CAS 版本升级是依赖管理中最具挑战性的任务之一。以下是基于实际项目经验的升级策略：

CAS 5.3 -> CAS 6.6 升级要点：

  1. Java 版本升级： Java 8 -> Java 11
  2. BOM 导入方式变更： dependencyManagement -> platform()
  3. 全局排除策略扩展： 从 2 个全局排除扩展到 8 个
  4. 移除逐个模块的 exclude： 将日志框架相关的排除提升到全局
  5. 移除显式版本锁定： spring-data-redis、jedis、tomcat-embed-core 等不再需要显式指定版本
  6. 依赖声明简化： 每个 CAS 模块从 5-7 行减少到 1 行

CAS 6.6 -> CAS 7.3 升级要点：

  1. Java 版本升级： Java 11 -> Java 21
  2. Spring Boot 版本升级： 2.7.x -> 3.5.x
  3. BOM 导入方式变更： platform() -> enforcedPlatform()
  4. javax -> jakarta 迁移： 所有 javax.servlet 替换为 jakarta.servlet
  5. Gradle 版本升级： 7.x -> 9.x
  6. MyBatis 版本升级： 3.5.6 -> 3.5.16，mybatis-spring 1.3.1 -> 3.0.3
  7. 连接池升级： commons-dbcp:1.4 -> commons-dbcp2:2.10.0

升级的通用建议：

  1. 先在独立分支上升级： 不要在主分支上直接升级。创建一个专门的升级分支，在隔离的环境中进行升级工作。升级完成后，经过充分的测试和代码审查，再合并到主分支。
  2. 逐步升级： 不要跨多个大版本升级，逐步进行（如 5.3 -> 6.0 -> 6.6 -> 7.0 -> 7.3）。每一步升级都应该是一个可独立验证的里程碑。如果跨版本升级失败，可以回退到上一个已验证的版本。
  3. 充分的回归测试： 升级后必须进行全面的回归测试，包括但不限于：用户登录/登出流程、票务管理、OAuth2 授权流程、REST API 调用、LDAP 认证、密码策略验证等核心功能。
  4. 关注 CAS 的 Release Notes： 每个版本的 Release Notes 中会标注破坏性变更（Breaking Changes），这些变更通常涉及依赖版本的变化或 API 的调整，需要特别关注。
  5. 使用 CAS 的初始模板： 从 CAS 官方的 Overlay 模板开始，逐步添加自定义配置。官方模板已经处理了大部分依赖冲突问题，可以作为升级的基准。
  6. 保留旧版本的配置备份： 在升级前，完整备份旧版本的构建配置文件（build.gradle 或 pom.xml），以便在升级失败时快速回退。
  7. 利用 CI/CD 流水线进行自动化验证： 将升级后的构建和测试集成到 CI/CD 流水线中，确保每次提交都经过自动化的依赖冲突检测和功能验证。

8.6 三代 CAS 版本依赖管理对比总结 ​

以下是对 CAS 5.3、6.6、7.3 三个版本依赖管理策略的全面对比：

维度CAS 5.3CAS 6.6CAS 7.3
Java 版本81121
Spring Boot2.7.x2.7.x3.5.x
Gradle7.x7.x9.x
BOM 导入方式dependencyManagement + mavenBomplatform()enforcedPlatform()
全局 exclude 数量2 个8 个8 个
每个模块 exclude 数量5-7 个0 个0 个
显式版本锁定数量15+ 个2-3 个0-1 个
dependencyManagement 版本声明15+ 个0 个0 个
Log4j BOM 独立导入需要不需要不需要
spring-data-redis 版本锁定需要 (1.8.23)不需要不需要
jedis 版本锁定需要 (2.9.3)不需要不需要
tomcat-embed-core 版本锁定需要 (8.5.32)可选可选
日志框架Log4j2 2.12.4Log4j2 (BOM 管理)Log4j2 (BOM 管理)
Servlet APIjavaxjavaxjakarta
配置代码量（依赖部分）~500 行~200 行~150 行
依赖冲突频率高中低
维护难度高中低

演进趋势总结：

从 CAS 5.3 到 CAS 7.3，依赖管理策略的演进呈现出以下趋势：

  1. 从手动到自动： 版本管理从手动指定到 BOM 自动管理
  2. 从分散到集中： 排除策略从逐个模块分散管理到全局集中管理
  3. 从宽松到严格： BOM 从 platform() 到 enforcedPlatform()，版本控制越来越严格
  4. 从复杂到简洁： 配置代码量从 500 行减少到 150 行，减少了 70%
  5. 从 Java EE 到 Jakarta EE： 跟随 Spring Boot 3.x 的迁移，完成了命名空间的现代化

8.7 构建可复现的依赖管理流水线 ​

在大型团队协作和 CI/CD 环境中，依赖管理的可复现性至关重要。以下策略可以确保不同环境下的构建结果一致。

Gradle 依赖锁定：

Gradle 支持生成依赖锁定文件，确保每次构建使用完全相同的依赖版本：

bash
# 生成依赖锁定文件
./gradlew dependencies --write-locks

# 使用锁定文件进行构建
./gradlew build --read-locks

锁定文件会记录所有依赖（包括传递依赖）的精确版本、校验和等信息。一旦生成了锁定文件，即使仓库中发布了新版本，构建也会使用锁定文件中记录的版本。

依赖仓库的镜像和代理：

在企业环境中，使用内部 Maven 仓库代理（如 Nexus Repository Manager 或 Artifactory）可以确保依赖的一致性：

groovy
repositories {
    // 优先使用内部仓库
    maven {
        url 'https://nexus.example.com/repository/maven-public/'
    }
    // 外部仓库作为后备
    mavenCentral()
    maven {
        url 'https://build.shibboleth.net/nexus/content/repositories/releases/'
    }
}

Gradle 构建缓存的配置：

CAS 项目的 gradle.properties 中通常包含以下缓存配置：

properties
org.gradle.configureondemand=true
org.gradle.caching=true
org.gradle.parallel=true

这些配置可以加速构建，但需要注意缓存可能导致依赖解析结果不一致。在排查依赖冲突时，建议临时关闭缓存：

bash
./gradlew build --no-build-cache --no-configuration-cache

8.8 从架构视角看依赖管理的未来趋势 ​

依赖管理作为软件工程的基础设施，正在经历深刻的变革。从 CAS 的演进历程中，我们可以看到以下趋势：

趋势一：BOM 即契约（BOM as Contract）

随着 enforcedPlatform() 的广泛应用，BOM 正在从"版本建议"演变为"版本契约"。这意味着依赖版本不再是一个可以随意覆盖的建议，而是一个必须遵守的契约。这种模式在微服务架构中尤为重要——当多个服务使用相同的 BOM 时，可以确保整个系统的版本一致性。

趋势二：SBOM（Software Bill of Materials）成为标准

随着供应链安全法规（如美国行政令 EO 14028）的实施，SBOM 正在成为软件交付的标准要求。CAS 7.3 集成的 CycloneDX 插件正是这一趋势的体现。未来，SBOM 不仅用于安全扫描，还将用于许可证合规、版本审计、依赖风险评估等多个场景。

趋势三：自动化依赖管理

Dependabot、Renovate Bot 等自动化依赖管理工具正在改变依赖管理的实践方式。这些工具可以自动检测依赖更新、创建 PR、运行测试，大幅降低依赖管理的手动工作量。在 CAS 项目中，结合 BOM 的版本契约和自动化工具，可以实现依赖管理的全自动化。

趋势四：容器化与依赖管理的融合

随着容器化部署的普及，依赖管理与容器镜像管理正在融合。Jib 插件可以将依赖分析、SBOM 生成和容器镜像构建整合到一个流水线中。未来，依赖管理将不再局限于构建阶段，而是贯穿整个软件交付生命周期。

趋势五：模块化（JPMS）对依赖管理的影响

Java 的模块系统（JPMS）虽然目前对 CAS 的影响有限，但随着 Java 平台的持续演进，模块化将从根本上改变依赖管理的方式。模块化的 requires 和 exports 声明可以提供编译期的依赖验证，从根本上消除某些类型的依赖冲突。例如，requires static 可以声明可选依赖，requires transitive 可以强制传递依赖，这些机制比传统的 classpath 依赖管理更加精确和安全。

对 CAS 开发者的启示：

从 CAS 5.3 到 CAS 7.3 的依赖管理演进历程告诉我们，依赖管理不是一个静态的技术问题，而是一个持续演进的工程实践。作为 CAS 开发者，我们需要：

  1. 持续关注构建工具的更新： Gradle 和 Maven 不断推出新的依赖管理特性，及时采用可以显著降低维护成本
  2. 建立依赖管理的标准化流程： 将本文介绍的最佳实践固化为团队的开发规范
  3. 投资自动化工具： 自动化的依赖检测、冲突排查和版本更新工具可以大幅降低人工成本
  4. 保持对新技术的敏感度： 关注 SBOM、模块化、容器化等新技术对依赖管理的影响，提前做好技术储备

附录 ​

附录 A：CAS 版本与 Spring Boot 版本对应关系 ​

CAS 版本Spring Boot 版本Java 版本Servlet APIGradle 版本
5.3.x2.0.x - 2.7.x8+javax (3.1/4.0)4.x - 7.x
6.0.x - 6.3.x2.3.x - 2.5.x11+javax (4.0)6.x - 7.x
6.4.x - 6.6.x2.7.x11+javax (4.0)7.x
7.0.x3.0.x - 3.1.x17+jakarta (6.0)7.x - 8.x
7.1.x - 7.2.x3.2.x - 3.4.x17+jakarta (6.0)8.x
7.3.x3.5.x21+jakarta (6.0)8.x - 9.x

附录 B：常用排除项速查表 ​

排除项原因适用版本
spring-boot-devtools生产环境不需要5.3
log4j-slf4j-impl版本统一管理5.3
log4j-webSpring Boot 负责初始化5.3
slf4j-api版本统一管理5.3
jul-to-slf4j避免重复桥接5.3
dom4j:dom4jgroupId 变化5.3
xpp3:xpp3XML 解析器冲突5.3
cglib:cglib已停止维护6.6, 7.3
slf4j-log4j12Log4j 1.x 绑定冲突6.6, 7.3
slf4j-simple不适合生产环境6.6, 7.3
jcl-over-slf4jJCL 桥接冲突6.6, 7.3
log4j-to-slf4j防止循环调用6.6, 7.3
logback-coreCAS 使用 Log4j26.6, 7.3
logback-classicCAS 使用 Log4j26.6, 7.3
spring-boot-starter-logging使用 Log4j2 替代全部

附录 C：依赖分析命令速查表 ​

Gradle 命令 ​

bash
# 查看完整依赖树
./gradlew dependencies --configuration compileClasspath
./gradlew dependencies --configuration runtimeClasspath

# 查看特定依赖的版本解析
./gradlew dependencyInsight --dependency <dependency-name> --configuration compileClasspath

# 开启版本冲突严格模式
./gradlew build -PfailOnVersionConflict=true

# 查看特定配置的依赖
./gradlew dependencies --configuration testRuntimeClasspath

# 生成 SBOM
./gradlew cyclonedxBom

Maven 命令 ​

bash
# 查看完整依赖树
mvn dependency:tree

# 查看特定依赖
mvn dependency:tree -Dincludes=<group>:<artifact>

# 详细输出（包含版本冲突）
mvn dependency:tree -Dverbose

# 分析未使用的依赖
mvn dependency:analyze

# 依赖管理信息
mvn help:effective-pom

附录 D：参考资料 ​

  1. Apereo CAS 官方文档
  2. CAS Overlay 项目模板
  3. Gradle 依赖管理指南
  4. SLF4J 官方文档
  5. Log4j2 官方文档
  6. Spring Boot 依赖管理
  7. Maven 依赖管理
  8. CAS 5.3 Release Notes
  9. CAS 6.6 Release Notes
  10. CAS 7.3 Release Notes

附录 E：术语表 ​

术语全称说明
BOMBill of Materials物料清单，用于集中管理依赖版本
CASCentral Authentication Service中央认证服务，Apereo 开源 SSO 解决方案
SLF4JSimple Logging Facade for JavaJava 简单日志门面
JCLJakarta Commons Logging (原 Apache Commons Logging)Apache 日志门面
JULJava Util LoggingJDK 自带日志框架
JPMSJava Platform Module SystemJava 平台模块系统
SBOMSoftware Bill of Materials软件物料清单
OverlayOverlayCAS 的定制化部署方式，通过覆盖默认配置实现定制
SPIService Provider Interface服务提供者接口，Java 的服务发现机制
CVECommon Vulnerabilities and Exposures通用漏洞披露
CVSSCommon Vulnerability Scoring System通用漏洞评分系统
CycloneDXCycloneDX开源的 SBOM 标准
DisruptorLMAX Disruptor高性能线程间消息传递库，Log4j2 AsyncLogger 的基础
platform()Gradle PlatformGradle 的 BOM 导入方式，提供版本建议
enforcedPlatform()Gradle Enforced PlatformGradle 的强化 BOM 导入方式，强制版本一致性
dependencyManagementMaven Dependency ManagementMaven 的依赖版本管理机制
mavenBomMaven BOM ImportGradle 的 io.spring.dependency-management 插件的 BOM 导入方式
resolutionStrategyGradle Resolution StrategyGradle 的依赖解析策略
configurations.allGradle Configurations AllGradle 的全局配置机制
excludeDependency Exclude依赖排除，阻止传递依赖的引入
eachDependencyGradle EachDependencyGradle 的逐依赖版本覆盖机制
failOnVersionConflictGradle Fail On Version ConflictGradle 的版本冲突严格模式
AsyncLoggerLog4j2 Async LoggerLog4j2 的异步日志器，基于 Disruptor 实现
CasAppenderCAS Log4j2 AppenderCAS 自定义的 Log4j2 Appender
JibGoogle JibGoogle 的容器镜像构建工具
ShibbolethShibboleth Consortium互联网身份认证联盟，CAS 的依赖仓库之一
OpenSAMLOpenSAML开源的 SAML 实现库
Pac4jPac4jJava 的认证和授权框架
javaxJava EE NamespaceJava EE 的命名空间
jakartaJakarta EE NamespaceJakarta EE 的命名空间（Java EE 的继任者）

版权声明： 本文为必码（bima.cc）原创技术文章，仅供学习交流。

本文内容基于实际项目源码解析整理，代码示例均为教学简化版本，仅供学习参考。

文档内容提取自项目源码与配置文件，如需获取完整项目代码，请访问 bima.cc。

© 2024-至今 北京必码科技工作室 bima.cc