脚本支持

DeepSeek V3 中英对照 Scripting Support

Spring Integration 2.1 新增了对 JSR223 Java 脚本规范 的支持，该规范自 Java 6 版本引入。它允许您使用任何支持的语言（包括 Ruby、JRuby、Groovy 和 Kotlin）编写的脚本来为各种集成组件提供逻辑，类似于 Spring Integration 中使用 Spring 表达式语言（SpEL）的方式。有关 JSR223 的更多信息，请参阅相关文档。

此依赖项为项目所需：

Maven

<dependency>
    <groupId>org.springframework.integration</groupId>
    <artifactId>spring-integration-scripting</artifactId>
    <version>7.0.2</version>
</dependency>

Gradle

compile "org.springframework.integration:spring-integration-scripting:7.0.2"

此外，你还需要添加一个脚本引擎实现，例如 JRuby。

从 5.2 版本开始，Spring Integration 提供了 Kotlin Jsr223 支持。你需要将此依赖项添加到项目中才能使其正常工作：

Maven

<dependency>
    <groupId>org.jetbrains.kotlin</groupId>
    <artifactId>kotlin-scripting-jsr223</artifactId>
    <scope>runtime</scope>
</dependency>

Gradle

runtime 'org.jetbrains.kotlin:kotlin-scripting-jsr223'

要使用 JVM 脚本语言，必须在类路径中包含该语言的 JSR223 实现。Groovy 和 JRuby 项目在其标准发行版中提供了 JSR233 支持。

important

多种 JSR223 语言实现已由第三方开发。特定实现与 Spring Integration 的兼容性取决于其对规范的遵循程度以及实现者对规范的理解。

提示

如果你计划使用 Groovy 作为脚本语言，我们建议你使用 Spring-Integration 的 Groovy 支持，因为它提供了针对 Groovy 的额外功能。不过，本节内容也同样适用。

脚本配置

根据集成需求的复杂程度，脚本可以以内联CDATA形式嵌入XML配置，也可以作为包含脚本的Spring资源引用。为支持脚本功能，Spring Integration定义了ScriptExecutingMessageProcessor，该处理器将消息负载绑定到名为payload的变量，将消息头绑定到headers变量，这两个变量在脚本执行上下文中均可访问。您只需编写使用这些变量的脚本即可。以下两个示例展示了创建过滤器的配置示例：

Java DSL

@Bean
public IntegrationFlow scriptFilter() {
    return f -> f.filter(Scripts.processor("some/path/to/ruby/script/RubyFilterTests.rb"));
}
...
@Bean
public Resource scriptResource() {
	return new ByteArrayResource("headers.type == 'good'".getBytes());
}

@Bean
public IntegrationFlow scriptFilter() {
	return f -> f.filter(Scripts.processor(scriptResource()).lang("groovy"));
}

XML

<int:filter input-channel="referencedScriptInput">
   <int-script:script location="some/path/to/ruby/script/RubyFilterTests.rb"/>
</int:filter>

<int:filter input-channel="inlineScriptInput">
     <int-script:script lang="groovy">
     <![CDATA[
     return payload == 'good'
   ]]>
  </int-script:script>
</int:filter>

如前面的示例所示，脚本可以内联包含，也可以通过引用资源位置（使用 location 属性）来包含。此外，lang 属性对应于语言名称（或其 JSR223 别名）。

其他支持脚本的Spring集成端点元素包括 router、service-activator、transformer 和 splitter。每种情况下的脚本配置与上述相同（除了端点元素）。

脚本支持的另一个有用特性是能够在无需重启应用上下文的情况下更新（重新加载）脚本。为此，请在 script 元素上指定 refresh-check-delay 属性，如下例所示：

Java DSL

Scripts.processor(...).refreshCheckDelay(5000)
}

XML

<int-script:script location="..." refresh-check-delay="5000"/>

在前面的例子中，脚本位置每5秒检查一次更新。如果脚本被更新，任何在更新后超过5秒的调用都会导致运行新脚本。

考虑以下示例：

Java DSL

Scripts.processor(...).refreshCheckDelay(0)
}

XML

<int-script:script location="..." refresh-check-delay="0"/>

在前面的示例中，一旦脚本发生修改，上下文会立即更新，这为“实时”配置提供了一种简单的机制。任何负值都意味着在应用程序上下文初始化后，脚本不会被重新加载。这是默认行为。以下示例展示了一个永远不会更新的脚本：

Java DSL

Scripts.processor(...).refreshCheckDelay(-1)
}

XML

<int-script:script location="..." refresh-check-delay="-1"/>

important

内联脚本无法重新加载。

脚本变量绑定

变量绑定用于使脚本能够引用外部提供给脚本执行上下文的变量。默认情况下，payload 和 headers 被用作绑定变量。您可以通过使用 <variable> 元素（或 ScriptSpec.variables() 选项）将额外的变量绑定到脚本，如下例所示：

Java DSL

Scripts.processor("foo/bar/MyScript.py")
    .variables(Map.of("var1", "thing1", "var2", "thing2", "date", date))
}

XML

<script:script lang="py" location="foo/bar/MyScript.py">
    <script:variable name="var1" value="thing1"/>
    <script:variable name="var2" value="thing2"/>
    <script:variable name="date" ref="date"/>
</script:script>

如前面的示例所示，您可以将脚本变量绑定到标量值或Spring bean引用。请注意，payload 和 headers 仍作为绑定变量包含在内。

自 Spring Integration 3.0 起，除了 variable 元素外，还引入了 variables 属性。该属性与 variable 元素并不互斥，您可以在一个 script 组件中同时使用它们。然而，无论变量在何处定义，它们都必须是唯一的。此外，从 Spring Integration 3.0 开始，内联脚本也允许变量绑定，如下例所示：

<service-activator input-channel="input">
    <script:script lang="ruby" variables="thing1=THING1, date-ref=dateBean">
        <script:variable name="thing2" ref="thing2Bean"/>
        <script:variable name="thing3" value="thing2"/>
        <![CDATA[
            payload.foo = thing1
            payload.date = date
            payload.bar = thing2
            payload.baz = thing3
            payload
        ]]>
    </script:script>
</service-activator>

前面的示例展示了内联脚本、variable 元素和 variables 属性的组合使用。variables 属性包含一个逗号分隔的值，其中每个段包含一个由 '=' 分隔的变量及其值对。变量名可以带有 -ref 后缀，如前面示例中的 date-ref 变量。这意味着绑定变量的名称为 date，但其值是对应用程序上下文中 dateBean bean 的引用。在使用属性占位符配置或命令行参数时，这可能很有用。

如果你需要对变量的生成方式进行更精细的控制，可以自行实现一个使用 ScriptVariableGenerator 策略的 Java 类，该策略由以下接口定义：

public interface ScriptVariableGenerator {

    Map<String, Object> generateScriptVariables(Message<?> message);

}

此接口要求你实现 generateScriptMessage(Message) 方法。消息参数允许你访问消息负载和头部中的任何可用数据，返回值是绑定变量的 Map。每次为消息执行脚本时都会调用此方法。以下示例展示了如何提供 ScriptVariableGenerator 的实现，并通过 script-variable-generator 属性引用它：

Java DSL

Scripts.processor("foo/bar/MyScript.groovy")
    .variableGenerator(new foo.bar.MyScriptVariableGenerator())
}

XML

<int-script:script location="foo/bar/MyScript.groovy"
        script-variable-generator="variableGenerator"/>

<bean id="variableGenerator" class="foo.bar.MyScriptVariableGenerator"/>

如果未提供 script-variable-generator，脚本组件将使用 DefaultScriptVariableGenerator，该生成器在其 generateScriptVariables(Message) 方法中，将任何提供的 <variable> 元素与来自 Message 的 payload 和 headers 变量进行合并。

important

不能同时提供 script-variable-generator 属性和 <variable> 元素。它们是互斥的。

GraalVM 多语言支持

自 6.0 版本起，框架提供了一个基于 GraalVM Polyglot API 的 PolyglotScriptExecutor。原本由 Java 自身移除的 JavaScript JSR223 引擎实现，现已被这个新的脚本执行器所取代。关于如何在 GraalVM 中启用 JavaScript 支持，以及可以通过脚本变量传递哪些配置选项的更多信息，请参阅相关文档。特别需要注意的是，为了支持 JavaScript，必须在目标项目中添加 org.graalvm.polyglot:js 依赖。

从版本 6.4 开始，Python 脚本支持也已迁移至 GraalVM Polyglot。现在这些脚本可以用 Python 3.x 编写，并且可以使用第三方库。更多信息请参阅 GraalPy 文档。特别需要注意的是，为了支持 Python，必须在目标项目中添加 rg.graalvm.polyglot:python 依赖项。

默认情况下，框架会在共享的 Polyglot Context 上设置 allowAllAccess 为 true，从而启用与宿主 JVM 的交互：

• 创建和使用新线程。

• 访问公共主机类。

• 通过向类路径添加条目来加载新的主机类。

• 将新成员导出到多语言绑定中。

• 在主机系统上进行无限制的 IO 操作。

• 传递实验性选项。

• 创建和使用新的子进程。

• 访问进程环境变量。

这可以通过重载 PolyglotScriptExecutor 构造函数来实现，该构造函数接受一个 org.graalvm.polyglot.Context.Builder 参数。例如，基于 Jython 的脚本仍然可以通过设置 option("python.EmulateJython", "true") 来执行。然而，为了获得更好的解释性能，建议完全迁移到 GraalPy。因此，不再支持直接 import Java 类，而必须使用 import java 及其 java.type() 函数。