GitHub 项目地址
https://github.com/BugSymphony/seamless-appserver-sidecar

如果该项目对你有帮助，欢迎 Star ⭐ 支持项目发展

---

Seamless AppServer Sidecar

一、项目概览

1. Sidecar 的定位

Seamless AppServer Sidecar 是一个面向 Java 应用运行时 的轻量级伴生框架（Runtime Sidecar Framework）。

它以 “不侵入业务代码” 为前提，在宿主应用内部持续注入可插拔的治理能力，为传统与现代 Java 应用服务器提供统一的运行时扩展基础设施。

Sidecar 关注的是 运行时治理，而非业务功能本身，典型能力包括：

• 流量治理
• 安全防护
• 审计与观测
• 策略执行
• 运行时扩展

2. 与宿主应用的关系

Sidecar 不是：

• 独立部署的微服务
• 外置的反向代理
• Java Agent 或字节码增强工具

Sidecar 的真实形态是：

• 运行在 宿主应用同一 JVM 中
• 拥有 独立的 Sidecar Runtime
• 通过 受控上下文桥接 与宿主运行时协作

核心约束关系如下：

• 宿主应用对 Sidecar 的感知最小化
• Sidecar 不反向依赖任何业务实现
• 插件不直接侵入或耦合业务代码

宿主应用始终是 Sidecar 的“被服务对象”，而不是“被改造对象”。

---

二、设计原则

Sidecar 的设计并非围绕单一功能点，而是围绕一个核心问题进行系统性抽象：

如何以最低侵入性、最高可演进性，为既有 Java 应用服务器持续注入治理能力

以下原则是 Sidecar 架构设计、类加载模型与插件机制的最高约束。

1. 运行时优先原则

Sidecar 首先被定义为一个 运行时系统（Runtime System），而非工具库或框架集合。

• 所有能力运行在明确的 Runtime 边界内
• 插件、能力、端点均具备可管理的生命周期
• 不依赖编译期织入、字节码增强或 JVM 启动参数

2. 零侵入宿主原则

Sidecar 对宿主应用保持严格的非侵入性：

• 不要求修改业务代码
• 不要求在业务 pom.xml 中引入依赖
• 不要求配置 Java Agent 或 JVM 参数

Sidecar 通过 独立 Runtime + 独立 ClassLoader 与宿主协作，而非融合。

3. 隔离优先设计

隔离是架构前提，而非优化手段。

• 插件级 ClassLoader 隔离
• 插件之间无隐式类可见性
• 插件失败不影响 Sidecar 整体
• Sidecar 故障可整体关闭或旁路

隔离维度包括：类、配置、生命周期、失败域。

4. 三层运行时模型

Sidecar 明确采用三层运行时划分：

1. Sidecar Runtime（平台层）
   负责插件发现、装载、生命周期与失败域管理

2. Plugin Runtime（容器层）
   提供插件级隔离、入口管理与上下文绑定

3. Sidecar Forge（能力框架层）
   负责治理能力的装配、注册与激活

5. 显式优于隐式

当前阶段，Sidecar 刻意避免 以下机制：

• ClassPath 扫描
• SPI 自动装配
• 隐式自动配置

插件能力必须通过 显式 Java 代码 注册：

SidecarForge.run(context, registry -> {
    registry.register(EndpointConfig.class);
});

该策略换取：

• 更清晰的依赖边界
• 更可控的启动顺序
• 更低的调试与理解成本

6. 能力为中心

Sidecar 并不试图成为新的应用开发框架，而是一个 治理能力承载平台。

插件的价值体现在：

• 提供了哪些治理能力
• 暴露了哪些运行时接口

而非：

• 实现了多少业务逻辑
• 封装了多少通用工具

7. 失败域收敛

Sidecar 明确约束失败传播范围：

• 插件失败仅影响自身
• 插件启动失败不阻塞其他插件
• 插件异常不传播至宿主应用

---

三、总体架构

Seamless AppServer Sidecar 是一个运行在宿主应用内部、但在逻辑与生命周期上高度隔离的 运行时治理平台。

它并非传统意义上的：

• 类库（Library）
• 应用框架（Framework）
• Java Agent（字节码代理）

1. 运行时模型

Sidecar 的整体设计可归约为三类 Runtime 的协作：

设计要点：

• Sidecar 只管理 Runtime，不直接管理业务逻辑
• 插件是 Runtime 的宿主，而非能力的直接实现者
• 所有能力都运行在明确的生命周期与失败边界内

2. 类加载层级与包导入机制

核心规则：插件默认不可见业务应用

在默认模型下：

• PluginClassLoader 不以 WebAppClassLoader 为 parent
• 插件无法直接访问业务应用类
• 插件仅可访问：
  • JDK 类
  • 应用服务器公共类
  • Sidecar Runtime API

该设计从根本上避免插件与业务代码形成隐式耦合。

包导入机制（PluginResolver 的引入）

完全隔离在真实场景中会带来一个现实问题：

插件如何在保持隔离前提下，受控地访问宿主运行时类型空间？

例如：

• 获取 Spring 容器元信息
• 感知 Web 框架运行状态

为此，Sidecar 引入 PluginResolver + Import-Package 机制，其思想类似于 OSGi：

• 插件显式声明需要导入的包
• Sidecar 在受控边界内完成类型桥接
• 不破坏默认隔离语义

---

四、安装与部署

• 安装与部署教程

五、插件开发指南

• 插件开发文档

---

六、版本状态

• 当前版本：0.1-SNAPSHOT
• 状态：预览 / 实验性

当前阶段说明

• 核心架构与插件模型已基本确立
• API 与扩展点仍可能发生调整
• 适用于：
  • 技术预研
  • 架构验证
  • 插件与治理机制探索

当前阶段不建议用于生产环境。

---

项目地址

GitHub：

https://github.com/BugSymphony/seamless-appserver-sidecar

如果这个项目对你有所帮助，欢迎：

• ⭐ Star 支持项目
• 🐞 提交 Issue 反馈问题
• 🔧 提交 PR 一起参与建设

开源项目需要社区力量共同成长。