# java-executor-janino

**Repository Path**: chenhonghua/java-executor-janino

## Basic Information

- **Project Name**: java-executor-janino
- **Description**: 可动态执行JAVA代码函数代码块的执行器。
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-17
- **Last Updated**: 2026-03-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Janino Executor

基于 [Janino](https://janino-compiler.github.io/) 的轻量级 Java 代码动态执行器。

## 简介

Janino Executor 是一个简单的工具库，用于在运行时动态编译和执行 Java 代码片段。它提供了安全的代码执行环境，支持白名单和黑名单机制来控制代码访问权限。

## 特性

- ✅ 动态编译和执行 Java 代码
- ✅ 支持自定义函数定义
- ✅ 参数类型安全
- ✅ Import 白名单控制
- ✅ 类加载黑名单限制
- ✅ 简洁易用的 API

## 依赖

本项目依赖 Janino 3.1.12：

```xml
<dependency>
    <groupId>org.codehaus.janino</groupId>
    <artifactId>janino</artifactId>
    <version>3.1.12</version>
</dependency>
```

## 快速开始

### 1. 基本使用

```java
import com.chenhonghua.janino.executor.Executor;
import com.chenhonghua.janino.executor.Manager;
import com.chenhonghua.janino.executor.Arg;

// 定义一个简单的函数
Manager.addMethod(
    "add",                              // 函数名
    int.class,                          // 返回值类型
    new Arg<?>[]{                       // 参数列表
        new Arg<>("a", int.class),
        new Arg<>("b", int.class)
    },
    """
    return a + b;                       // 函数体
    """
);

// 调用函数
Object result = Executor.invoke("add", 10, 20);
System.out.println(result);  // 输出：30
```

### 2. 复杂示例

```java
// 定义一个计算函数
Manager.addMethod(
    "calculate",
    double.class,
    new Arg<?>[]{
        new Arg<>("x", double.class),
        new Arg<>("y", double.class)
    },
    """
    import java.lang.Math;
    
    if (x > y) {
        return Math.sqrt(x - y);
    } else {
        return Math.pow(x + y, 2);
    }
    """
);

// 调用
Object result1 = Executor.invoke("calculate", 25.0, 9.0);  // 输出：4.0
Object result2 = Executor.invoke("calculate", 3.0, 5.0);   // 输出：64.0
```

### 3. 使用对象类型

```java
// 字符串处理函数
Manager.addMethod(
    "concat",
    String.class,
    new Arg<?>[]{
        new Arg<>("str1", String.class),
        new Arg<>("str2", String.class)
    },
    """
    return str1.toUpperCase() + "-" + str2.toLowerCase();
    """
);

Object result = Executor.invoke("concat", "Hello", "WORLD");
System.out.println(result);  // 输出：HELLO-world
```

## API 说明

### Manager 类

管理函数的注册和查询。

#### `addMethod(String methodName, Class<?> returnType, Arg<?>[] args, String code)`

添加一个自定义函数。

- **methodName**: 函数名称
- **returnType**: 返回值类型（Class 对象）
- **args**: 参数数组，每个参数使用 `Arg<T>` 定义
- **code**: 函数体代码

#### `existMethod(String methodName)`

检查函数是否已注册。

- **methodName**: 函数名称
- **返回值**: 存在返回 `true`，否则返回 `false`

#### `getMethod(String methodName)`

获取已注册的函数对象。

- **methodName**: 函数名称
- **返回值**: Method 对象，如果不存在则返回 `null`

### Executor 类

执行已定义的函数。

#### `invoke(String method, Object... args)`

调用指定的函数。

- **method**: 函数名称
- **args**: 函数参数
- **返回值**: 函数执行结果
- **异常**: 如果函数不存在或执行出错会抛出异常

### Arg 类

定义函数参数的辅助类。

```java
public record Arg<T>(String name, Class<T> type)
```

- **name**: 参数名称（必须与代码中使用的变量名一致）
- **type**: 参数类型

## 安全控制

### Import 白名单

通过 `Constant.ALLOWED_IMPORTS` 控制允许导入的包或类：

```java
// 设置允许的 import
Constant.ALLOWED_IMPORTS = new String[]{
    "java.lang.",
    "java.util.",
    "java.math."
};
```

未在白名单中的 import 会被拒绝，抛出 `SecurityException`。

### 类加载黑名单

通过 `Constant.BLACK_CLASSES` 禁止加载特定的类：

```java
// 添加禁止加载的类
Constant.BLACK_CLASSES.add("java.lang.Runtime");
Constant.BLACK_CLASSES.add("java.lang.System");
```

被加入黑名单的类无法在执行代码中使用。

## 注意事项

1. **参数名称匹配**：`Arg` 中定义的参数名称必须与代码中使用的变量名完全一致
2. **类型安全**：传入的参数类型必须与定义的参数类型兼容
3. **性能考虑**：函数首次执行时会进行编译，后续调用会使用缓存的执行器
4. **异常处理**：代码执行过程中的异常会直接抛出，建议在外层捕获处理
5. **线程安全**：当前实现未做特殊的线程同步处理，多线程环境下使用需注意

## 完整示例

```java
import com.chenhonghua.janino.executor.*;

public class Demo {
    public static void main(String[] args) {
        try {
            // 配置安全策略
            Constant.ALLOWED_IMPORTS = new String[]{
                "java.lang.",
                "java.util.",
                "java.math.BigDecimal"
            };
            
            // 定义多个函数
            Manager.addMethod(
                "sum",
                int.class,
                new Arg<?>[]{new Arg<>("nums", int[].class)},
                """
                int total = 0;
                for (int num : nums) {
                    total += num;
                }
                return total;
                """
            );
            
            Manager.addMethod(
                "greet",
                String.class,
                new Arg<?>[]{new Arg<>("name", String.class)},
                """
                return "Hello, " + name + "!";
                """
            );
            
            // 调用函数
            System.out.println(Executor.invoke("sum", new int[]{1, 2, 3, 4, 5}));  // 15
            System.out.println(Executor.invoke("greet", "World"));  // Hello, World!
            
            // 检查函数是否存在
            System.out.println(Manager.existMethod("sum"));  // true
            
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

## 许可证

Apache License 2.0

## 版本信息

- **当前版本**: 3.1.12.1
- **Janino 版本**: 3.1.12