基础设施起步依赖范式 (Infrastructure Starter Pattern)

在后端架构开发（尤其是基于 Spring Boot 的微服务体系）中，这种“自动配置 + 统一拦截”的设计模式被称为 “基础设施起步依赖范式 (Infrastructure Starter Pattern)”。

当你需要为全公司或全项目提供一个通用功能（如 XSS、限流、日志、异常处理）时，可以套用以下这套**“五步法”**：

第一步：定义配置属性 (Properties)

目的： 让功能“可配置、可开关”。

• 范式： 创建 XxxProperties 类，使用 @ConfigurationProperties。

• 原则： 必须提供 enable 开关，方便在紧急情况下通过 Nacos 直接关闭该功能。

第二步：核心逻辑抽象 (Core Logic)

目的： 业务逻辑与 Spring 框架解耦。

• 范式： 定义一个接口（如 XssCleaner、ApiEncryptor）。

• 原则： 这样如果未来想把 Jsoup 换成其他清理工具，只需更换实现类，不需要改动配置代码。

第三步：多维拦截适配 (Adapters)

目的： 覆盖所有入口（HTTP、JSON、RPC）。

根据数据流向，通常需要实现三个层面的适配器：

1. Servlet 层 (Filter/Interceptor)：拦截传统的表单、URL 参数。

2. 序列化层 (Jackson Serializer/Deserializer)：拦截 JSON 格式的 RequestBody。

3. 切面层 (AOP)：拦截特定注解标注的方法或类。

第四步：自动配置声明 (Auto-Configuration)

目的： 实现“引入即生效”。

• 范式： 1. 创建 XxxAutoConfiguration。

  2. 使用 @ConditionalOnProperty 绑定第一步的开关。

  3. 使用 @ConditionalOnMissingBean 保证用户可以自定义实现并覆盖你的默认逻辑（提供扩展性）。

第五步：SPI 注册 (Spring Boot 3 标准)

目的： 告诉 Spring 这是一个自动配置类。

• 范式： 在 resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports 中写入配置类的全类名。

避坑指南（套用时的关键细节）

1. 优先级管理 (Order)

• Filter：一定要考虑顺序。例如 XSS 过滤必须在业务逻辑之前，但在认证（Auth）之后。使用 FilterRegistrationBean.setOrder() 明确位置。

• Configuration：使用 @AutoConfiguration(before = ..., after = ...) 控制配置类的加载顺序。

2. 条件依赖 (Conditionals)

• 环境兼容：如果是通用 Starter，必须考虑 MVC 还是 WebFlux。利用 @ConditionalOnClass(name = "...") 避免在缺失相关 jar 包时报 ClassNotFoundException。

3. 排除机制 (Exclude URLs)

• 所有拦截器必须配套“排除机制”。因为总会有特殊业务（如富文本、文件上传、回调接口）不符合通用规则。

总结模板：你的思维导图