# usher-groovy-flex

**Repository Path**: opentech_usher/usher-groovy-flex

## Basic Information

- **Project Name**: usher-groovy-flex
- **Description**: groovy-flex是一个专为Spring Boot应用设计的动态脚本执行框架，基于Groovy语言开发，支持在运行时动态修改业务逻辑，适用于企业级应用中的规则引擎、工作流条件判断等场景。
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-24
- **Last Updated**: 2026-02-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Usher Groovy Flex

`usher-groovy-flex` 是一个专为Spring Boot应用设计的动态脚本执行框架，基于Groovy语言开发，支持在运行时动态修改业务逻辑，适用于企业级应用中的规则引擎、工作流条件判断等场景。

## 特性

- **动态脚本执行**: 支持在运行时动态执行Groovy脚本
- **Spring Boot集成**: 无缝集成Spring Boot，开箱即用
- **脚本缓存**: 提供脚本缓存机制，提升执行性能
- **参数传递**: 支持向脚本传递参数
- **安全执行**: 提供安全的脚本执行环境
- **灵活配置**: 支持通过配置文件自定义行为

## 快速开始

### 1. 添加依赖

在你的 `pom.xml` 中添加以下依赖：

```xml
<dependency>
    <groupId>top.uhyils.usher</groupId>
    <artifactId>usher-groovy-flex-boot-starter</artifactId>
    <version>2.1.2.2.usher</version>
</dependency>
```

### 2. 配置选项

在 `application.yml` 或 `application.properties` 中进行配置：

```yaml
usher:
  groovy:
    flex:
      enable-script-cache: true      # 启用脚本缓存
      max-cache-size: 100           # 最大缓存数量
      script-timeout: 5000          # 脚本超时时间（毫秒）
```

或

```properties
usher.groovy.flex.enable-script-cache=true
usher.groovy.flex.max-cache-size=100
usher.groovy.flex.script-timeout=5000
```

### 3. 使用示例

#### 基本用法

```java
@RestController
public class ScriptController {
    
    @Autowired
    private GroovyScriptRunner groovyScriptRunner;
    
    @PostMapping("/execute")
    public Object executeScript(@RequestBody ScriptRequest request) {
        Map<String, Object> params = new HashMap<>();
        params.put("input", request.getInput());
        params.put("data", request.getData());
        
        return groovyScriptRunner.run(request.getScript(), params);
    }
    
    @PostMapping("/execute-with-cache")
    public Object executeScriptWithCache(@RequestBody CachedScriptRequest request) {
        Map<String, Object> params = new HashMap<>();
        params.put("input", request.getInput());
        params.put("data", request.getData());
        
        return groovyScriptRunner.runWithCache(
            request.getScriptId(), 
            request.getScript(), 
            params
        );
    }
}
```

#### Groovy脚本示例

```groovy
// 简单计算
def calculate(a, b) {
    return a + b
}

calculate(input.a, input.b)
```

```groovy
// 条件判断
if (data.status == 'ACTIVE') {
    return [result: 'allowed', code: 200]
} else {
    return [result: 'denied', code: 403]
}
```

```groovy
// 数据处理
def processList(items) {
    return items.findAll { it.value > 100 }
               .collect { it.name }
}

processList(data.items)
```

## 核心组件

### 1. GroovyScriptRunner

主要的脚本执行接口，提供基本的脚本执行功能：

- `run()`: 执行脚本
- `runWithCache()`: 执行带缓存的脚本
- `clearCache()`: 清除缓存

### 2. 配置属性

- `enableScriptCache`: 是否启用脚本缓存
- `maxCacheSize`: 最大缓存大小
- `scriptTimeout`: 脚本执行超时时间

## 应用场景

- **规则引擎**: 动态定义业务规则
- **工作流条件**: 动态判断流程走向
- **数据转换**: 动态数据格式转换
- **报表生成**: 动态报表逻辑
- **API路由**: 动态API路由规则

## 安全考虑

- 限制脚本执行时间防止长时间运行
- 不允许执行系统级操作（如文件IO、网络请求）
- 建议对上传的脚本进行安全验证

## 开发指南

### 本地构建

```bash
mvn clean install
```

### 运行测试

```bash
mvn test
```

## 许可证

Apache License, Version 2.0

## 联系方式

- 作者: uhyils
- 邮箱: uhyils@qq.com