Spotless项目中的Gradle构建缓存失效问题分析与解决方案

问题背景

在Gradle构建系统中，Spotless作为代码格式化工具被广泛使用。近期在Spotless 7.0.0.BETA1版本中发现了一个影响Gradle构建缓存命中率的问题：当连续两次运行构建且代码未更改时，spotlessJava任务无法获得缓存命中。

问题本质

问题的核心在于SpotlessTask.steps输入属性的序列化/反序列化不一致性。具体表现为：

1. 任务输入属性steps被标记为Gradle输入(@Input)
2. 该集合的序列化结果在不同构建运行间存在差异
3. 差异主要源于EclipseJdtFormatterStep中使用的EquoBasedStepBuilder
4. EquoBasedStepBuilder序列化时包含了设置文件的绝对路径引用

技术细节分析

序列化机制的问题

Spotless采用了FormatterStepSerializationRoundtrip机制来处理步骤的序列化，其中包含两个关键部分：

1. RoundtripState：支持包含绝对路径的完整序列化
2. EqualityState：用于equals和hashCode计算，不包含绝对路径

这种设计原本是为了同时满足：

• 可重定位的构建缓存(忽略绝对路径)
• 配置缓存(支持完整的往返序列化)

Gradle的指纹机制

Gradle在计算任务输入指纹时，实际上使用了Java序列化结果而非对象的equals/hashCode方法。这就导致了：

1. 即使EqualityState相同(equals返回true)
2. 由于RoundtripState中包含的绝对路径不同
3. 序列化结果不同
4. 最终导致Gradle认为输入不同而产生缓存未命中

解决方案演进

初步修复方案

最初的修复思路是：

1. 将集合配置为transient
2. 添加仅包含文件名的集合作为输入
3. 确保输入表示的一致性

最终解决方案

在Spotless 7.0.0.BETA3中，通过以下方式彻底解决了问题：

1. 重新设计了序列化机制
2. 确保即使在不同位置运行构建
3. 相同配置产生的序列化结果一致
4. 同时保留了必要的配置缓存支持

经验总结

这个案例为我们提供了几个重要的技术启示：

1. Gradle构建缓存机制对任务输入的序列化方式非常敏感
2. 在设计可缓存任务时，必须确保输入属性的序列化结果稳定性
3. 绝对路径等环境相关因素需要特别处理
4. 配置缓存和构建缓存的需求可能存在冲突，需要仔细权衡

最佳实践建议

基于此问题的解决经验，建议开发者在实现Gradle任务时：

1. 避免在可缓存任务的输入中包含绝对路径
2. 考虑使用相对路径或内容哈希作为替代
3. 对复杂对象的序列化行为进行充分测试
4. 验证在不同环境下的构建缓存命中情况

通过遵循这些原则，可以构建出更加稳定可靠的Gradle任务和插件。