解析策略

目录

属性
方法
脚本块
属性详情
方法详情
API 文档解析策略

定义了依赖解析的策略。例如，强制某些依赖版本、替换、冲突解决或快照超时。

示例

plugins {
    id 'java' // so that there are some configurations
}

configurations.all {
  resolutionStrategy {
    // fail eagerly on version conflict (includes transitive dependencies)
    // e.g. multiple different versions of the same dependency (group and name are equal)
    failOnVersionConflict()

    // prefer modules that are part of this build (multi-project or composite build) over external modules
    preferProjectModules()

    // force certain versions of dependencies (including transitive)
    //  *append new forced modules:
    force 'asm:asm-all:3.3.1', 'commons-io:commons-io:1.4'
    //  *replace existing forced modules with new ones:
    forcedModules = ['asm:asm-all:3.3.1']

    // add dependency substitution rules
    dependencySubstitution {
      substitute module('org.gradle:api') using project(':api')
      substitute project(':util') using module('org.gradle:util:3.0')
    }

    // cache dynamic versions for 10 minutes
    cacheDynamicVersionsFor 10*60, 'seconds'
    // don't cache changing modules at all
    cacheChangingModulesFor 0, 'seconds'
  }
}

属性

属性描述
能力解析

能力解析策略。

组件选择

当前配置的版本选择规则对象。

依赖替换

为此配置设置的依赖替换规则集。

强制模块

返回当前配置的强制模块。有关强制版本的更多信息，请参阅 ResolutionStrategy.force(java.lang.Object[])

方法

方法描述
激活依赖锁定()

激活 Gradle 中的依赖锁定支持。一旦开启配置，解析结果可以被保存并在后续构建中重复使用。这在使用动态版本时可以实现可重现的构建。

cacheChangingModulesFor(值, 单位)

设置可变模块的缓存时长，单位表示为字符串。

cacheChangingModulesFor(值, 单位)

设置可变模块的缓存时长。

cacheDynamicVersionsFor(值, 单位)

设置动态版本的缓存时长，单位表示为字符串。

cacheDynamicVersionsFor(值, 单位)

设置动态版本的缓存时长。

componentSelection(动作)

componentSelection 块提供了过滤或阻止某些组件出现在解析结果中的规则。

停用依赖锁定()

停用 Gradle 中的依赖锁定支持。

dependencySubstitution(动作)

配置此配置的依赖替换规则集。该动作接收一个 DependencySubstitutions 实例，然后可以配置替换规则。

禁用依赖验证()

禁用此配置的依赖验证。在禁用验证时应始终小心，尤其是避免禁用插件的验证，因为插件可能会利用这一点来禁用验证本身。

eachDependency(规则)

添加一个依赖替换规则，该规则在配置解析时针对每个依赖项（包括传递依赖项）触发。该动作接收一个 DependencyResolveDetails 实例，可用于查找正在解析的依赖项并影响解析过程。示例

启用依赖验证()

为该配置启用依赖验证。

在可变版本上失败()

如果调用此方法，Gradle 将确保没有可变版本参与解析。这可用于确保构建可重现的情况，而不依赖于依赖锁定。

在动态版本上失败()

如果调用此方法，Gradle 将确保在生成的依赖图中没有使用动态版本。实际上，这意味着如果解析的依赖图包含一个模块，并且参与该模块选择的版本中至少包含一个动态版本，则如果解析结果可能因此版本选择器而改变，则解析将失败。这可用于确保构建可重现的情况，而不依赖于依赖锁定。

在不可重现解析上失败()

配置 Gradle 以在解析结果预计不稳定（即包含动态版本或可变版本，因此结果可能会因构建执行时间而异）时使构建失败。此方法等同于同时调用 ResolutionStrategy.failOnDynamicVersions() 和 ResolutionStrategy.failOnChangingVersions()。

在版本冲突时失败()

在冲突情况下，Gradle 默认使用冲突版本中最新的版本。但是，您可以更改此行为。使用此方法配置解析以在任何版本冲突时立即失败，例如在同一个 Configuration 中存在同一依赖项（组和名称相同）的多个不同版本。检查包括一级依赖项和传递依赖项。请参见下面的示例

force(模块版本选择器表示法)

允许强制使用某些依赖项的版本，包括传递依赖项。追加新的强制模块以在解析依赖项时考虑。

获取使用全局依赖替换规则()

Gradle 隐式注册整个构建树中所有配置的依赖替换规则，以查找其他包含构建中的项目。这些规则默认始终处于活动状态。但是，在某些情况下，某个配置在解析时不应应用这些规则。例如，如果应发现模块的二进制版本，而该模块也由另一个构建中的项目表示。此属性可用于禁用这些全局替换规则。

优先项目模块()

Gradle 可以纯粹通过版本号解决冲突，或者优先考虑项目依赖项而不是二进制依赖项。默认是按版本号。

sortArtifacts(排序顺序)

指定已解析构件的排序顺序。选项包括

脚本块

无脚本块

属性详情

CapabilitiesResolution capabilitiesResolution (只读)

能力解析策略。

ComponentSelectionRules componentSelection (只读)

当前配置的版本选择规则对象。

DependencySubstitutions dependencySubstitution (只读)

为此配置设置的依赖替换规则集。

Set<ModuleVersionSelector> forcedModules

返回当前配置的强制模块。有关强制版本的更多信息，请参阅 ResolutionStrategy.force(java.lang.Object[])

方法详情

ResolutionStrategy activateDependencyLocking()

激活 Gradle 中的依赖锁定支持。一旦开启配置，解析结果可以被保存并在后续构建中重复使用。这在使用动态版本时可以实现可重现的构建。

void cacheChangingModulesFor(int 值, String 单位)

设置可变模块的缓存时长，单位表示为字符串。

这是 ResolutionStrategy.cacheChangingModulesFor(int, java.util.concurrent.TimeUnit) 的便捷方法，单位表示为字符串。单位通过调用 TimeUnit 的 valueOf(String) 方法与大写的字符串值来解析。

void cacheChangingModulesFor(int 值, TimeUnit 单位)

设置可变模块的缓存时长。

Gradle 缓存可变模块的内容和构件。默认情况下，这些缓存值保留 24 小时，之后缓存条目过期并再次解析模块。

使用此方法提供自定义过期时间，在此时间之后，任何可变模块的缓存条目都将过期。

void cacheDynamicVersionsFor(int 值, String 单位)

设置动态版本的缓存时长，单位表示为字符串。

这是 ResolutionStrategy.cacheDynamicVersionsFor(int, java.util.concurrent.TimeUnit) 的便捷方法，单位表示为字符串。单位通过调用 TimeUnit 的 valueOf(String) 方法与大写的字符串值来解析。

void cacheDynamicVersionsFor(int 值, TimeUnit 单位)

设置动态版本的缓存时长。

Gradle 维护一个动态版本 => 已解析版本（即 2.+ => 2.3）的缓存。默认情况下，这些缓存值保留 24 小时，之后缓存条目过期并再次解析动态版本。

使用此方法提供自定义过期时间，在此时间之后，任何动态版本的缓存值都将过期。

ResolutionStrategy componentSelection(Action<? super ComponentSelectionRules> 动作)

componentSelection 块提供了过滤或阻止某些组件出现在解析结果中的规则。

ResolutionStrategy deactivateDependencyLocking()

停用 Gradle 中的依赖锁定支持。

ResolutionStrategy dependencySubstitution(Action<? super DependencySubstitutions> 动作)

配置此配置的依赖替换规则集。该动作接收一个 DependencySubstitutions 实例，然后可以配置替换规则。

示例

// add dependency substitution rules
configurations.all {
  resolutionStrategy.dependencySubstitution {
    // Substitute project and module dependencies
    substitute module('org.gradle:api') using project(':api')
    substitute project(':util') using module('org.gradle:util:3.0')

    // Substitute one module dependency for another
    substitute module('org.gradle:api:2.0') using module('org.gradle:api:2.1')
  }
}

ResolutionStrategy disableDependencyVerification()

禁用此配置的依赖验证。在禁用验证时应始终小心，尤其是避免禁用插件的验证，因为插件可能会利用这一点来禁用验证本身。

ResolutionStrategy eachDependency(Action<? super DependencyResolveDetails> 规则)

添加一个依赖替换规则，该规则在配置解析时针对每个依赖项（包括传递依赖项）触发。该动作接收一个 DependencyResolveDetails 实例，可用于查找正在解析的依赖项并影响解析过程。示例

configurations {
  compileClasspath.resolutionStrategy {
    eachDependency { DependencyResolveDetails details ->
      //specifying a fixed version for all libraries with 'org.gradle' group
      if (details.requested.group == 'org.gradle') {
        details.useVersion '1.4'
      }
    }
    eachDependency { details ->
      //multiple actions can be specified
      if (details.requested.name == 'groovy-all') {
         //changing the name:
         details.useTarget group: details.requested.group, name: 'groovy', version: details.requested.version
      }
    }
  }
}

规则按声明顺序评估。在应用强制模块后评估规则（参见 ResolutionStrategy.force(java.lang.Object[])

ResolutionStrategy enableDependencyVerification()

为该配置启用依赖验证。

ResolutionStrategy failOnChangingVersions()

如果调用此方法，Gradle 将确保没有可变版本参与解析。这可用于确保构建可重现的情况，而不依赖于依赖锁定。

ResolutionStrategy failOnDynamicVersions()

如果调用此方法，Gradle 将确保在生成的依赖图中没有使用动态版本。实际上，这意味着如果解析的依赖图包含一个模块，并且参与该模块选择的版本中至少包含一个动态版本，则如果解析结果可能因此版本选择器而改变，则解析将失败。这可用于确保构建可重现的情况，而不依赖于依赖锁定。

ResolutionStrategy failOnNonReproducibleResolution()

配置 Gradle 以在解析结果预计不稳定（即包含动态版本或可变版本，因此结果可能会因构建执行时间而异）时使构建失败。此方法等同于同时调用 ResolutionStrategy.failOnDynamicVersions() 和 ResolutionStrategy.failOnChangingVersions()。

ResolutionStrategy failOnVersionConflict()

在冲突情况下，Gradle 默认使用冲突版本中最新的版本。但是，您可以更改此行为。使用此方法配置解析以在任何版本冲突时立即失败，例如在同一个 Configuration 中存在同一依赖项（组和名称相同）的多个不同版本。检查包括一级依赖项和传递依赖项。请参见下面的示例

plugins {
    id 'java' // so that there are some configurations
}

configurations.all {
  resolutionStrategy.failOnVersionConflict()
}

ResolutionStrategy force(Object... 模块版本选择器表示法)

允许强制使用某些依赖项的版本，包括传递依赖项。追加新的强制模块以在解析依赖项时考虑。

它接受以下表示法

  • 格式为“group:name:version”的字符串，例如：“org.gradle:gradle-core:1.0”
  • ModuleVersionSelector 的实例
  • 任何上述内容的集合或数组将自动展平

示例

plugins {
    id 'java' // so that there are some configurations
}

configurations.all {
  resolutionStrategy.force 'asm:asm-all:3.3.1', 'commons-io:commons-io:1.4'
}

Property<Boolean> getUseGlobalDependencySubstitutionRules()

Gradle 隐式注册整个构建树中所有配置的依赖替换规则，以查找其他包含构建中的项目。这些规则默认始终处于活动状态。但是，在某些情况下，某个配置在解析时不应应用这些规则。例如，如果应发现模块的二进制版本，而该模块也由另一个构建中的项目表示。此属性可用于禁用这些全局替换规则。

void preferProjectModules()

Gradle 可以纯粹通过版本号解决冲突，或者优先考虑项目依赖项而不是二进制依赖项。默认是按版本号。

这适用于一级和传递依赖项。请参见下面的示例

plugins {
    id 'java' // so that there are some configurations
}

configurations.all {
  resolutionStrategy.preferProjectModules()
}

void sortArtifacts(SortOrder 排序顺序)

指定已解析构件的排序顺序。选项包括

  • <UNHANDLED-LINK>SortOrder#DEFAULT</UNHANDLED-LINK> : 不指定排序顺序。Gradle 将按默认顺序提供构件。
  • <UNHANDLED-LINK>SortOrder#CONSUMER_FIRST</UNHANDLED-LINK> : 消费组件的构件应在依赖项的构件之前出现。
  • <UNHANDLED-LINK>SortOrder#DEPENDENCY_FIRST</UNHANDLED-LINK> : 消费组件的构件应在依赖项的构件之后出现。

将尽力按照提供的 SortOrder 对构件进行排序，但在存在依赖循环的情况下不作保证。注意：对于特定 Gradle 版本，构件排序将保持一致。相同输入的多次解析将导致相同顺序的相同输出。