Groovy 语言教学

一份面向”有 Java 基础(或没有)的工程师”的 Groovy 语言教学文档。
全文示例均可直接运行(groovy xxx.groovy 或粘贴进 groovyConsole),最后一章专门讲在 Jira ScriptRunner 中使用 Groovy 的要点。



1. Groovy 是什么

Groovy 是一门运行在 JVM 上的动态语言,最终编译成和 Java 一样的字节码。

它和 Java 的关系可以这样理解:

  • 语法上:Groovy 是 Java 的超集(大部分 Java 代码去掉分号就能当 Groovy 跑);
  • 运行时:同一个 JVM、可以互相调用、可以用所有 Java 库;
  • 气质上:Java 是”严谨的编译型语言”,Groovy 是”脚本化的动态语言”——你可以像写 Python 一样写它,也可以像写 Java 一样写它。

1.1 为什么在 Jira 生态里必须学 Groovy

  • ScriptRunner for Jira(Jira DC/Server 最大的自动化插件)的脚本语言就是 Groovy;
  • Jenkins pipeline(脚本式)、Gradle 构建脚本、SonarQube、Bitbucket Server 钩子等也大量使用 Groovy。

1.2 Groovy vs Java 速览

特性 Java Groovy
分号、public、return 必须/习惯写 全部可省略
类型 静态 可静态可动态(def)
字符串插值 无(要 String.format) "hello ${name}"
集合字面量 new ArrayList<>()… [1, 2, 3]、[a: 1]
闭包 Lambda(受限) 真闭包(可改 delegate)
== 比较引用 调用 equals()
运行方式 编译后运行 可直接跑脚本,也可编译成 .class
默认小数类型 double BigDecimal

1.3 版本说明

  • Groovy 2.x:Jira 7/8 时代 ScriptRunner 捆绑的版本(2.4.x 为主)。
  • Groovy 3.x:支持 Java 风格 Lambda、do-while、!in、!instanceof、var;较新的 ScriptRunner 捆绑此版本。
  • Groovy 4.x:包名从 org.codehaus.groovy 迁到 groovy,switch 支持箭头语法。

本文以 Groovy 3.x 为主,涉及版本差异处会明确标注。写 Jira 脚本前,先确认你的 ScriptRunner 捆绑的 Groovy 版本(管理界面里能看到)。


2. 快速开始

2.1 安装与运行

三种最常见的运行方式:

# 方式一:命令行直接跑脚本文件
groovy hello.groovy

# 方式二:交互式 REPL(逐行试语法)
groovysh

# 方式三:图形化控制台(左侧写代码,右侧看输出,最推荐初学者)
groovyConsole

安装:从 groovy-lang.org 下载,或用 SDKMAN(Linux/macOS)/ Scoop、Chocolatey(Windows)。要求先装好 JDK。

2.2 第一个脚本

新建 hello.groovy:

// 没有 class、没有 main、没有分号、没有 System.out
def name = 'World'
println "Hello, ${name}!"

// 文件顶层直接写语句,Groovy 会自动包成一个类去执行
3.times {
    println "repeat"
}

输出:

Hello, World!
repeat
repeat
repeat

2.3 一切都是”脚本即代码”

Groovy 会把脚本文件编译成一个继承自 groovy.lang.Script 的类(文件名即类名),顶层语句进入自动生成的 run() 方法。所以:

  • 脚本里可以定义方法、类(放在文件末尾更符合习惯);
  • 也可以把同一个 .groovy 文件编译成 .class 给 Java 调用(groovyc)。

3. 变量、类型与字符串

3.1 def 与动态类型

def x = 1          // 动态类型,编译器不检查类型
x = 'now a string' // 可以随时换类型(动态类型语言的自由)

int y = 2          // 也可以像 Java 一样声明静态类型
y = 3              // 静态类型会在编译/运行时检查
// y = 'str'       // 运行时抛 CannotCastException

经验法则:

  • 局部小脚本用 def;
  • 写给别人看、要长期维护的代码,参数和返回值尽量标静态类型——IDE 补全和静态检查都会好很多;
  • 公共 API、类字段必须声明类型(或 def)。

3.2 一切皆对象

Groovy 里没有”基本类型”这回事:int 在需要时会自动包装成 Integer。所有值都是对象,所以可以写 42.toString()、1.class。

3.3 数字与除法的坑

assert 1 + 1 == 2
assert 2 ** 10 == 1024          // ** 幂运算

assert 5 / 2 == 2.5             // ⚠️ 除法默认返回 BigDecimal,不是整数!
assert 5.intdiv(2) == 2         // 想要整数除法用 intdiv
assert 5 % 2 == 1

assert 0.1 + 0.2 == 0.3         // BigDecimal 精确运算,没有浮点误差

要点:Groovy 的小数字面量(1.5)默认是 BigDecimal 而不是 double。这对金额计算是好消息,但从 Java 思维迁移过来容易踩坑。

3.4 字符串:三种引号

def s1 = 'single'   // 单引号:纯字符串(等价 Java 的 String)
def s2 = "double"   // 双引号:如果没有 $,也是纯 String
def s3 = '''triple
multi
line'''             // 三单引号:多行文本(保留原样)

3.5 GString:字符串插值

双引号字符串里出现 $,就变成了 **GString**(模板字符串):

def name = 'Alice'
def score = 95

println "Hi ${name}, your score is ${score}"   // ${...} 里放任意表达式
println "Hi $name"                              // 只取变量时可省略大括号
println "Score: ${score > 90 ? 'excellent' : 'good'}"  // 表达式

def multi = """
select * from t
where name = '${name}'
"""                                             // 常用于拼 SQL / JSON / HTML

println "text".center(20, '-')   // --------text--------

⚠️ GString 的经典大坑(必背):

def name = 'World'
def gs = "Hello ${name}"
def st = 'Hello World'

assert gs == st            // ✅ 用 == 比较相等:true(== 调 equals)
def map = [:]
map[gs] = 'a'
assert map[st] == 'a'      // ❌ 抛 NPE / 取不到!

原因:GString 和 String 的 hashCode() 不同,作为 HashMap/HashSet 的 key 时查不到。**任何要当 key、要放入 Set、要传给严格比较的 API 的字符串,都先 .toString()**。

3.6 常用字符串扩展方法(GDK)

assert 'Groovy'.size() == 6            // 比 length() 好记
assert 'a,b,c'.tokenize(',') == ['a', 'b', 'c']
assert 'a b  c'.split() == ['a', 'b', 'c']
assert '  pad '.trim() == 'pad'
assert 'abc'.reverse() == 'cba'
assert 'abc'.capitalize() == 'Abc'
assert 'Hello'.toLowerCase() == 'hello'
assert 'groovy'.padRight(10, '.') == 'groovy.....'
assert '123'.toInteger() == 123
assert '1.5'.toDouble() == 1.5
assert '2024-01-01'.substring(0, 4) == '2024'
assert 'one two'.replaceAll('o', '0') == '0ne tw0'
assert 'a1b2'.findAll(/\d/) == ['1', '2']     // 正则提取

3.7 Truthy:真值判断

Groovy 的 if 接受任意对象,有自己的”真假”规则:

值 真假
null、false、0(数字零) 假
'' 空字符串、[] 空集合、[:] 空 Map 假
零长度的迭代器/流(Iterator、Stream) 假
其他一切(包括空格字符串 ' ') 真
def list = []
if (!list) println 'empty'      // 常见写法:空集合当 false
def name = null
println name ?: 'default'       // 配合 Elvis(见第 4 章)

4. 运算符:Groovy 与 Java 最大的差别

这一章是”Java 老手最容易被坑”的部分,请逐条记住。

4.1 == 是 equals,is() 才是比引用

def a = new StringBuilder('x')
def b = new StringBuilder('x')

assert a == b      // true:== 调用 a.equals(b)
assert !a.is(b)    // is() 比较引用(同一个对象?)

// Groovy 3+ 也可以用 ===
assert a !== b     // Groovy 3+

对于实现了 Comparable 的类(如 BigDecimal、String),== 语义是”值相等”(compareTo() == 0)。写 Java 习惯了的”用 == 比引用”在 Groovy 里是错的。

4.2 安全导航 ?.:再也不写满屏 null 判断

def user = null

// Java 风格:
// if (user != null && user.getAddress() != null) { ... }

// Groovy 风格:
println user?.address?.city    // null,不抛 NPE

def list = null
println list?.size()           // null

注意:?. 只保护”点号左边的对象”。如果链式调用中间还有会抛异常的方法(如下标越界),仍需自己判断。

4.3 Elvis 操作符 ?::默认值神器

def name = null
def displayName = name ?: 'Anonymous'    // name 为 null/falsy 时取右侧

def port = System.getProperty('port') as Integer ?: 8080

读法:a ?: b = “a 有值就用 a,否则用 b”(像 Elvis 的侧脸发型而得名)。

4.4 宇宙船操作符 <=>:三路比较

assert 1 <=> 2 == -1     // 小于
assert 2 <=> 2 == 0      // 相等
assert 3 <=> 2 == 1      // 大于

常用于自定义排序:

list.sort { a, b -> a.age <=> b.age ?: a.name <=> b.name }   // 先按年龄,再按姓名

4.5 展开操作符 *.:批量调用

def names = ['alice', 'bob']
assert names*.capitalize() == ['Alice', 'Bob']
// 等价于 names.collect { it.capitalize() }
// 且对 null 元素安全:[null, 'x']*.capitalize() == [null, 'X']

还有两个兄弟:

// 展开实参:把 List 拆成一个个参数传进去
def add(int a, int b) { a + b }
def args = [1, 2]
assert add(*args) == 3          // 等价 add(1, 2)

// 展开合入 Map 字面量
def defaults = [retries: 3, timeout: 30]
def config = [timeout: 10, *:defaults]   // 后面的覆盖前面的

4.6 正则操作符

// =~ 返回 Matcher(找匹配)
def m = '2024-10-01' =~ /\d{4}-\d{2}-\d{2}/
assert m.find()

// ==~ 全串匹配(整个字符串都要匹配上)
assert '2024-10-01' ==~ /\d{4}-\d{2}-\d{2}/
assert !'x2024-10-01' ==~ /\d{4}-\d{2}-\d{2}/

// 斜杠字符串:写正则不用双写反斜杠
def pattern = ~/a\d+/        // 等价 "a\\d+"

4.7 其他常用操作符速览

def x = 5
x += 2; x -= 1; x *= 3       // 正常
assert x in [6, 7, 8]        // in:成员判断(集合/Range/Map)
assert 'a' in 'abc'          // CharSequence 也支持
assert !(3 in [1, 2])

// Groovy 3+
assert 3 !in [1, 2]
assert 5 !instanceof String     // Java 风格写 !(x instanceof String) 也完全可以

// as:类型强制转换
assert '123' as Integer == 123
assert [1, 2, 3] as String[] instanceof String[]

5. 集合:Groovy 的灵魂

Groovy 对 List、Map、Set、Range 做了大量扩展(GDK),配合闭包形成了极其流畅的数据处理风格。这一章值得反复看。

5.1 List

def list = [1, 2, 3, 'mixed', null]   // 字面量创建 ArrayList,元素可混合类型
def empty = []

// 访问
assert list[0] == 1
assert list[-1] == null               // ⭐ 负索引从尾部数
assert list[1..3] == [2, 3, 'mixed']  // 切片返回新 List
assert list.size() == 5

// 增删改
list << 4                 // 追加(左移运算符),返回 list 自身
list << 5 << 6            // 可链式
list.add(0, 'head')       // 插入
list -= 4                 // 移除值为 4 的元素
list.removeLast()
assert list.contains(2)
assert 2 in list
list.clear()

排序(注意可变性):

def nums = [3, 1, 2]
def sorted = nums.sort()            // ⚠️ 原地排序,改变 nums 自身
assert sorted == [1, 2, 3] && nums == [1, 2, 3]

nums = [3, 1, 2]
def copied = nums.sort(false)       // false = 不修改原集合,返回新 List
assert nums == [3, 1, 2] && copied == [1, 2, 3]

def people = [[name: 'B', age: 30], [name: 'A', age: 25]]
def byAge = people.sort(false) { it.age }                    // 单键
def multi = people.sort(false) { a, b -> a.age <=> b.age }   // 自定义比较

去重、反转、打乱:

assert [1, 2, 2, 3].unique() == [1, 2, 3]        // 原地;unique(false) 返回新
assert [1, 2, 3].reverse() == [3, 2, 1]
assert [1, 2, 3].shuffled().size() == 3
assert [3, 1, 2].min() == 1
assert [3, 1, 2].max() == 3
assert [1, 2, 3].sum() == 6
assert ['a', 'b'].sum() == 'ab'
assert [1, 2, 3].sum { it * 2 } == 12            // 先变换再求和
assert [1, 2, 3].average() == 2.0
assert [1, 2, 3].count { it > 1 } == 2
assert [1, 2, 1, 3].count(1) == 2
assert [[1, 2], [3]].flatten() == [1, 2, 3]
assert [[1, 2], [3, 4]].transpose() == [[1, 3], [2, 4]]
assert [1, 2, 3].join('-') == '1-2-3'

5.2 Map

def map = [name: 'Alice', age: 30]   // 字面量创建 LinkedHashMap(保序)
def empty = [:]

// 访问——两种风格都行
assert map.name == 'Alice'
assert map['name'] == 'Alice'
assert map.age == 30
assert map.missing == null           // 不存在的 key 返回 null,不抛异常

// 增改
map.city = 'Beijing'                  // 不存在即新增
map.age = 31
map << [country: 'CN']               // 合并(原地)
def merged = map + [zip: '100000']   // 生成新 Map

// 删
map.remove('zip')
assert map.keySet() instanceof Set
assert map.containsKey('name')
assert map.any { it.value instanceof String }

⚠️ Map 字面量的两个坑:

def key = 'dyn'
// 坑 1:裸标识符会被当作字符串
def m1 = [key: 'value']          // key 是字符串 "key"!
assert m1['dyn'] == null
def m2 = [(key): 'value']        // ⭐ 加括号才是变量求值
assert m2['dyn'] == 'value'

// 坑 2:GString 做 key 进 HashMap 查不到(见 3.5)
def gs = "a${1}"
def map2 = [:]
map2[gs] = 'x'
assert map2['a1'] == null        // ❌ hashCode 不同
assert map2[gs.toString()] == 'x' // ✅

5.3 Map 的遍历与变换

def scores = [alice: 90, bob: 75, carol: 82]

// 遍历:entry 是 Map.Entry,可用 it.key / it.value
scores.each { entry -> println "${entry.key} -> ${entry.value}" }
scores.each { k, v -> println "$k -> $v" }              // 两个参数更常用
scores.eachWithIndex { k, v, i -> println "$i: $k=$v" }

// 过滤 / 变换(都返回新 Map)
def passed = scores.findAll { it.value >= 80 }          // Map
def doubled = scores.collectEntries { k, v -> [k, v * 2] }
def namesOnly = scores.collect { k, v -> k }            // 变成 List

// 查找
assert scores.find { it.value > 85 }.key == 'alice'     // 返回第一个满足的 Entry
assert scores.every { it.value > 60 }
assert scores.any { it.value == 75 }
assert scores.count { it.value > 80 } == 2

// 分组
def byPass = scores.groupBy { it.value >= 80 }          // [true:[...], false:[...]]
def buckets = scores.countBy { it.value >= 80 }         // 计数版:[true:2, false:1]

// 排序(Map 排序返回 LinkedHashMap)
def ranked = scores.sort { -it.value }                  // 按分数降序(原地)
def asc = scores.sort(false) { a, b -> a.value <=> b.value }

5.4 Range

def r1 = 1..5          // 含头含尾
def r2 = 1..<5         // 含头不含尾
def letters = 'a'..'e'

assert r1.from == 1 && r1.to == 5
assert r2 == [1, 2, 3, 4]
assert (5..1).toList() == [5, 4, 3, 2, 1]   // 可反向
assert letters.contains('c')

r1.each { print "$it " }        // 1 2 3 4 5
(0..<10).step(3) { print "$it " }   // 0 3 6 9

Range 是 List 之外最常用的”区间”工具:循环、切片、switch 分支、日期区间都靠它。

5.5 数据处理实战:一条链式流水线

def orders = [
    [id: 1, user: 'alice', amount: 120, paid: true],
    [id: 2, user: 'bob',   amount: 80,  paid: false],
    [id: 3, user: 'alice', amount: 200, paid: true],
    [id: 4, user: 'carol', amount: 45,  paid: true],
]

// 需求:已支付订单,按用户汇总金额,输出金额降序的 Map
def report = orders
    .findAll { it.paid }                                   // 过滤
    .groupBy { it.user }                                   // 按用户分组
    .collectEntries { user, list ->                        // 聚合
        [user, list.sum { it.amount }]
    }
    .sort { a, b -> b.value <=> a.value }                  // 降序

assert report == [alice: 320, carol: 45]

这段代码用 Java 写大约要 20 行循环 + 临时变量。Groovy 的链式集合操作是它最大的生产力来源。

5.6 each 不能 break

// ❌ each 无法提前退出(return 只是跳过本次)
[1, 2, 3].each {
    if (it == 2) return        // 只是跳过 2,继续 3
    println it
}

// ✅ 需要提前退出时,换语义化方法:
assert [1, 2, 3].find { it > 1 } == 2         // 找第一个满足的
assert [1, 2, 3].any { it > 2 }               // 有一个满足就停
assert [1, 2, 3].every { it > 0 }             // 有一个不满足就停

// ✅ 或者直接用 for-in(支持 break/continue)
for (n in [1, 2, 3]) {
    if (n == 2) break
    println n
}

6. 闭包(Closure)

闭包是 Groovy 的核心特性,集合方法、Gradle DSL、ScriptRunner 全部建立在闭包之上。理解闭包是看懂别人 Groovy 代码的分水岭。

6.1 基本形态

// { 参数 -> 代码 }
def add = { a, b -> a + b }
assert add(1, 2) == 3
assert add.call(1, 2) == 3          // 两种调用方式等价

// 单参数有隐式名 it
def double = { it * 2 }
assert double(5) == 10

// 无参数要显式写 ->,否则括号里的变量会被当参数
def sayHi = { -> println 'hi' }
sayHi()

// 闭包是对象,可以赋值、传参、放进集合
def ops = [plus: { a, b -> a + b }, minus: { a, b -> a - b }]
assert ops.plus(5, 3) == 8

6.2 闭包作为方法参数:省掉括号

Groovy 规定:方法的最后一个参数是闭包时,可以写在括号外面。这就是各种”DSL 感”的来源:

def repeat(int times, Closure body) {
    times.times { body(it) }
}

repeat(3) { i ->                     // 看起来像语法,其实 repeat(3, { i -> ... })
    println "round $i"
}

each、with、tap、Gradle 的 task、Jenkins 的 pipeline,都是这个规则。

6.3 闭包捕获变量

闭包捕获的是外部局部变量的引用(可读写),这一点和 Java Lambda(只能捕获 effectively final)不同:

def counter = 0
def inc = { counter += 1 }
3.times { inc() }
assert counter == 3

6.4 this / owner / delegate

闭包里三个”我”的概念:

名称 指向
this 定义闭包的类/脚本
owner 直接外围对象(类,或外层闭包——嵌套闭包时与 this 不同)
delegate 默认等于 owner,但可以被改
class Person { String name }

def p = new Person(name: 'Alice')

def greet = { "Hi, ${name}" }       // name 在闭包作用域里找不到
greet.delegate = p                  // ⭐ 改 delegate:找不到的属性/方法去 p 身上找
assert greet() == 'Hi, Alice'

委托策略(resolveStrategy)决定”先找谁”:

策略 含义
OWNER_FIRST(默认) 先查闭包外围作用域,再查 delegate
DELEGATE_FIRST 先查 delegate
OWNER_ONLY / DELEGATE_ONLY 只查一边
TO_SELF 只查闭包自身
def name = 'Local'                      // 脚本顶层变量(owner 可见)
def c = { name }
c.delegate = [name: 'Delegate']
assert c() == 'Local'                   // 默认 OWNER_FIRST:局部变量优先

c.resolveStrategy = Closure.DELEGATE_FIRST
assert c() == 'Delegate'                // DELEGATE_FIRST:delegate 优先

为什么重要:Gradle、Jenkins、ScriptRunner 的 DSL 全靠 delegate 让你”直接写属性名”(如 description = 'x'),本质是把闭包的 delegate 设成了某个配置对象。

6.5 柯里化与记忆化

def power = { base, exp -> base ** exp }
def square = power.curry(2)             // 固定第一个参数
def cube = power.rcurry(3)              // 固定最后一个参数
assert square(5) == 25 && cube(2) == 8

// 记忆化:缓存计算结果(适合纯函数、递归)
def fib
fib = { n -> n < 2 ? n : fib(n - 1) + fib(n - 2) }.memoize()
assert fib(40) == 102334155             // 没有缓存这会跑非常久

6.6 常用闭包方法

def c = { a, b, c -> a + b + c }
def fixed = c.ncurry(1, 10, 20)         // 生成 { a -> c(a, 10, 20) }
assert fixed(6) == 36                   // 6 + 10 + 20

assert [1, 2, 3].inject(0) { acc, v -> acc + v } == 6        // 累计器
assert [1, 2, 3].inject { acc, v -> acc * v } == 6           // 无初值,用第一个元素
assert [1, 2, 3].with { size() } == 3                        // 把对象当 delegate 跑闭包

7. 控制流

7.1 if / else:与 Java 几乎相同

唯一区别是条件可以是任意对象(见 3.7 Truthy)。

7.2 switch:Groovy 的 switch 强大得多

def classify(obj) {
    switch (obj) {
        case 0:                 return 'zero'
        case 1..10:             return 'small number'
        case [11, 22, 33]:      return 'in list'
        case ~/^\d+$/:          return 'digits string'
        case String:            return 'some string'
        case { it > 100 }:      return 'big'
        default:                return 'other'
    }
}

assert classify(5) == 'small number'
assert classify(22) == 'in list'
assert classify('42') == 'digits string'
assert classify('abc') == 'some string'
assert classify(500) == 'big'
assert classify(11.5) == 'other'      // 11.5 不满足任何 case(11.5 > 100 为 false),走 default

每条 case 自上而下按顺序尝试,底层用 isCase() 判断,命中即停,所以 case 顺序很重要。

Groovy 4 新增箭头语法(不用写 break):

switch (n) {
    case 1 -> println 'one'
    case 2..5 -> println 'few'
    default -> println 'many'
}

7.3 循环

// for-in:Groovy 最常用
for (i in 0..<3) { print i }             // 012
for (s in ['a', 'b']) { print s }        // ab
for (e in [x: 1, y: 2]) { print e }      // 遍历 Map.Entry

// Java 风格也支持(Groovy 3+)
for (int i = 0; i < 3; i++) { print i }

// while / do-while(do-while 是 Groovy 3+ 才有)
def n = 0
while (n < 3) { n++ }
do { n-- } while (n > 0)

// 函数式循环
3.times { print it }                     // 012
1.upto(3) { print it }                   // 123
3.downto(1) { print it }                 // 321
0.step(1, 0.25) { print "$it " }         // 0 0.25 0.5 0.75

7.4 异常:不用声明受检异常

// Groovy 不强制声明/捕获受检异常(Checked Exception)
def parse(String s) {
    Integer.parseInt(s)     // 会抛 NumberFormatException,方法签名不用 throws
}

// 多类型捕获(Groovy 1.8+)
try {
    parse('abc')
} catch (NumberFormatException | IllegalStateException e) {
    println "bad input: ${e.message}"
} finally {
    println 'done'
}

// ⭐ Groovy 2.4+ 没有自动资源管理 try-with-resources 的语法糖?
// 有—— GDK 的 withCloseable / withReader / withWriter 更好用:
new File('out.txt').withWriter('UTF-8') { w ->
    w << 'auto closed'
}

7.5 assert:自带”力量输出”

Groovy 的断言失败时会打印每个子表达式的值,调试体验极佳:

assert [1, 2, 3].sum() == 7
// AssertionError:
//   [1, 2, 3].sum() == 7
//         |      |   |
//         6      |   false
//              false

生产代码里建议把 assert 当开发期工具,或开启/关闭 JVM 的 -ea 控制。


8. 方法与类

8.1 方法的灵活参数

// 默认参数
def greet(String name, String greeting = 'Hello') {
    "$greeting, $name!"
}
assert greet('Bob') == 'Hello, Bob!'
assert greet('Bob', 'Hi') == 'Hi, Bob!'

// 命名参数:第一个参数是 Map + 闭包的惯用法(DSL 基石)
def makeOrder(Map opts = [:]) {
    [item: opts.item ?: 'default', qty: opts.qty ?: 1, urgent: opts.urgent ?: false]
}
def o = makeOrder(item: 'pen', qty: 5)
assert o == [item: 'pen', qty: 5, urgent: false]

// 可变参数:两种写法等价
def sumAll(int... nums) { nums.sum() }
def sumAll2(Object[] nums) { nums.sum() }
assert sumAll(1, 2, 3) == 6
assert sumAll() == 0                    // 空数组也合法

8.2 返回值与省略 return

方法(和闭包)的最后一个表达式自动作为返回值:

def max2(a, b) {
    if (a > b) a        // 不写 return 也返回
    else b
}
assert max2(3, 1) == 3

注意:println 的返回值是 null,别把 println x 写成方法最后一行然后以为返回了 x。

8.3 POGO:Groovy 的”POJO”

class Person {
    String name              // 字段自动生成 getter/setter
    int age
    private String secret = 'hidden'   // private 字段不生成公开 setter 供外部随意改

    String displayName() {   // 方法
        "$name($age)"
    }
}

def p = new Person(name: 'Alice', age: 30)   // ⭐ Map 构造器(按属性名)
assert p.name == 'Alice'      // 自动 getter
p.age = 31                    // 自动 setter
assert p.displayName() == 'Alice(31)'

默认生成的类已经带 equals/hashCode/toString 的合理实现吗?——默认不带(和 Java 一样用 Object 的)。需要时用注解生成(见第 11 章)。

8.4 构造器的便利与顺序构造

class Point {
    int x
    int y
    Point(int x, int y) { this.x = x; this.y = y }
}

def p1 = new Point(1, 2)
def p2 = [1, 2] as Point        // 列表按参数顺序构造

// ⚠️ Map 构造器(按属性名)只有在类**没有显式定义构造器**时才有:
class Point2 { int x; int y }
def p3 = new Point2(x: 3, y: 4)          // ✅ Point2 无显式构造器
// new Point(x: 1, y: 2)                 // ❌ Point 定义了构造器,Map 构造器不可用

8.5 trait:真正的”接口带默认实现”

trait Greeter {
    String greet(String name) { "Hello, $name from ${this.class.simpleName}" }
    abstract String title()
}

class Bot implements Greeter {
    String title() { 'BOT' }
}

assert new Bot().greet('world') == 'Hello, world from Bot'

与 Java 8 的 default method 类似,但 Groovy trait 可以有状态(字段)、可以运行时织入(配合元编程)。

8.6 运算符重载

class Money {
    BigDecimal amount
    String currency
    Money plus(Money other) {
        assert currency == other.currency
        new Money(amount: amount + other.amount, currency: currency)
    }
    String toString() { "$amount $currency" }
}

assert (new Money(amount: 1, currency: 'CNY') + new Money(amount: 2, currency: 'CNY')).toString() == '3 CNY'

常用映射:plus(+)、minus(-)、multiply(*)、next/previous(++/--)、compareTo(<=>)、getAt/putAt([])、leftShift(<<)、isCase(in)。Jira 里日期运算 date + 3 就是这么来的。


9. 元编程

Groovy 的方法调用不走 Java 的直接分派,而是先经过一层”元对象协议(MOP)”——这意味着你可以在运行时给任何类添加/替换方法。这是 Groovy DSL 能力的底层来源,日常写业务脚本用得少,但读别人的代码必须懂。

9.1 给类加方法:metaClass

String.metaClass.shout = { -> delegate.toUpperCase() + '!' }
assert 'hello'.shout() == 'HELLO!'

// 给单个对象加方法(不影响类)
def list = [1, 2, 3]
list.metaClass.doubleSum = { -> delegate.sum() * 2 }
assert list.doubleSum() == 12

// 静态方法
Integer.metaClass.static.isEven = { int v -> v % 2 == 0 }
assert Integer.isEven(4)

警告:改 Integer.metaClass 之类会影响整个 JVM,脚本语言运行环境(如 ScriptRunner)通常禁止或不建议乱改核心类。

9.2 methodMissing / propertyMissing

class Router {
    def routes = [:]
    def methodMissing(String name, args) {
        if (name.startsWith('get')) return routes[name[3..-1].toLowerCase()]
        throw new MissingMethodException(name, this, args)
    }
    def propertyMissing(String name) { routes[name] }
}

def r = new Router(routes: [user: 'Alice'])
assert r.getUser() == 'Alice'
assert r.user == 'Alice'

动态方法/属性名(如 getAlice())就是这样”凭空”出现的——很多基于 Groovy 的规则引擎、REST 客户端都是这个模式。

9.3 @Delegate:编译期”抄袭”方法

class Sized {
    @Delegate List inner = []
}
def s = new Sized()
s << 'a' << 'b'                     // List 的方法全部被编译进 Sized
assert s.size() == 2

9.4 Expando:随手造对象

def mock = new Expando(name: 'Alice', shout: { -> "HI ${name}" })
assert mock.name == 'Alice'
assert mock.shout() == 'HI Alice'

写单测时常用 Expando 当假对象(比写匿名内部类快得多)。

9.5 类别类:临时给一批类加方法

use(TimeCategory) {
    def later = new Date() + 3.hours + 20.minutes    // Jira 脚本里常见的日期 DSL
    println later
}

use { } 块内的日期加减、TimeCategory 提供的 2.days.ago 等写法,来自 org.codehaus.groovy.runtime.TimeCategory(Groovy 4 为 groovy.time.TimeCategory)。


10. IO、JSON、XML 与正则

10.1 文件:一句话读写

def f = new File('demo.txt')

// 写
f.text = 'line1\nline2\n'                    // 覆盖写
f << 'line3\n'                               // 追加
f.withWriter('UTF-8') { w -> w.writeLine('with writer') }   // 自动关闭

// 读
println f.text                               // 整个文件为一个 String
println f.readLines()                        // 按行读成 List<String>
f.eachLine { line, idx -> println "$idx: $line" }
f.filterLine { it.contains('1') }            // 过滤行
assert f.bytes.length > 0                    // 二进制

// 遍历目录
new File('.').eachFile { println it.name }
new File('.').eachFileRecurse { println it } // 递归
new File('.').eachFileMatch(~/.*\.groovy$/) { println it }

注意:File.text 等方法默认用 JVM 编码,跨平台读中文请显式 f.getText('UTF-8')。

10.2 网络(简版)

def html = new URL('https://example.com').text    // 最简单的 GET
// 复杂请求(Header/POST/JSON)建议直接用 Java 11 HttpClient 或 Apache HttpClient,
// 在 Jira 里则走 ScriptRunner 提供的封装(见第 13 章)

10.3 JSON

import groovy.json.JsonSlurper
import groovy.json.JsonOutput

// 解析:返回 Map/List(LazyMap)
def json = new JsonSlurper().parseText('{"name":"Alice","tags":["a","b"],"meta":{"age":30}}')
assert json.name == 'Alice'
assert json.tags[1] == 'b'
assert json.meta.age == 30

// 也可以直接 parse 文件/URL
// new JsonSlurper().parse(new File('data.json'))

// 生成
def out = JsonOutput.toJson([name: 'Bob', scores: [90, 85]])
assert out == '{"name":"Bob","scores":[90,85]}'
println JsonOutput.prettyPrint(out)     // 格式化输出

10.4 XML

def xml = '''
<users>
  <user id="1"><name>Alice</name></user>
  <user id="2"><name>Bob</name></user>
</users>
'''

// 读:XmlSlurper(懒解析,语法最舒服)
def users = new XmlSlurper().parseText(xml)
assert users.user.size() == 2
assert users.user[0].name.text() == 'Alice'
assert users.user[1].@id.text() == '2'       // @ 属性访问

// 写:MarkupBuilder
def sw = new StringWriter()
new groovy.xml.MarkupBuilder(sw).users {
    user(id: 1) { name('Alice') }
    user(id: 2) { name('Bob') }
}
assert sw.toString().contains('<name>Bob</name>')

Groovy 4 中 XmlSlurper/MarkupBuilder 移到了 groovy.xml 包;Groovy 2/3 在 groovy.util.XmlSlurper。

10.5 正则:三种操作符 + 便捷方法

def text = 'issue KEY-101 and KEY-202'

// 提取所有匹配
assert text.findAll(/KEY-\d+/) == ['KEY-101', 'KEY-202']

// 捕获组
def m = 'KEY-101' =~ /KEY-(\d+)/
assert m[0][1] == '101'          // m[0] 是整串匹配,m[0][1] 是第一组

// 命名组:直接用 Java Matcher 的 group('name'),先 find()
def nm = ('KEY-101' =~ /KEY-(?<num>\d+)/)
assert nm.find()
assert nm.group('num') == '101'

// 替换
assert text.replaceFirst(/KEY-\d+/, 'XXX-n') == 'issue XXX-n and KEY-202'

10.6 外部进程

def proc = 'git log --oneline -3'.execute()      // ⚠️ Windows 上要写 ['cmd','/c','dir'].execute()
println proc.text                                 // 标准输出
def err = proc.err.text                           // 标准错误
proc.waitFor()                                    // 等待结束

11. 注解与编译期定制

Groovy 的 AST 转换注解能在编译期生成代码,是”动态语言”里写出”静态安全代码”的关键。

11.1 静态类型检查与编译

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

@TypeChecked                     // 编译期类型检查,但仍走动态调用
def safeSize(String s) { s.size() }

@CompileStatic                   // 完全静态编译:和 Java 一样的性能与检查
def fastSum(List<Integer> nums) { nums.sum() }

何时用:

  • 库代码、高性能路径 → @CompileStatic;
  • 只想 IDE/编译器帮你抓 typo,又想保留一点动态能力 → @TypeChecked;
  • ScriptRunner 里建议**至少给自己的类和方法加 @TypeChecked**,静态类型检查器能提前抓出大部分笔误。

11.2 生成样板代码

import groovy.transform.*

@Canonical                    // = @ToString + @EqualsAndHashCode + @TupleConstructor
@Immutable                    // 不可变对象(字段变 final,自动深拷贝防御)
class Money {
    BigDecimal amount
    String currency
}

def m = new Money(10, 'CNY')          // 按字段顺序构造
assert m.toString() == 'Money(10, CNY)'   // @ToString 默认不带字段名,需要时用 @ToString(includeNames=true)

@Builder
class Request {
    String url
    int timeout
}
def r = Request.builder().url('https://x').timeout(5).build()
assert r.timeout == 5

@Memoized                             // 方法级记忆化
def fib(long n) { n < 2 ? n : fib(n - 1) + fib(n - 2) }

@TailRecursive                        // 尾递归优化(防止栈溢出)
long fact(long n, long acc = 1) { n <= 1 ? acc : fact(n - 1, n * acc) }
assert fact(200) > 0

11.3 依赖注入:@Grab

@Grab('commons-io:commons-io:2.15.1')
import org.apache.commons.io.FileUtils
// 脚本运行时会自动下载 jar 并加载(Maven Central)

注意:Jira 生产环境一般禁止 @Grab(无外网 / 安全策略),应把依赖装进实例或用平台提供的类。


12. 脚本特性与语法细节

12.1 脚本里的”全局变量” vs def

// 脚本顶层不用 def:
x = 1                     // 绑定到 Binding(脚本"全局变量"),方法里也能访问
def y = 2                 // 局部变量,只在本脚本 run() 方法里可见

def readX() { x }         // ✅ 能读到 x(来自 binding)
// def readY() { y }      // ❌ 编译错:方法里看不到 y

想让”局部”变量在脚本内的方法里可见,用 @Field:

import groovy.transform.Field

@Field List cache = []    // 编译为脚本类的字段,方法里可访问
def add(v) { cache << v }

这是 ScriptRunner 脚本里最常犯的编译错误之一:顶层 def 变量在自定义方法里”看不见”。要么加 @Field,要么全走参数传递。

12.2 命令行参数

# hello.groovy
println "args: ${args}"
groovy hello.groovy a b c     # args == ['a', 'b', 'c']

12.3 数字与相等性的细节

assert 1.0 == 1                // BigDecimal 与 Integer 比值相等
assert '1' != 1                // 字符串与数字不相等(要 toInteger)
assert [1, 2] == [1, 2]        // List/Map 的 == 是深度相等(调 equals)

12.4 闭包返回值与 collect 的隐式返回

// 集合方法的闭包"最后一个表达式即返回值"——别忘了副作用会改变结果
def doubled = [1, 2, 3].collect {
    println "processing $it"   // println 返回 null!
    it * 2                     // ⭐ 必须把真正的值放最后一行
}
assert doubled == [2, 4, 6]

12.5 Groovy 3+ 的新语法一览

var x = 10                          // var 关键字
def neg = 3 !in [1, 2]              // !in
def check = !(x instanceof String)  // !instanceof
do { x-- } while (x > 5)            // do-while
def lam = (int i) -> i * 2          // Java 风格 lambda(与闭包并存)

13. 在 ScriptRunner / Jira 中写 Groovy

工作区已有的 ScriptRunner.md(功能与设置)和 HAPI.md(API 手册)是操作手册,这里只讲语言层面要注意的事。

13.1 环境

  • ScriptRunner 内嵌 Groovy(新版本为 Groovy 3),运行在 Jira JVM 里——你的脚本能调用 Jira 的所有 Java API,也能搞挂 Jira,务必在测试环境先跑;
  • 脚本编辑器支持自动补全(Ctrl+Space)、静态类型检查(可在 Settings 里开 HAPI Code Helper 提示简化写法);
  • 输出:Script Console 里 return 的值和 log.warn(...) 都会显示,**生产代码用 log 而不是 println**(ScriptRunner 提供了预置的 log 变量,走 atlassian 日志体系)。

13.2 import 是全的,但别乱改 metaClass

import com.atlassian.jira.component.ComponentAccessor

def user = ComponentAccessor.jiraUserManager.getUserByName('admin')   // 静态简写

Jira 的类都能 import;但修改 String.metaClass、Date.metaClass 之类会波及整个 Jira 实例,绝对不要在生产实例的脚本里做。

13.3 顶层变量与 @Field

import groovy.transform.Field

@Field List issues = []        // 若脚本里还要定义方法并访问它,必须 @Field

def collect(def issue) {
    issues << issue.key
}

13.4 日期用 TimeCategory 或 HAPI

use(groovy.time.TimeCategory) {
    def due = new Date() + 3.days
}
// 或用 HAPI:issue.update { dueDate = ... }(见 HAPI.md)

13.5 一个典型脚本的骨架

import groovy.transform.Field
import com.atlassian.jira.component.ComponentAccessor

// log 是 ScriptRunner 预置变量(走 atlassian 日志体系),无需自己创建

// 逻辑:把所有未指派且超过 7 天未更新的 issue 加标签
use(groovy.time.TimeCategory) {
    def cutoff = new Date() - 7.days
    def jql = "assignee is EMPTY and updated < '${cutoff.format('yyyy-MM-dd HH:mm')}'"

    Issues.search(jql).each { issue ->          // HAPI 入口,详见 HAPI.md
        issue.update {
            setLabels { add 'stale' }
        }
        log.warn "tagged ${issue.key}"
    }
}

14. 速查表与常见错误清单

14.1 语法速查

场景 写法
动态变量 def x = ...
字符串插值 "hi ${name}"
多行文本 '''...''' 或 """..."""
空集合 / 空 Map [] / [:]
Range 1..5、1..<5、'a'..'e'
追加到 List / Map 合并 list << x / map << [k: v]
负索引 list[-1]
Elvis 默认值 name ?: 'anon'
安全导航 user?.address?.city
值相等 / 引用相等 a == b / a.is(b)(Groovy 3+ ===)
成员判断 x in list
全串正则匹配 text ==~ /pattern/
遍历 list.each {}、map.each { k, v -> }
过滤 / 映射 / 聚合 findAll / collect / inject、sum
查找(可 break) find / any / every(或 for-in)
分组 groupBy、countBy
累计 inject(0) { acc, v -> }
排序不改原集合 sort(false) { it.x }
Map 构造对象 new Person(name: 'x')
命名参数方法 def f(Map m),调用 f(a: 1, b: 2)
不可变类 @Immutable
静态编译 @CompileStatic / @TypeChecked
脚本字段 @Field
资源自动关闭 file.withWriter { }、withReader、withCloseable
JSON 解析/生成 new JsonSlurper().parseText() / JsonOutput.toJson()
XML 读/写 new XmlSlurper().parseText() / MarkupBuilder
日期 DSL use(TimeCategory) { new Date() + 3.days }

14.2 十大常见错误(按踩坑频率排序)

  1. GString 当 key / 进 Set:map["a${x}"] 查不到,先 .toString()。
  2. == 语义:Groovy 的 == 是 equals();想比引用用 is() / ===。
  3. 闭包最后一行决定返回值:把 println 写最后一行,collect 收回来全是 null。
  4. each 里想 break:return 只是跳过本次;要提前退出用 find/any/for-in。
  5. sort() 原地修改:要保留原顺序用 sort(false)。
  6. 整数除法:5 / 2 == 2.5(BigDecimal);要整数商用 intdiv。
  7. 脚本顶层 def 变量方法里不可见:用 @Field 或传参。
  8. Map 字面量裸 key 是字符串:动态 key 要写 [(var): value]。
  9. null 传播:?. 只保护点号左边;链式调用中间步骤仍可能抛异常。
  10. findAll 返回新集合、collect 不去重:以为”过滤=去重”是 Python 思维惯性。

14.3 学习路线建议

  1. 用 groovyConsole 把本文 3–7 章的示例逐段敲一遍(半天);
  2. 挑一个真实数据文件(JSON/CSV),用第 5、10 章的方法做一次清洗汇总(半天);
  3. 对照 HAPI.md 写一个真实的 Jira 脚本,跑通”查询 → 更新 → 验证”(一天);
  4. 读懂 ScriptRunner.md 第 10 章里 Built-in Scripts 的源码风格,模仿改造一个(一天)。

附:参考资料