{"id":13458746,"url":"https://github.com/alibaba/jvm-sandbox","last_synced_at":"2025-05-13T17:10:37.841Z","repository":{"id":41055391,"uuid":"99183902","full_name":"alibaba/jvm-sandbox","owner":"alibaba","description":"Real - time non-invasive AOP framework container based on JVM","archived":false,"fork":false,"pushed_at":"2024-10-03T17:09:13.000Z","size":1874,"stargazers_count":6875,"open_issues_count":37,"forks_count":1576,"subscribers_count":379,"default_branch":"master","last_synced_at":"2025-04-24T01:54:24.653Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alibaba.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING.LESSER","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-08-03T02:55:31.000Z","updated_at":"2025-04-22T09:19:32.000Z","dependencies_parsed_at":"2024-06-18T23:01:14.997Z","dependency_job_id":"a67144c5-9373-4242-b35f-67e3490ff16a","html_url":"https://github.com/alibaba/jvm-sandbox","commit_stats":{"total_commits":344,"total_committers":40,"mean_commits":8.6,"dds":0.7412790697674418,"last_synced_commit":"c01c28ab5d7d97a64071a2aca261804c47a5347e"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alibaba%2Fjvm-sandbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alibaba%2Fjvm-sandbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alibaba%2Fjvm-sandbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alibaba%2Fjvm-sandbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alibaba","download_url":"https://codeload.github.com/alibaba/jvm-sandbox/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253990468,"owners_count":21995774,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T09:00:56.538Z","updated_at":"2025-05-13T17:10:32.829Z","avatar_url":"https://github.com/alibaba.png","language":"Java","funding_links":[],"categories":["Java","Java (78)","Java (504)","AOP"],"sub_categories":[],"readme":"# ![BANNER](https://github.com/alibaba/jvm-sandbox/wiki/img/BANNER.png)\n\n[![Build Status](https://travis-ci.org/alibaba/jvm-sandbox.svg?branch=master)](https://travis-ci.org/alibaba/jvm-sandbox)\n[![codecov](https://codecov.io/gh/alibaba/jvm-sandbox/branch/master/graph/badge.svg)](https://codecov.io/gh/alibaba/jvm-sandbox)\n[![Average time to resolve an issue](http://isitmaintained.com/badge/resolution/alibaba/jvm-sandbox.svg)](http://isitmaintained.com/project/alibaba/jvm-sandbox \"Average time to resolve an issue\")\n[![Percentage of issues still open](http://isitmaintained.com/badge/open/alibaba/jvm-sandbox.svg)](http://isitmaintained.com/project/alibaba/jvm-sandbox \"Percentage of issues still open\")\n\n\u003e JVM沙箱容器，一种JVM的非侵入式运行期AOP解决方案\u003cbr/\u003e\n\u003e Real - time non-invasive AOP framework container based on JVM\n\n## 目标群体\n\n- [BTRACE](https://github.com/btraceio/btrace)好强大，也曾技痒想做一个更便捷、更适合自己的问题定位工具，既可支持线上链路监控排查，也可支持单机版问题定位。\n- 有时候突然一个问题反馈上来，需要入参才能完成定位，但恰恰没有任何日志，甚至出现在别人的代码里，好想开发一个工具可以根据需要动态添加日志，最好还能按照业务ID进行过滤。\n- 系统间的异常模拟可以使用的工具很多，可是系统内的异常模拟怎么办，加开关或是用AOP在开发系统中实现，好想开发一个更优雅的异常模拟工具，既能模拟系统间的异常，又能模拟系统内的异常。\n- 好想获取行调用链路数据，可以用它识别场景、覆盖率统计等等，覆盖率统计工具不能原生支持，统计链路数据不准确。想自己开发一个工具获取行链路数据。\n- 我想开发录制回放、故障模拟、动态日志、行链路获取等等工具，就算我开发完成了，这些工具底层实现原理相同，同时使用，要怎么消除这些工具之间的影响，怎么保证这些工具动态加载，怎么保证动态加载/卸载之后不会影响其他工具，怎么保证在工具有问题的时候，快速消除影响，代码还原\n\n如果你有以上研发诉求，那么你就是JVM-SANDBOX(以下简称沙箱容器)的潜在客户。沙箱容器提供\n\n1. 动态增强类你所指定的类，获取你想要的参数和行信息甚至改变方法执行\n2. 动态可插拔容器框架\n\n## 项目简介\n\n**JVM-SANDBOX（沙箱）实现了一种在不重启、不侵入目标JVM应用的AOP解决方案。**\n\n### 沙箱的特性\n\n1. `无侵入`：目标应用无需重启也无需感知沙箱的存在\n2. `类隔离`：沙箱以及沙箱的模块不会和目标应用的类相互干扰\n3. `可插拔`：沙箱以及沙箱的模块可以随时加载和卸载，不会在目标应用留下痕迹\n4. `多租户`：目标应用可以同时挂载不同租户下的沙箱并独立控制\n5. `高兼容`：支持JDK[6,11]\n\n### 沙箱常见应用场景\n\n- 线上故障定位\n- 线上系统流控\n- 线上故障模拟\n- 方法请求录制和结果回放\n- 动态日志打印\n- 安全信息监测和脱敏\n\n*JVM-SANDBOX还能帮助你做很多很多，取决于你的脑洞有多大了。*\n\n### 实时无侵入AOP框架\n\n在常见的AOP框架实现方案中，有静态编织和动态编织两种。\n\n1. **静态编织**：静态编织发生在字节码生成时根据一定框架的规则提前将AOP字节码插入到目标类和方法中，实现AOP；\n2. **动态编织**：动态编织则允许在JVM运行过程中完成指定方法的AOP字节码增强.常见的动态编织方案大多采用重命名原有方法，再新建一个同签名的方法来做代理的工作模式来完成AOP的功能(常见的实现方案如CgLib)，但这种方式存在一些应用边界：\n   - **侵入性**：对被代理的目标类需要进行侵入式改造。比如：在Spring中必须是托管于Spring容器中的Bean\n   - **固化性**：目标代理方法在启动之后即固化，无法重新对一个已有方法进行AOP增强\n \n要解决`无侵入`的特性需要AOP框架具备 **在运行时完成目标方法的增强和替换**。在JDK的规范中运行期重定义一个类必须准循以下原则\n  1. 不允许新增、修改和删除成员变量\n  2. 不允许新增和删除方法\n  3. 不允许修改方法签名\n\nJVM-SANDBOX属于基于Instrumentation的动态编织类的AOP框架，**通过精心构造了字节码增强逻辑，使得沙箱的模块能在不违反JDK约束情况下实现对目标应用方法的`无侵入`运行时AOP拦截**。\n\n## 核心原理\n\n### 事件驱动\n\n在沙箱的世界观中，任何一个Java方法的调用都可以分解为`BEFORE`、`RETURN`和`THROWS`三个环节，由此在三个环节上引申出对应环节的事件探测和流程控制机制。\n\n```java\n// BEFORE\ntry {\n\n   /*\n    * do something...\n    */\n\n    // RETURN\n    return;\n\n} catch (Throwable cause) {\n    // THROWS\n}\n```\n\n基于`BEFORE`、`RETURN`和`THROWS`三个环节事件分离，沙箱的模块可以完成很多类AOP的操作。\n\n1. 可以感知和改变方法调用的入参\n2. 可以感知和改变方法调用返回值和抛出的异常\n3. 可以改变方法执行的流程\n    - 在方法体执行之前直接返回自定义结果对象，原有方法代码将不会被执行\n    - 在方法体返回之前重新构造新的结果对象，甚至可以改变为抛出异常\n    - 在方法体抛出异常之后重新抛出新的异常，甚至可以改变为正常返回\n\n### 类隔离策略\n\n沙箱通过自定义的SandboxClassLoader破坏了双亲委派的约定，实现了和目标应用的类隔离。所以不用担心加载沙箱会引起应用的类污染、冲突。各模块之间类通过ModuleJarClassLoader实现了各自的独立，达到模块之间、模块和沙箱之间、模块和应用之间互不干扰。\n\n![jvm-sandbox-classloader](https://github.com/alibaba/jvm-sandbox/wiki/img/jvm-sandbox-classloader.png)\n\n### 类增强策略\n\n沙箱通过在BootstrapClassLoader中埋藏的Spy类完成目标类和沙箱内核的通讯\n\n![jvm-sandbox-enhance-class](https://github.com/alibaba/jvm-sandbox/wiki/img/jvm-sandbox-enhance-class.jpg)\n\n### 整体架构\n\n![jvm-sandbox-architecture](https://github.com/alibaba/jvm-sandbox/wiki/img/jvm-sandbox-architecture.png)\n\n## 快速安装\n- **下载并安装或自行打包**\n\n  ```shell\n  # 下载最新版本的JVM-SANDBOX，oss已到期，或者oss链接不可访问时，可选择自行打包\n  wget https://ompc.oss-cn-hangzhou.aliyuncs.com/jvm-sandbox/release/sandbox-1.3.3-bin.zip\n\n  # 解压\n  unzip sandbox-1.3.3-bin.zip\n  ```\n  ```shell\n  #自行打包\n   cd bin\n   ./sandbox-packages.sh\n   #target路径下有多种构建件类型，选择一个合适的使用\n   cd ../target\n  ```\n\n\n- **挂载目标应用**\n\n  ```shell\n  # 进入沙箱执行脚本\n  cd sandbox/bin\n\n  # 目标JVM进程33342\n  ./sandbox.sh -p 33342\n  ```\n\n- **挂载成功后会提示**\n\n  ```shell\n  ./sandbox.sh -p 33342\n             NAMESPACE : default\n               VERSION : 1.2.0\n                  MODE : ATTACH\n           SERVER_ADDR : 0.0.0.0\n           SERVER_PORT : 55756\n        UNSAFE_SUPPORT : ENABLE\n          SANDBOX_HOME : /Users/vlinux/opt/sandbox\n     SYSTEM_MODULE_LIB : /Users/vlinux/opt/sandbox/module\n       USER_MODULE_LIB : ~/.sandbox-module;\n   SYSTEM_PROVIDER_LIB : /Users/vlinux/opt/sandbox/provider\n    EVENT_POOL_SUPPORT : DISABLE\n  ```\n\n- **卸载沙箱**\n\n  ```shell\n  ./sandbox.sh -p 33342 -S\n  jvm-sandbox[default] shutdown finished.\n  ```\n\n## 项目构建\n\n当你修改了sandbox的代码后，想打包成自己需要的发行版，可以执行以下命令\n\n\u003e 脚本执行目录默认为项目主目录，后续不在另外说明\n\n```shell\ncd bin\n./sandbox-package.sh\n```\n\n命令执行成功后会在target目录下生成`sandbox-\u003c版本号\u003e-bin.zip`文件\n\n### 构建注意事项\n\n1. 必须用JDK1.8进行构建，工程自身和maven插件中使用了tools.jar\n2. 必须在Linux/Mac/Unix下进行构建，有部分测试用例没有考虑好$USER_HOME的目录路径在windows下的特殊性，会导致测试用例跑不通过。\n\n### 修改sandbox版本号\n\nsandbox的版本号需要修改所有的pom文件以及`.//sandbox-core/src/main/resources/com/alibaba/jvm/sandbox/version`，这里有一个脚本方便执行\n\n```shell\ncd bin\n./set-version.sh -s 1.4.0\n```\n\n脚本第一个参数是`[s|r]`\n- **s** : SNAPSHOT版，会自动在版本号后边追加`-SNAPSHOT`\n- **r** : 正式版\n\n### 本地仓库安装api包\n\n如果本次你修改了sandbox-api、sandbox-common-api、sandbox-module-starter等本应该发布到中央仓库的包，但你需要本地测试验证，可以执行以下命令\n\n```shell\nmvn clean install\n```\n\n以下四个包将会安装到本地manven仓库\n- sandbox\n- sandbox-api\n- sandbox-common-api\n- sandbox-module-starter\n- sandbox-provider-api\n\n## 项目背景\n\n2014年[GREYS](https://github.com/oldmanpushcart/greys-anatomy)第一版正式发布，一路看着他从无到有，并不断优化强大，感慨羡慕之余，也在想GREYS是不是只能做问题定位。\n\n2015年开始根据GREYS的底层代码完成了人生的第一个字节码增强工具——动态日志。之后又萌生了将其拆解成*录制回放*、*故障模拟*等工具的想法。扪心自问，我是想以一人一个团队的力量建立大而全的工具平台，还是做一个底层中台，让每一位技术人员都可以在它的基础上快速的实现业务功能。我选择了后者。\n\n## 相关文档\n\n- **[WIKI](https://github.com/alibaba/jvm-sandbox/wiki/Home)**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falibaba%2Fjvm-sandbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falibaba%2Fjvm-sandbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falibaba%2Fjvm-sandbox/lists"}