Gradle 属性命名规范 ADR-0010：org.gradle 前缀体系下的 public/internal 与特性稳定性契约

构建工具开发工具【免费下载链接】gradleAdaptable, fast automation for all项目地址https://gitcode.com/gh_mirrors/gr/gradle点击查看免费下载本文是 Gradle 仓库 architecture/standards/0010-gradle-properties-naming.md 这份架构决策记录ADR的深度解读。它定义了 Gradle 运行时与核心插件所有属性Gradle properties的统一命名规则用户仅凭属性名即可判断该属性是公开public还是内部internal、对应特性是稳定stable还是不稳定unstable。读完本文你将掌握org.gradle.internal.、org.gradle.experimental.、org.gradle.feature-name.三段式前缀的语义、生命周期约定与配套命令行选项规则并能在引入新属性时做出符合 Gradle 规范的命名决策。ADR 背景为什么需要形式化的属性命名规则Gradle 属性的定位Gradle properties 是构建工程师用来开启/关闭 Gradle 运行时或核心插件特性的开关标志flags。几乎每一个 Gradle 特性背后都有一个属性并且还会派生若干子标志sub-flags或选项提供更细粒度的控制。当前 Gradle 中的属性数量已达两位数并且会持续增长。属性为用户侧带来了精确控制与渐进式演化的好处但数量众多也带来了挑战用户的构建脚本会随时间的推移不断累积属性用户需要理解与这些特性绑定的契约——例如他们使用的到底是一个内部属性有意或无意还是一个随时可能变化的不稳定特性。维护者视角的对称问题对 Gradle 维护者而言同样需要明确引入一个属性时用户能期待什么契约、我们能承诺提供什么。随着特性经历稳定化乃至后续弃用deprecation的生命周期对应属性也应随之调整。由于属性名是用户获取即时信息的第一来源属性名及其结构本身必须承载足够的信息以设定正确预期。此前 Gradle 只有松散的命名惯例没有形式化定义这造成了一些情况下命名失去统一性并为新属性的命名过程留下了摩擦。状态与时间线该 ADR 于 2026-02-26 提出PROPOSED于 2026-03-05 被接受ACCEPTED。它属于仓库中记录架构决策的 ADR 系列之一完整的 ADR 索引见 architecture/standards/README.md。术语定义Public 与 Internal 属性的契约差异Public properties公开属性形式上属于Public API的一部分是稳定属性未经通知不得重命名或移除通常做法是弃用特性或行为本身但属性的变更不能发生在 minor 版本中必须被文档化。Internal properties内部属性不属于 Public API是不稳定属性可以在不通知的情况下重命名或移除不面向一般用户使用虽然在某些孤立场景下有助于故障排查但主要服务于 Gradle 自身的测试与开发活动其背后的行为可以随时、无通知地改变严禁出现在公开文档中。次要维度特性稳定性信息作为次要方面属性名可以携带其所代表特性的稳定性信息。随着特性经历早期原型early prototype、孵化incubation到稳定stabilization的生命周期对应属性也可能随之更新。Gradle 9.3.0 时期的实例属性名类别org.gradle.internal.operations.trace内部属性org.gradle.configuration-cache稳定特性的公开属性org.gradle.configuration-cache.parallel不稳定特性的公开属性org.gradle.configuration-cache.internal.parallel-store内部属性org.gradle.unsafe.isolated-projects不稳定特性的公开属性org.gradle.experimental.declarative-common不稳定特性的公开属性决策以用户为中心的共享命名方案新属性将遵循显式命名规则已有属性在可行处逐步更新。核心原则是以用户为中心user-centric用户仅凭属性名就能判断属性及对应特性是 public 还是 internal、stable 还是 unstable。共享命名范式org.gradle[.qualifier].feature-name.detail其中可选的qualifier限定词用于表达次要方面即特性的稳定性阶段。共享的命令行选项范式为提升命令行CLI下的使用体验部分属性可以配备补充的命令行构建选项build option且构建选项中特性的名称应与属性名中的特性名保持一致--feature-name-detail关于短形式构建选项short-form的决策则需逐案决定因为可用的短名称空间很小。Internal 属性必须以 org.gradle.internal. 开头必须以org.gradle.internal.开头这明确向用户传达这是一个非公开属性不提供任何保证不得配备命令行选项它们始终可以通过-D在命令行传入。符合规则的内置示例org.gradle.internal.operations.trace—— 用于操作追踪的调试属性org.gradle.internal.cmdline.max.length—— 命令行长度上限控制org.gradle.internal.configuration-cache.parallel-store、org.gradle.internal.configuration-cache.parallel-load—— 配置缓存并行存储/并行加载开关二者在 BuildModelParametersProvider.kt 中通过InternalOptions.ofBoolean(...)以内部选项形式解析注册印证了内部属性仅在 Gradle 内部基础设施中使用的定位。孵化前特性pre-incubation属性org.gradle.experimental.孵化前特性的属性必须以org.gradle.experimental.开头统称experimental properties实验属性该限定词明确告诉用户特性仍处于早期开发阶段尚未稳定实验属性本身必须是稳定的对应特性可以无通知地变更或移除但属性的重命名或移除必须提前通知用户不得配备命令行选项始终通过-D传入特性应离开实验阶段后才能获得构建选项。何时选择 experimental 而非 internal两者的差别在于面向公众的程度如果目的是在早期原型上收集用户反馈→ 使用实验属性如果目的是允许问题报告者在其专有环境中运行构建时获取额外的本地诊断→ 内部属性就足够了。符合规则的示例org.gradle.experimental.declarative-common声明式 DSL 公共基础设施。应当被重命名的反例以下属性不符合新规则应被重命名org.gradle.unsafe.isolated-projectsorg.gradle.unsafe.suppress-gradle-api。在仓库中可以看到这一迁移的真实轨迹IsolatedProjectsIntegrationTest.groovy 等集成测试仍以-Dorg.gradle.unsafe.isolated-projectstrue形式验证旧属性同时同一文件中也维护了org.gradle.isolated-projects.diagnostics↔org.gradle.unsafe.isolated-projects.diagnostics、org.gradle.isolated-projects.dangerously-ignore-problems↔org.gradle.unsafe.isolated-projects.dangerously-ignore-problems的新旧属性对照表见同文件 L190-L191、L205、L219直观展示了已有属性在可行处逐步更新、并为旧名保留兼容映射的落地方式。孵化中特性incubating属性org.gradle. .孵化中特性的属性必须以org.gradle.feature-name.开头这类属性没有限定词命名更简洁该属性名在特性稳定后应保持不变尽管特性处于孵化状态这些属性必须稳定若需重命名或移除无论是否随特性一起必须走弃用周期deprecation cycle且实际变更必须发生在 major 版本中由于命名不再暗示实验性质我们要确保用户能在当前属性停止生效时得到提醒底层特性仍在孵化其实际行为可以在 minor 版本中变更或移除这些属性可以配备命令行选项并应遵循上述共享命名范式。典型示例org.gradle.configuration-cache.parallel—— 公开但特性不稳定的属性其命名不含internal或experimental前缀仅由特性名configuration-cache加细节parallel构成。稳定特性stable属性org.gradle. .稳定特性的属性必须以org.gradle.feature-name.开头同样没有限定词命名简洁这是合理默认因为大多数特性都属于此类这些属性必须稳定重命名或移除须走弃用周期实际变更须发生在 major 版本可以配备命令行选项并遵循共享命名范式。典型示例org.gradle.cachingorg.gradle.configuration-cache。决策后果三条必须遵守的硬性规则该 ADR 最终沉淀为三条可操作、可审查的强制性约定内部属性必须以org.gradle.internal.开头孵化前特性属性必须以org.gradle.experimental.开头孵化中与稳定特性属性必须以org.gradle.feature-name.开头。这三条规则构成了一份简洁的命名决策表先判定属性所属类别internal / experimental / incubating / stable再套用对应前缀内部与实验属性一律不配命令行选项通过-D传递孵化与稳定属性可配选项且特性名必须与属性名一致。任何新属性的引入都应先对照此表自查再进入实现与文档流程。附录如何对照本规范审查仓库中的属性如需在当前仓库中快速定位属性定义与测试证据可以参考以下入口ADR 原文architecture/standards/0010-gradle-properties-naming.mdADR 目录与格式约定architecture/standards/README.md采用轻量 Markdown ADR 模板格式见 0001-use-architectural-decision-records.md新旧属性名兼容映射的集成测试IsolatedProjectsIntegrationTest.groovy内部选项的解析与注册BuildModelParametersProvider.kt。赞分享构建工具开发工具【免费下载链接】gradleAdaptable, fast automation for all项目地址https://gitcode.com/gh_mirrors/gr/gradle点击查看免费下载相关推荐Druid SQL 解析器特性开关命名规范LexerFeature 与 ParserFeature 的确定性命名契约Druid SQL 解析器特性开关命名规范LexerFeature 与 ParserFeature 的确定性命名契约 导读 本文面向 Druid阿里云 Da数据库后端Unleash 前端接口命名规范以 I 前缀的 TypeScript 接口与 Props 命名约定ADR 实践指南Unleash 前端接口命名规范以 I 前缀的 TypeScript 接口与 Props 命名约定ADR 实践指南 Unleash 开源特性管理平台的前端后端faster-whisper 语音转文字快速指南比原版 Whisper 快 4 倍faster whisper 语音转文字快速指南比原版 Whisper 快 4 倍 faster whisper 是基于 CTranslate2 推理引擎对人工智能语音本地部署上一篇深入理解Litter的循环引用处理机制避免Go调试中的无限递归下一篇DiffSynth Studio终极扩展开发指南FastBlend与ESRGAN插件深度集成创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考