Apache Groovy 配置参数详解

梳理 Apache Groovy 配置：GROOVY_HOME/JAVA_OPTS、-cp/-D/--configscript 参数、GroovyConfig、Grape 依赖、groovysh/@CompileStatic、内存调优。

Apache GroovyApache Groovy参数调优JavaApache配置详解2026/10/12

Apache Groovy 配置参数详解

Groovy 的配置可归纳为四层：进程环境变量、命令行参数、编译配置脚本（--configscript / withConfig）以及依赖解析配置（Grape）。本文结合 Ubuntu 22.04 与 CentOS 8 上的真实回显逐一说明。

一、环境变量

1.1 GROOVY_HOME

GROOVY_HOME 指向 Groovy 安装根目录，启动脚本据此定位 lib/、conf/ 与 bin/。

# export GROOVY_HOME=/opt/groovy
# ls $GROOVY_HOME
bin  conf  lib  LICENSE  NOTICE

1.2 JAVA_HOME 与 PATH

Groovy 由启动脚本调用 $JAVA_HOME/bin/java，因此 JAVA_HOME 决定实际运行的 JDK 版本；PATH 需包含 $GROOVY_HOME/bin。

# export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64   # CentOS: /usr/lib/jvm/java-11-openjdk
# export PATH=$GROOVY_HOME/bin:$JAVA_HOME/bin:$PATH
# groovy --version
Groovy Version: 4.0.24 JVM: 11.0.32.1 Vendor: Ubuntu OS: Linux

1.3 JAVA_OPTS

JAVA_OPTS 会被追加到 JVM 启动参数中，适合设置堆大小、时区、编码等。实测验证堆上限生效：

# JAVA_OPTS="-Xmx512m" groovy -e 'println((Runtime.runtime.maxMemory()/1024/1024) as int)'
512

二、groovy 启动参数

2.1 -cp / -classpath

指定脚本运行所需的额外类路径，注意必须作为第一个参数：

# groovy -cp /opt/libs/app.jar /root/app.groovy

2.2 -D / --define

向 JVM 注入系统属性，脚本中通过 System.getProperty 读取：

# groovy -Dapp.env=prod -e 'println System.getProperty("app.env")'
prod

2.3 --configscript

指定编译配置脚本，对本次编译全局生效。创建一个全局启用静态编译的配置脚本 config.groovy：

withConfig(configuration) {
    ast(groovy.transform.CompileStatic)
}

应用该配置：

# groovy --configscript=/root/config.groovy -e 'int r = 0; for (i in 1..3){ r += i }; println "sum=" + r'
sum=6

2.4 -J 与相关选项

groovyc 支持 -J=<property=value> 将属性透传给底层 javac（联合编译场景），以及 -pa（保留方法参数名元数据）、-pr（启用预览特性）。示例：

# groovyc -J=source=11 -d /root/classes /root/mix/*.groovy /root/mix/*.java

三、GroovyConfig 与 groovy.properties

3.1 withConfig 编译配置

在 --configscript 或自定义 Builder 中使用 withConfig(configuration){...} 调整 CompilerConfiguration，例如开启 invokedynamic、追加全局 AST 转换：

withConfig(configuration) {
    configuration.optimizationOptions.indy = true
}

3.2 ConfigSlurper 读取分层配置

groovy.util.ConfigSlurper 可将 Groovy 风格的分层配置解析为对象：

def slurper = new groovy.util.ConfigSlurper()
def cfg = slurper.parse('''
app {
    name = 'groovy-app'
    threads = 8
    debug = true
    db { url = 'jdbc:mysql://127.0.0.1:3306/demo'; pool = 10 }
}
''')
println "app.name    = ${cfg.app.name}"
println "app.db.url  = ${cfg.app.db.url}"

真实回显：

app.name    = groovy-app
app.threads = 8
app.debug   = true
app.db.url  = jdbc:mysql://127.0.0.1:3306/demo
app.db.pool = 10

四、Grape/Ivy 依赖解析与 @GrabConfig

4.1 @Grab

在脚本顶部用 @Grab 声明依赖，Groovy 会在编译期通过 Grape（内嵌 Ivy）解析并缓存 jar：

@Grab('org.apache.commons:commons-lang3:3.14.0')
import org.apache.commons.lang3.StringUtils
println StringUtils.reverse('apache')

真实回显：

# groovy /root/grab.groovy
trim   = [groovy grab]
reverse= barg yvoorg
cap    = Apache

4.2 @GrabConfig

当需要控制系统类加载器（如 JDBC 驱动、java.sql 服务发现）时使用：

@GrabConfig(systemClassLoader = true)
@Grab('org.postgresql:postgresql:42.7.3')
import org.postgresql.Driver
println Driver.name

4.3 缓存与镜像

  • 缓存目录：~/.groovy/grapes。
  • 私有仓库：通过 @GrabResolver(name='nexus', root='https://nexus.example.com/repository/maven-public/') 指定。
  • CLI 管理：grape install / grape list / grape resolve（详见《Apache Groovy 常用 CLI 命令与工具详解》）。

五、groovysh 配置

5.1 常用参数

  • -q：安静模式，抑制多余提示。
  • -D：注入系统属性。
  • -e <code>：进入会话前先执行一段代码。
  • -cp：追加类路径。
  • -T <TYPE>：指定终端类型。

5.2 启动目录约束（重要）

groovysh 启动时会对类路径当前目录递归扫描包名。若在根目录 / 启动会陷入长时间扫描（CPU 满载且无输出）。务必在业务目录中启动：

# mkdir -p /opt/groovy-work && cd /opt/groovy-work
# groovysh
Groovy Shell (4.0.24, JVM: 11.0.32.1)
groovy:000> :help

5.3 变量作用域

在 groovysh 中，def x = ... 定义的是单条求值的局部变量，不跨行保留；需要跨行复用请使用 x = ...：

groovy:000> m=[a:1,b:2]
===> [a:1, b:2]
groovy:000> m.collect{ k,v -> k.toUpperCase()+v }.join(",")
===> A1,B2

六、@CompileStatic 与 @TypeChecked

6.1 命令行开关

# groovy --compile-static -e 'int add(int a,int b){a+b}; println add(3,4)'
7

6.2 @TypeChecked 静态类型检查

# groovy --type-checked -e 'int n = "not-a-number"'
org.codehaus.groovy.control.MultipleCompilationErrorsException: startup failed:
script_from_command_line: 1: [Static type checking] - Cannot assign value of type java.lang.String to variable of type int
 @ line 1, column 9.
   int n = "not-a-number"
           ^

6.3 注解用法

import groovy.transform.CompileStatic
import groovy.transform.TypeChecked

@CompileStatic
class Calculator {
    int add(int a, int b) { a + b }
}

@CompileStatic 在编译期生成静态分派字节码，性能接近原生 Java；@TypeChecked 仅做类型校验而不改变分派方式。

七、内存与 JVM 参数

7.1 堆内存

通过 JAVA_OPTS 控制堆区间，脚本类场景建议 256–512 MB：

# JAVA_OPTS="-Xms256m -Xmx512m" groovy -e 'println((Runtime.runtime.maxMemory()/1024/1024) as int)'
512

7.2 元空间与 GC

# export JAVA_OPTS="-Xmx512m -XX:MaxMetaspaceSize=256m -XX:+UseG1GC"

7.3 编码与随机源

# export JAVA_OPTS="$JAVA_OPTS -Dfile.encoding=UTF-8 -Djava.security.egd=file:/dev/./urandom"

7.4 关闭 Java 模块告警

在 JDK 16+ 上运行 Groovy 会提示模块访问告警，可设置：

# export GROOVY_TURN_OFF_JAVA_WARNINGS=true