✨ 前言
作者：bailiun
注:作者长期徘徊在“复刻轮子”和“造新轮子”的边缘地带，且信息获取水平在“原始人”和“现代人”之间反复横跳，若有类似组件出现，纯属灵魂频率共振，非抄袭，敬请海涵。若不是，那大概是地球引力的锅。。。
因为人的运气即为重力!!!
与市面上常见的版本控制框架不同，Multiple Versions Coexist 不是通过路径标识、分支代码或手动模块区分来实现多版本管理的，也不同于市面上依赖
v1/v2路径区分、包层隔离或多模块部署的版本管理方式。而是通过 运行时动态注册、注入优先级、环境匹配与条件控制 来实现 接口级别的版本共存与灵活切换，Multiple Versions Coexist 通过注入优先级与动态注册机制，使多个版本接口在同一运行环境中并存、控制、切换，而无需代码分支或重复工程。
项目地址：GitHub - bailiun/multiple-versions-coexist(早期测试版源码)
组件功能详解篇：Multiple Versions Coexist —— 一种区别于传统方案的运行时多版本管理机制的功能介绍[（](Multiple Versions Coexist —— 一种区别于传统方案的运行时多版本管理机制的功能介绍Multip - 掘金)如果要进行二次开发或自定义功能,请一定要阅读此文章）
功能介绍配套视频地址:(暂未完成)
Maven 依赖：
<dependency> <groupId>io.github.bailiun</groupId> <artifactId>multiple-versions-coexist</artifactId> <version>1.2.5</version>(若非研究,建议使用最新版,部分老版本有问题存在) </dependency>
✨ 一、组件背景
在企业开发中，我们经常会遇到以下尴尬场景：
- 多个开发人员协同开发某个功能，但 接口版本不一致、沟通不足，导致混乱；
- 项目因为要区分 免费版（Low Edition） 与 收费版（Pro Edition） 被迫拆成两份几乎相同的项目；
- 为新客户定制接口版本，却不得不复制控制器和配置；
- 遗留项目庞大且逻辑复杂，想重构但又不敢动原有逻辑。
- 项目Advice（增强） ，Interceptor（拦截器） ，Event-driven mechanism（事件驱动机制） ，Hook（钩子函数） ，AOP切面实现过于繁杂,需求更改创新复杂
- 不同环境不同配置,切换部署部署繁琐
上线中项目部分功能需加急展示但由出bug而不得不通宵吐血
这些痛点都源自一个问题：
如何在 同一个 Spring Boot 项目中 同时管理、隔离、演化多个接口版本？
于是，MultipleVersionsCoexist 应运而生 —— 它是一个轻量级、可扩展的 Spring Boot 组件，用于 统一管理多版本接口的注册、启用、禁用与优先级控制。并且自带更为方便的AOP切面实现。
🚀 二、组件核心特性
1️⃣ 版本接口动态注册
组件在项目启动时自动扫描带有 @CoexistenceVersion 注解的接口 并将其注册到不同版本，主要实现为切换路径前缀（如 /v1/api/...、/v2/api/...）。
2️⃣ 可自由切换版本
- 通过配置文件 (
application.properties) 快速启用或禁用版本； - 若开启“本地文件控制版本开放”功能，可在运行时动态切换无需重启。
3️⃣ 版本白名单与黑名单
通过 multi.version.include 与 multi.version.exclude 精确控制哪些版本可注册，哪些版本被屏蔽。
4️⃣ 注入优先级控制
当同一路径存在多个版本实现时，可以通过 @InterfacePriority 注解来定义优先级：
- 高优先级接口覆盖低优先级；
- 优先级冲突时输出详细冲突信息，帮助开发者快速定位。
5️⃣ 支持多环境策略
自动识别 spring.profiles.active 环境，针对开发、测试、生产环境可加载不同版本策略。
6️⃣ 文件动态控制（实时热更新）
启用 multi.version.file.FileConfiguration=true 后，组件会定时读取本地配置文件，实时刷新可访问版本，无需重启项目。
7️⃣ 版本元信息管理
支持为每个版本定义元信息（作者、描述、启用状态、创建时间、自定义扩展信息），并可通过接口输出。
8️⃣ 优雅的版本分组与展示
VersionInfoList 提供对版本元信息的分组管理与快速查询，可输出启用版本、未启用版本、版本总览等信息。
9️⃣ 可自定义的同步 / 异步逻辑
组件提供 AOP 拦截点，可针对慢操作（如日志、通知）进行异步化处理，提升性能。
🔟 面向分布式与灰度发布的可扩展性
通过版本元数据和优先级机制，可以轻松扩展到：
- Beta 测试环境；
- MVP（最小可行产品）灰度发布；
- 企业版 / 社区版差异化接口管理。
1️⃣1️⃣ 更便捷的AOP切面编程实现
组件提供了一个特殊的抽象父类SynOpeImplementation，只需继承此类，并且在其子类中直接写方法，就能完成AOP的创建。
🧠 三、典型应用场景
| 场景 | 传统做法 | 使用 MultipleVersionsCoexist |
|---|---|---|
| 前后端版本不一致 | 手动改 Controller 路径 | 自动注册多版本路径 |
| 旧接口逻辑难以重构 | 重开新模块或项目 | 使用优先级注入覆盖旧逻辑 |
| 免费版/付费版项目分离 | 两个代码库 | 单项目统一管理多个版本 |
| 不同客户定制化需求 | 拷贝粘贴代码 | 定义版本组并动态启用 |
| 灰度测试 / Beta 发布 | 手动部署不同包 | 本地配置文件动态控制 |
🧩 四、关键组件设计
| 组件类 | 作用 |
|---|---|
DualRequestMappingHandlerMapping | 框架核心，动态注册版本路径、处理优先级与冲突 |
MultiVersionProperties | 控制多版本注册开关、版本名单、最大注入数等 |
MultiVersionFile | 文件控制配置，用于动态刷新版本 |
MultiVersionInfo | 版本信息定义与输出控制 |
VersionMeta | 单个版本的元数据定义 |
VersionInfoList | 自定义版本集合管理类 |
VersionEnvironmentLoader | 多环境版本加载器 |
DynamicFileWatcher | 文件动态监控与缓存刷新 |
SynOpeImplementation | 优化后的AOP实现 |
| 剩余组件类详见组件篇 | 剩余组件类详见组件篇 |
🛠 五、快速开始(建议以组件篇内容为标准)
1. 引入依赖
> <dependency>
> <groupId>io.github.bailiun</groupId>
> <artifactId>multiple-versions-coexist</artifactId>
> <version>1.2.5</version>(若非研究,建议使用最新版,部分老版本有问题存在)
> </dependency>
2. 创建版本控制注解
@CoexistenceVersion(version = "v2")
@RestController
@RequestMapping("/api")
public class V2UserController {
@GetMapping("/user")
public String getUser() {
return "This is v2 user";
}
}
3. 配置文件（application.yml）(application.properties也行)
multi:
version:
properties:
start: true
include: [v1, v2]
exclude: []
max-num: 10
sorting-method: ASC
file:
file-configuration: true
file-path: config/version.txt
file-refresh-time: 5000
📈 六、未来计划(如果我战胜了懒癌...)
- ✅ 支持实时热插拔接口（完全动态注册/注销）
- ✅ 与 Spring Cloud Gateway / Nacos 集成，实现分布式版本网关
- ✅ 更完善的管理界面（Spring Boot Admin 可视化插件）
- ✅ 对于针对某类用户群体而开放特定版本的功能提供
官方(我)的便捷解决方案 - ✅ 异步的Event-driven mechanism（事件驱动机制） ，Hook（钩子函数） 实现
📜 七、结语
MultipleVersionsCoexist 并不是一个庞大的框架，而是一个让项目“更优雅地进化”的小工具。 它的核心目标，是让开发者在面对 复杂版本共存、接口演化、环境差异化部署 时，不再感到无从下手。
无论你是在参与 Beta 测试、MVP 快速迭代、还是维护一个庞大的企业系统， 都可以通过它让接口版本管理变得简单、有序、可靠。
🌍 项目地址
🔗 GitHub：github.com/bailiun/Spr… 📦 Maven Central：搜索 multiple-versions-coexist
