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 十大常见错误(按踩坑频率排序)
- GString 当 key / 进 Set:
map["a${x}"]查不到,先.toString()。 ==语义:Groovy 的==是equals();想比引用用is()/===。- 闭包最后一行决定返回值:把
println写最后一行,collect收回来全是null。 each里想 break:return只是跳过本次;要提前退出用find/any/for-in。sort()原地修改:要保留原顺序用sort(false)。- 整数除法:
5 / 2 == 2.5(BigDecimal);要整数商用intdiv。 - 脚本顶层
def变量方法里不可见:用@Field或传参。 - Map 字面量裸 key 是字符串:动态 key 要写
[(var): value]。 null传播:?.只保护点号左边;链式调用中间步骤仍可能抛异常。findAll返回新集合、collect不去重:以为”过滤=去重”是 Python 思维惯性。
14.3 学习路线建议
- 用
groovyConsole把本文 3–7 章的示例逐段敲一遍(半天); - 挑一个真实数据文件(JSON/CSV),用第 5、10 章的方法做一次清洗汇总(半天);
- 对照
HAPI.md写一个真实的 Jira 脚本,跑通”查询 → 更新 → 验证”(一天); - 读懂
ScriptRunner.md第 10 章里 Built-in Scripts 的源码风格,模仿改造一个(一天)。
附:参考资料
- 官方文档:https://groovy-lang.org/documentation.html(语言规范、GDK API)
- Apache Groovy 源码中的
DefaultGroovyMethods(集合扩展方法的”本体”) - 工作区配套文档:
ScriptRunner.md(平台功能)、HAPI.md(Jira API 手册)、JiraDeveloper.md(原生开发)