👉目录

1 约定与现状：主应用能做到，插件为什么不行？

2 MVC 模式：当配置不生效时，追溯源码

3 MVC 模式：实现方案

4 WebFlux 模式：不同的架构，同一个约定

5 实践与思考

6 写在最后

在插件框架的设计中，我们希望尽可能降低插件开发者的心智负担。控制器路径大小写不敏感就是其中一条：开发者不需要关心调用方用的是什么命名风格，框架保证路径能匹配上就对了。

Java生态： ▎gj.spring.pf4j正式发布。 基于 PF4J + Spring 的轻量级模块化插件框架，无 Spring Boot 运行时依赖。支持 MVC / WebFlux ，双栈路由、MyBatis-Plus 多数据源隔离、7 种数据库自动迁移等等，欢迎star&共同交流。

https://github.com/wangpengxpy/gj.spring.pf4j

  .NET 生态： ▎ EntityFrameworkCore.Dm 发布 .NET 10 适配版——国产达梦数据库 EF Core 官方驱动，让 .NET 10 开发者以 LINQ，直连达梦，无缝融入 EF Core 生态。

https://github.com/dotnetcore/EntityFrameworkCore.Dm

采用 PF4J 插件架构。框架为 MVC 和 WebFlux 两种模式分别提供了插件控制器路由管理

• MVC 模式：GJPluginRequestMappingHandlerMapping（继承 Spring MVC 的 RequestMappingHandlerMapping）

• WebFlux 模式：GJPluginWebFluxRequestMappingHandlerMapping（继承 WebFlux 的 RequestMappingHandlerMapping）

主应用实现路径大小写不敏感的典型配置如下：

@Configurationpublic class WebConfig implements WebMvcConfigurer {    @Override    public void configurePathMatch(PathMatchConfigurer configurer) {        AntPathMatcher matcher = new AntPathMatcher();        matcher.setCaseSensitive(false);        configurer.setPathMatcher(matcher);    }}

敲黑板： 同样的配置方式，主应用生效，插件不生效。这说明在落地约定时，主应用和插件 handler mapping 经历了不同的初始化路径，我们只复制了配置，没有复制初始化路径的差异。

2.1 一个矛盾的信号

为了验证配置是否真的不生效，在匹配逻辑中加入诊断日志：

getPathMatcher().match("getOrganizationInfo", "GetOrganizationInfo") 返回了 true

说明 handler mapping 上的AntPathMatcher(caseSensitive=false) 确实被设置上去了。但最终路由匹配返回了 null。

说明 handler mapping 自身的 matcher 能正确判断两个字符串的大小写不敏感匹配，但 RequestMappingInfo 在做路径匹配时走的是另一条路径，完全没用到这个 matcher。

2.2  Spring 6.x MVC 的双路匹配机制

深入 RequestMappingInfo 的构建过程，发现 Spring 6.x MVC 在路径匹配上存在两套并行的机制：

在 RequestMappingInfo 的 DefaultBuilder.build() 方法中：

而 getPatternParserToUse() 的决策链如下：

敲黑板：patternParser 的优先级高于 pathMatcher——只要 patternParser 不为 null，就永远走 PathPatternParser 路径。你在 pathMatcher 上的所有配置（包括大小写不敏感）都静默失效，没有任何警告。

2.3 链路还原

完整的决策链路如下：

1. GJPluginConfig 创建 handler mapping 时，调用了 setPathMatcher()，没有主动调用 setPatternParser(null)

2. Spring 6.x 为 AbstractHandlerMapping 注入了默认的 PathPatternParser 实例 → getPatternParser() 返回非 null

3. afterPropertiesSet() 检测到 getPatternParser() != null执行 this.config.setPatternParser(getPatternParser())，而不是this.config.setPathMatcher(getPathMatcher())

4. 后续创建 RequestMappingInfo 时，options.getPatternParserToUse() 返回了默认的 PathPatternParser

5. 最终创建的是 PathPatternsRequestCondition，大小写由 PathPatternParser 决定（默认敏感），我们设置的 AntPathMatcher(caseSensitive=false) 被完全绕过

2.3 主应用为什么可以？

这是理解整个问题的关键。主应用的 requestMappingHandlerMapping 不是简单的 @Bean 创建，而是由 WebMvcConfigurationSupport 创建后经过 initHandlerMapping() 处理：

Spring 在初始化主应用 handler mapping 时，检测到用户通过 WebMvcConfigurer.configurePathMatch() 配置了自定义 pathMatcher，会自动将 patternParser 置 null，使匹配链路回退到 AntPathMatcher 路径。

但我们的插件 handler mapping 是 @Bean 方法中直接 new 出来的，完全绕过了 initHandlerMapping() 这个处理环节。

敲黑板： Spring 对自己的"handler mapping 和"用户手动创建"的 handler mapping 走了不同的初始化路径。我们需要手动补齐 initHandlerMapping() 做的事情。

链路分析清楚后，实现就一一对应了——在创建插件 handler mapping 时，显式将 patternParser 置为 null

使匹配链路回到我们配置的 AntPathMatcher(caseSensitive=false)

1. setPatternParser(null) 是落地的核心，它将 patternParser 置为 null，使得 afterPropertiesSet() 走 else 分支

2. 将AntPathMatcher(caseSensitive=false)写入 config。

3. 后续 RequestMappingInfo创建时，getPatternParserToUse()返回 null，走 

PatternsRequestCondition 路径，大小写不敏感匹配生效。

MVC 模式的实现链路：

MVC 模式完成后，自然要问：WebFlux 需要同样的处理吗？

4.1 WebFlux 没有双路机制

答案是不需要同样的处理，但同样需要落地约定——因为 PathPatternParser 默认大小写敏感。

MVC 和 WebFlux 的 AbstractHandlerMapping是两个独立的类层级：

WebFlux 在架构上已经抛弃了 AntPathMatcher，全部走 PathPatternParser。

因此不存在"配置了 matcher 被 parser 绕过"的问题，但也意味着无法通过置 null 的方式来控制大小写——需要用 WebFlux 自身提供的 API。

敲黑板： WebFlux 的 API 设计更直白——既然只有一套匹配机制，那就直接提供一个开关来控制大小写。MVC 的复杂性来源于需要同时兼容新旧两套机制。

4.2 WebFlux 实现方案

WebFlux 落地约定的方式非常直接：

它内部直接修改 PathPatternParser 的 caseSensitive 属性为 false。一条 API 调用，语义清晰，无需理解双路机制的内部决策逻辑。

实现链路：

到这里我们已经大致了解原理和实现细节，在整个约定落地的过程中，有几个值得留意的点

5.1 手动创建 Spring 内置组件时注意初始化路径差异

Spring Boot 自动配置的组件会经过一系列后处理流程（如 initHandlerMapping()），而手动 @Bean 创建的实例需要自己补齐这些处理。下次遇到"配置看起来一样但不生效"的情况，先怀疑初始化路径差异。

5.2 MVC 的双路机制容易形成"静默失效"

patternParser 优先级高于 pathMatcher，但两者可以通过不同的 API 独立设置。当你调用 setPathMatcher() 但 patternParser 恰好不为 null 时，matcher 的配置静默不生效且没有任何警告。这是一个典型的 API 设计问题——两个有优先级的配置项应该通过同一个入口管理。

5.3 WebFlux 的 API 设计更好

单路机制 + setUseCaseSensitiveMatch(boolean) 语义明确，没有隐藏的优先级规则。如果Spring MVC 未来废弃 AntPathMatcher，统一为 PathPatternParser 单路机制，这类问题自然消失。

控制器路径大小写不敏感，从使用者的角度看只是一个简单的约定，但从框架实现的角度，需要在 Spring 6.x 两套 Web 栈、两套路径匹配机制之间找到正确的配置方式。MVC 需要理解双路优先级规则，WebFlux 需要找到正确的 API——看起来简单的事情，实际落地时往往比预期要复杂一些。

两个模式的约定均已在插件化架构落地实现，插件控制器路由现在统一支持大小写不敏感匹配。

以上全文基于个人理解，欢迎批评指正。