Gradle设置器语法选用指南：插件开发时何时用哪种语法？

作为Gradle插件开发者，这三种语法本质是基于属性类型和API设计意图的差异化实现，核心是让DSL更贴合Kotlin编程习惯，同时满足不同的配置需求：

1. foo("foo")：增量式集合配置的语法糖 #

这种写法专门针对需要增量添加元素的集合属性（比如ListProperty、SetProperty）。插件开发时，我们会给这类属性封装可变参数的扩展函数，内部调用集合的add或addAll方法，避免直接赋值覆盖原有内容。

举个实现例子：

// 插件内定义ListProperty
val foo: ListProperty<String> = objects.listProperty(String::class.java)

// 为DSL块提供可变参数扩展函数
fun ConfigBlock.foo(vararg values: String) {
    this.foo.addAll(values.toList())
}

对比直接foo = listOf("foo1", "foo2")会完全替换原有集合，foo("foo1", "foo2")的语义是追加元素，更符合依赖声明、资源文件配置这类需要逐步添加的场景（比如implementation("com.x:y:1.0")就是同款逻辑）。

2. bar = "bar"：委托属性的直观赋值 #

这种是Kotlin委托属性结合Gradle Property<T>接口实现的语法糖。当插件里把Property<T>类型的属性委托给Kotlin的var属性时，就可以用普通赋值语法，内部自动调用Property.set()方法。

实现示例：

// 插件内定义StringProperty
val bar: StringProperty = objects.property(String::class.java)

// 通过委托让DSL支持直接赋值
var ConfigBlock.bar: String by bar

这种写法最符合Kotlin开发者的日常习惯，适合单一值的属性（比如版本号、输出路径），语义清晰，代码简洁。

3. baz.set("baz")：直接调用Property接口方法 #

Property<T>接口本身就自带set()方法，以下两种场景会用到这种写法：

• 插件开发者没有把属性委托成Kotlin的var属性（比如对外暴露的是val类型的Property<T>实例）；
• 需要在DSL块外延迟赋值，或者更明确地表达“替换属性值”的语义。

比如插件里这么定义：

// 插件内定义属性，但不做委托
val baz: StringProperty = objects.property(String::class.java)

// DSL块内只暴露Property实例
fun ConfigBlock.baz(): StringProperty = baz

这时在DSL里就只能用baz.set("baz")来赋值。另外对于集合属性，qux.set(listOf("qux1", "qux2"))的语义是完全替换整个集合，和foo()的增量添加形成明确区分。

插件开发时的设计原则总结 #

• 单一值属性：优先用委托属性实现bar = value的语法，贴合Kotlin习惯；
• 集合属性：需要增量添加就提供可变参数扩展函数foo(vararg values)，需要替换整个集合则支持foo = listOf(...)或foo.set(listOf(...))；
• 若属性是只读但允许设置值（比如内部维护状态，对外仅暴露Property实例），则用baz.set(value)的写法。

内容的提问来源于stack exchange，提问作者Marco Eckstein