refer and add koupleless Samples (#1282)

* Update index.md * add refer to koupleless * Update index.md * Update index.md * Update index.md * Update index.md * Update index.md * Update index.md --------- Co-authored-by: youji.zzl <[email protected]> Co-authored-by: Marco <[email protected]>
sofastack · Oct 14, 2024 · 20dc55a · 20dc55a
1 parent b82b724
commit 20dc55a
Show file tree

Hide file tree

Showing 4 changed files with 38 additions and 34 deletions.
diff --git a/content/en/projects/sofa-boot/sofa-ark-readme/index.md b/content/en/projects/sofa-boot/sofa-ark-readme/index.md
@@ -4,12 +4,13 @@ title: "Introduction to SOFAArk"
 aliases: "/sofa-boot/docs/sofa-ark-readme"
 ---
 
-
 ## Product description
 SOFAArk is a light-weight，java based classloader isolation framework 
 open sourced by Ant Financial. Based on  [Fat Jar](https://docs.spring.io/spring-boot/docs/current/reference/html/executable-jar.html#executable-jar-jar-file-structure) technology, the container can pack simple single-module Java applications or Spring Boot applications into a self-contained executable Fat Jar, known as an Ark package. When the `java -jar` command is used to start an Ark package embedded with the SOFAArk class isolation container, the SOFAArk container will start, and it then starts each Ark plugin and application.
+If you want to merge multi app into one jvm, please go and refer to [koupleless](https://github.com/koupleless/koupleless) which based on SOFAArk; if you want to just isolate class by classLoader then you can read docs in this site, and focus on sofaArk Plugin.
 
 ## Background
+
 In Java world, dependency is always a problem, and can cause various errors, such as `LinkageError`, `NoSuchMethodError` etc. There are many ways to solve the dependency problems, the Spring Boot's way is using a dependency management to manage all the dependencies, make sure that all the dependencies in the dependency management will not conflict and can work pretty well. This is quite a simple and efficient way, it can cover most scenario, but there is some exceptions.
 
 For example, there is a project that need protobuf version 2 and protobuf version 3, and because protobuf version 3 is not compatible with version 2, so the project can not simply upgrade the protobuf to version 3 to solve the problem. There is same problem for hessian version 3 and version 4.
@@ -22,7 +23,9 @@ So this is the origin of SOFAArk, it's goal is to use a light-weight classloader
 
 There are three concepts in SOFAArk: `Ark Container`, `Ark-Plugin` and `Ark-Biz`; they are organized as what the following graph shows:
 
-![image.png | center | 1310x1178](https://cdn.yuque.com/lark/2018/png/590/1523868989241-f50695ed-dca0-4bf7-a6a9-afe07c2ade76.png)
+<div style="text-align: center;">
+    <img align="center" width="1310" height="1178" src="https://cdn.yuque.com/lark/2018/png/590/1523868989241-f50695ed-dca0-4bf7-a6a9-afe07c2ade76.png">
+</div>
 
 First of all, we explain what roles these concepts play;
 
@@ -36,13 +39,10 @@ In runtime, `Ark Container` would automatically recognize `Ark-Plugin` and `Ark-
 
 isolated well. For example, if a project has two dependencies of A and B, but A depends on C (version = 0.1) and B depends on C (version = 0.2), so conflicts maybe emerge.
 
-
 ## Scenario
+
 SOFAArk was originally designed to resolve package conflicts, but when and how can you use SOFAArk? Assume that a project needs to introduce two third-party packages A and B; package A needs to depend on package C with the version number 0.1, whereas package B needs to depend on package C with the version number 0.2; the two versions of package C are incompatible, illustrated as follows:
 
 ![conflict](https://cdn.yuque.com/lark/2018/png/590/1523868150329-41ea3982-4783-49b0-a1e6-ffffddbe0886.png)
 
 You can use SOFAArk to resolve the dependency conflict in this scenario. You only need to pack package A and package C with the version number 0.1 into an Ark plugin, and then make the application engineering introduce the plugin to depend on.
-
-
-
diff --git a/content/zh/projects/sofa-boot/sofa-ark-class-loader-delegation/index.md b/content/zh/projects/sofa-boot/sofa-ark-class-loader-delegation/index.md
@@ -65,8 +65,8 @@ SOFAArk 支持的场景主要分为两类：
 
 ### 对比与总结
 
-||依赖缺失排查成本|修复成本|模块改造成本|维护成本|
-|-|-|-|-|-|
+|委托加载类型|依赖缺失排查成本|修复成本|模块改造成本|维护成本|
+|----|----|----|----|----|
 |强制加载|类转换失败或类查找失败，成本中|更新 plugin，发布基座，高|低|高|
 |自定义委托加载 |类转换失败或类查找失败，成本中|更新模块依赖，如果基座依赖不足，需要更新基座并发布，中|高|低|
 |自定义委托加载 + 基座预置依赖 + 模块自动瘦身|类转换失败或类查找失败，成本中|更新模块依赖，设置为provided，低|低|低|

diff --git a/content/zh/projects/sofa-boot/sofa-ark-migration-guide/index.md b/content/zh/projects/sofa-boot/sofa-ark-migration-guide/index.md
@@ -3,11 +3,13 @@ title: "SOFAArk2.0 升级"
 aliases: "/sofa-boot/docs/sofa-ark-migration-guide"
 ---
 
-# 背景
+## 背景
 
 SOFAArk 框架包含有三个概念，Ark Container, Ark Plugin 和 Ark Biz; 运行时逻辑结构图如下：
 
-![image.png | center | 1310x1178](https://cdn.yuque.com/lark/2018/png/590/1523868989241-f50695ed-dca0-4bf7-a6a9-afe07c2ade76.png)
+<div style="text-align: center;">
+    <img align="center" width="1310" height="1178" src="https://cdn.yuque.com/lark/2018/png/590/1523868989241-f50695ed-dca0-4bf7-a6a9-afe07c2ade76.png">
+</div>
 
 每次应用启动时，首先运行 Ark 包，Ark Container 优先启动，容器自动解析 Ark 包中含有的 Ark Plugin 和 Ark Biz，并读取他们的配置信息，构建类和资源的加载索引表；然后使用独立的 ClassLoader 加载并按优先级配置依次启动；需要指出的是，Ark Plugin 优先 Ark Biz 被加载启动。
 详细介绍可阅读： [SOFAArk 介绍](https://www.sofastack.tech/projects/sofa-boot/sofa-ark-readme/)
@@ -18,19 +20,19 @@ SOFAArk 框架包含有三个概念，Ark Container, Ark Plugin 和 Ark Biz; 运
 
 详细介绍可阅读：[Ark 容器类加载机制](https://www.sofastack.tech/projects/sofa-boot/sofa-ark-classloader/)
 
-## 问题一
+### 问题一
 
 由于Ark Plugin的存在，插件在依赖层面的强管控，造成了一些问题
 - 业务使用的依赖是被插件管控导出的，但是插件管控导出的版本与业务实际期望的版本不符（比如插件管控的版本是 1.0，而业务需要的是 2.0）。
 - 插件对于依赖的强管控，直接堵住了业务扩展插件能力的路；也存在部分依赖，当业务引入时会直接报错（其package 被导出了，但是依赖不在插件中），那么对于业务来说就只能等框架发版解决。
 - 业务接入成本，学习成本较高，问题排查困难，需要非常熟悉Ark类加载机制。
 - 由于管控依赖的增长，Ark Plugin难以持续维护
 
-## 问题二
+### 问题二
 
 另外，由于Ark Container先于master biz启动，master biz的启动入口和springboot/sofaboot不一致，导致Ark master biz的的启动在研发运维中需要定制镜像，定制启动入口，造成研发运维困难。
 
-# SOFAArk2.0
+## SOFAArk2.0
 
 针对这些问题，我们尝试从框架层面去优化三层结构，沉淀出了SOFAArk2.0方案，整体优化思路和原则是 Ark Master Biz保持和原生springboot/sofaboot保持一致，弱化复杂的Ark Plugin类管控机制，将Ark Plugin与master biz合并。
 
@@ -39,9 +41,9 @@ SOFAArk2.0方案整体优化点：
 - Ark master biz和原生的springboot/sofaboot应用启动方式，类加载方式保持一致；
 - 优化Ark Biz启动速度；
 
-# 升级方式
+### 升级方式
 
-## 版本升级
+#### 版本升级
 
 SOFAArk版本号第一位为大版本号，当为1.x.x时为SOFAArk1.0版，当为2.x.x时是SOFAArk2.0版，当前2.0版本已正式release，[Release-Notes](https://github.com/sofastack/sofa-ark/releases/tag/v2.0.0)
 
@@ -59,9 +61,9 @@ SOFAArk版本号第一位为大版本号，当为1.x.x时为SOFAArk1.0版，当
 </properties>
 ```
 
-## 打包插件
+#### 打包插件
 
-在SOFAArk1.0中使用sofa-ark-maven-plugin打包，在SOFAArk2.0中采用spring-boot原生打包插件spring-boot-maven-plugin打包
+对于基座来说，在SOFAArk1.0中使用sofa-ark-maven-plugin打包，在SOFAArk2.0中采用spring-boot原生打包插件spring-boot-maven-plugin打包对于模块来说，则继续使用 sofa-ark-maven-plugin 来打包。
 
 ```xml
 <build>
@@ -120,24 +122,20 @@ SOFAArk版本号第一位为大版本号，当为1.x.x时为SOFAArk1.0版，当
 </build>
 ```
 
-## 运行启动
+### 运行启动
 
-### 方式一：IDEA启动
+#### 方式一：IDEA启动
 
 本地启动需要加上启动参数
 
 > -Dsofa.ark.embed.enable=true -Dcom.alipay.sofa.ark.master.biz=${bizName}
 
-### 方式二：命令行启动
+#### 方式二：命令行启动
 
 Ark包是可执行Jar，可直接使用Java -jar的方式启动，先使用 mvn clean package 进行打包，打包得到 ${bizName}-${bizVersion}-ark-biz.jar，命令行启动
 
 > java -jar -Dsofa.ark.embed.enable=true -Dcom.alipay.sofa.ark.master.biz=${bizName} ${bizName}-${bizVersion}-ark-biz.jar
 
-## 示例工程
-
-[SOFAArk1.0示例工程](https://github.com/sofastack-guides/sofa-ark-guides/tree/master/sample-ark-springboot) ：SOFAArk1.0接入方式
-
-[SOFAArk2.0示例工程](https://github.com/sofastack-guides/sofa-ark-spring-guides) ：SOFAArk2.0接入方式
-
+### 示例工程
 
+[SOFAArk2.0示例工程](https://github.com/sofastack-guides/sofa-ark-guides/tree/master/sample-ark-springboot) ：SOFAArk2.0接入方式。另外 SOFAArk 作为 [Koupleless](https://github.com/koupleless/koupleless) 类隔离组件，也可以查看 [Koupleless 合并部署的 samples](https://github.com/koupleless/samples/blob/main/springboot-samples/web/tomcat/README-zh_CN.md)
diff --git a/content/zh/projects/sofa-boot/sofa-ark-readme/index.md b/content/zh/projects/sofa-boot/sofa-ark-readme/index.md
@@ -3,7 +3,7 @@ title: "SOFAArk 介绍"
 aliases: "/sofa-boot/docs/sofa-ark-readme"
 ---
 
-SOFAArk 是一款基于 Java 实现的轻量级类隔离容器，主要提供类隔离和应用(模块)合并部署能力，由蚂蚁金服公司开源贡献；
+SOFAArk 是一款基于 Java 实现的轻量级类隔离容器，主要提供类隔离和应用(模块)合并部署能力，由蚂蚁金服公司开源贡献，目前已经基于 SOFAArk 提供了模块化合并部署的完整解决方案 [koupleless](https://github.com/koupleless/koupleless), 如果想要使用合并部署能力，建议查看 [Koupleless 使用文档](https://koupleless.io/)，如果只是想要使用的类隔离能力可以查看 SOFAArk Plugin 能力，继续查看本站点相关文档；
 
 在大型软件开发过程中，通常会推荐底层功能插件化，业务功能模块化的开发模式，以期达到低耦合、高内聚、功能复用的优点。基于此，SOFAArk 提供了一套较为规范化的插件化、模块化的开发方案，产品能力主要包括：
 
@@ -16,7 +16,9 @@ SOFAArk 是一款基于 Java 实现的轻量级类隔离容器，主要提供类
 基于以上能力，SOFAArk 可以帮助解决依赖包冲突、多应用(模块)合并部署等场景问题。
 
 ## 场景
-#### 包冲突
+
+### 包冲突
+
 日常使用 Java 开发，常常会遇到包依赖冲突的问题，尤其当应用变得臃肿庞大，包冲突的问题也会变得更加棘手，导致各种各样的报错，例如 `LinkageError`, `NoSuchMethodError` 等；实际开发中，可以采用多种方法来解决包冲突问题，比较常见的是类似 Spring Boot 的做法，统一管理应用所有依赖包的版本，保证这些三方包不存在依赖冲突；这种做法只能有效避免包冲突问题，不能根本上解决包冲突的问题；如果某个应用的确需要在运行时使用两个相互冲突的包，例如 `protobuf2` 和 `protobuf3`，那么类似 Spring Boot 的做法依然解决不了问题。
 
 为了彻底解决包冲突的问题，需要借助类隔离机制，使用不同的 `ClassLoader` 加载不同版本的三方依赖，进而隔离包冲突问题； `OSGI` 作为业内最出名的类隔离框架，自然是可以被用于解决上述包冲突问题，但是 `OSGI` 框架太过臃肿，功能繁杂；为了解决包冲突问题，引入 `OSGI` 框架，有牛刀杀鸡之嫌，且反而使工程变得更加复杂，不利于开发；
@@ -29,23 +31,29 @@ SOFAArk 采用轻量级的类隔离方案来解决日常经常遇到的包冲突
 
 此时，即可使用 SOFAArk 解决该依赖冲突问题；只需要把 A 和版本为 0.1 的 C 包一起打包成一个 Ark 插件，然后让应用工程引入该插件依赖即可；
 
-#### 合并部署
+### 合并部署
+
 复杂项目通常需要跨团队协作开发，各自负责不同的组件，而众所周知，协调跨团队合作开发会遇到不少问题；比如各自技术栈不统一导致的依赖冲突，又比如往同一个 Git 仓库提交代码常常导致 merge 冲突。因此，如果能让每个团队将负责的功能组件当成一个个单独的应用开发，运行时合并部署，通过统一的编程界面交互，那么将极大的提升开发效率及应用可扩展性。SOFAArk 提出了一种特殊的包结构 -- Ark Biz，用户可以使用 Maven 插件将应用打包成 Biz，允许多 Biz 在 SOFAArk 容器之上合并部署，并通过统一的编程界面交互。
 
-##### 静态合并部署
+#### 静态合并部署
+
 SOFAArk 提供了静态合并部署能力，在开发阶段，应用可以将其他应用打成的 Biz 包通过 Maven 依赖的方式引入，而当自身被打成可执行 Fat Jar 时，可以将其他应用 Biz 包一并打入，启动时，则会根据优先级依次启动各应用。每个 Biz 使用独立的 BizClassLoader 加载，不需要考虑相互依赖冲突问题，Biz 之间则通过 `SofaService/SofaReference` JVM 服务进行交互。
 
-##### 动态合并部署
+#### 动态合并部署
+
 动态合并部署区别于静态合并部署最大的一点是，运行时通过 API 或者配置中心（Zookeeper）来控制 Biz 的部署和卸载。动态合并部署的设计理念图如下：
 
 ![architecture](architecture.png)
 
 无论是静态还是动态合并部署都会有宿主应用（master biz）的概念, 如果 Ark 包只打包了一个 Biz，则该 Biz 默认成为宿主应用；如果 Ark 包打包了多个 Biz 包，需要配置指定宿主应用。宿主应用不允许被卸载，一般而言，宿主应用会作为流量入口的中台系统，具体的服务实现会放在不同的动态 Biz 中，供宿主应用调用。宿主应用可以使用 SOFAArk 提供的客户端 API 实现动态应用的部署和卸载。除了 API, SOFAArk 提供了 Config Plugin，用于对接配置中心（目前支持 Zookeeper），运行时接受动态配置；Config Plugin 会解析下发的配置，控制动态应用的部署和卸载。
 
 ## 原理
+
 SOFAArk 包含三个概念，`Ark Container`, `Ark Plugin` 和 `Ark Biz`; 运行时逻辑结构图如下:
 
-![image.png | center | 1310x1178](https://cdn.yuque.com/lark/2018/png/590/1523868989241-f50695ed-dca0-4bf7-a6a9-afe07c2ade76.png)
+<div style="text-align: center;">
+    <img align="center" width="1310" height="1178" src="https://cdn.yuque.com/lark/2018/png/590/1523868989241-f50695ed-dca0-4bf7-a6a9-afe07c2ade76.png">
+</div>
 
 在介绍这三个概念之前，先介绍上述 `Ark` 包概念；`Ark` 包是满足特定目录格式要求的可运行 `Fat Jar`，使用官方提供的 `Maven` 插件 `sofa-ark-maven-plugin` 可以将**单个或多个应用**打包成标准格式的 `Ark` 包；使用 `java -jar` 命令即可在 SOFAArk 容器之上启动所有应用；`Ark` 包通常包含 `Ark Container`、`Ark Plugin` 和 `Ark Biz`；以下我们针对这三个概念简单做下名词解释：
 
@@ -56,5 +64,3 @@ SOFAArk 包含三个概念，`Ark Container`, `Ark Plugin` 和 `Ark Biz`; 运行
 + `Ark Biz`: Ark 应用模块，满足特定目录格式要求的 `Fat Jar`，使用官方提供的 `Maven` 插件 `sofa-ark-maven-plugin` 可以将工程应用打包成一个标准格式的 `Ark Biz`；`Ark Biz` 是工程应用以及其依赖包的组织单元，包含应用启动所需的所有依赖和配置；一个 Ark 包中可以包含多个 `Ark Biz` 包，按优先级依次启动，Biz 之间通过 JVM 服务交互；
 
 运行 `Ark` 包，`Ark Container` 优先启动，容器自动解析 `Ark` 包中含有的 `Ark Plugin` 和 `Ark Biz`，并读取他们的配置信息，构建类和资源的加载索引表；然后使用独立的 `ClassLoader` 加载并按优先级配置依次启动；需要指出的是，`Ark Plugin` 优先 `Ark Biz` 被加载启动；`Ark Plugin` 之间是双向类索引关系，即可以相互委托对方加载所需的类和资源；`Ark Plugin` 和 `Ark Biz` 是单向类索引关系，即只允许 `Ark Biz` 索引 `Ark Plugin` 加载的类和资源，反之则不允许。
-
-