第五十章. 依赖管理

依赖管理在从一个构建系统迁移到另一个的过程中尤其具有挑战性。如果你从一个像 Ant 或 Maven 这样的工具迁移到 Gradle，你可能会面临一些困难的情况。例如，一个常见的模式是，有一个 Ant 项目，而它保存在文件系统中的一些 jar 文件缺少版本号。其他的构建系统在迁移之前需要对这种方法进行大量的替换。使用 Gradle，你可以让你的新构建适配任何现有的依赖来源或依赖元数据。这使得增量迁移到 Gradle 比其他的要容易得多。在大多数的大项目中，构建迁移和对发展过程的任何更改都是增量的，因为大多数组织不能负担得起停止一切事情并迁移到依赖管理的构建工具的想法。
Dependency management can be particularly challenging during a migration from one build system to another. If you are migrating from a tool like Ant or Maven to Gradle, you may be faced with some difficult situations. For example, one common pattern is an Ant project with version-less jar files stored in the filesystem. Other build systems require a wholesale replacement of this approach before migrating. With Gradle, you can adapt your new build to any existing source of dependencies or dependency metadata. This makes incremental migration to Gradle much easier than the alternative. On most large projects, build migrations and any change to development process is incremental because most organizations can't afford to stop everything and migrate to a build tool's idea of dependency management.

即使你的项目使用一个自定义的依赖管理系统，或者是一些像 Eclipse 作为依赖管理的主数据的 .classpath 文件，那么可以很容易地写一个 Gradle 插件在 Gradle 中使用此数据。出于迁移的目的，这是在 Gradle 中的一种常用技术。（但是，一旦你已经迁移，远离 .classpath 文件，直接使用 Gradle 的依赖管理功能会是一个好主意。）
Even if your project is using a custom dependency management system or something like an Eclipse .classpath file as master data for dependency management, it is very easy to write a Gradle plugin to use this data in Gradle. For migration purposes this is a common technique with Gradle. (But, once you've migrated, it might be a good idea to move away from a .classpath file and use Gradle's dependency management features directly.)

令人啼笑皆非的是，以其丰富的开源组件库著称的语言，Java 竟然没有库或者版本的概念。在 Java 中，没有标准的方法来告诉 JVM 你使用的是 3.0.5 版本的 Hibernate，也没有标准的方法来表明 foo-1.0.jar 依赖于 bar-2.0.jar。这导致了外部的解决方案通常都会基于构建工具。目前最受欢迎的解决方案是 Maven 和 Ivy。Maven 提供了一个完整的构建系统，而 Ivy 则完全着眼于依赖管理。
It is ironic that in a language known for its rich library of open source components that Java has no concept of libraries or versions. In Java, there is no standard way to tell the JVM that you are using version 3.0.5 of Hibernate, and there is no standard way to say that foo-1.0.jar depends on bar-2.0.jar. This has led to external solutions often based on build tools. The most popular ones at the moment are Maven and Ivy. While Maven provides a complete build system, Ivy focuses solely on dependency management.

这两种工具都依赖于描述符 XML 文件，包含有关具体某个 jar 的依赖的信息。这两者都使用了存储库，在存储库中实际的 jar 文件和它们的描述文件都放在一起，而且这两者通过窗口或其他的方式都提供了 jar 版本冲突的解决方案。这两者都已成为解决依赖冲突的标准，而 Gradle 最初使用的是 Ivy 引擎的依赖管理。Gradle 已经取代了 Ivy 上的直接依赖，而采用了原生的 Gradle 依赖解决引擎，它支持许多的依赖解决方案的方法，包括 POM 文件和 Ivy 描述文件。
Both tools rely on descriptor XML files, which contain information about the dependencies of a particular jar. Both also use repositories where the actual jars are placed together with their descriptor files, and both offer resolution for conflicting jar versions in one form or the other. Both have emerged as standards for solving dependency conflicts, and while Gradle originally used Ivy under the hood for its dependency management. Gradle has replaced this direct dependency on Ivy with a native Gradle dependency resolution engine which supports a range of approaches to dependency resolution including both POM and Ivy descriptor files.

在文件名中库的版本必须是容易辨认的。Jar 的版本通常是在清单文件中，当你要检查一个项目时它并不显而易见。如果有人让你看 20 个 jar 文件，你更喜欢哪一种？一个文件命名为 beanutils-beanutils-1.3.jar 的集合，还是文件命名为 spring.jar 的集合？如果依赖的文件名称带有版本号，那么将更容易快速确定依赖的版本。
The version of a library must be easy to recognize in the filename. While the version of a jar is usually in the Manifest file, it isn't readily apparent when you are inspecting a project. If someone asks you to look at a collection of 20 jar files, which would you prefer? A collection of files with names like commons-beanutils-1.3.jar or a collection of files with names like spring.jar? If dependencies have file names with version numbers it is much easier to quickly identify the versions of your dependencies.

如果版本不清楚，你可能引入一些很难找到的微妙的错误。例如可能有一个项目使用 Hibernate 2.5。想一下一个开发人员决定在她的机器安装 3.0.5 的版本，以修复一个关键的安全 bug，但她忘记通知其他团队这个变化。她可能成功地解决了这个安全 bug，但她也可能有引入一些 bug 到代码库中，因为项目用到了 Hibernate 现在弃用的功能。一周后在集成的机器上可能会有一个异常，而这个异常无法在任何人的机器上复现。然后多个开发人员花了数天的时间在这个问题上，终于意识到如果他们知道 Hibernate 已经从 2.5 升级到 3.0.5，这个错误会很容易发现。
If versions are unclear you can introduce subtle bugs which are very hard to find. For example there might be a project which uses Hibernate 2.5. Think about a developer who decides to install version 3.0.5 of Hibernate on her machine to fix a critical security bug but forgets to notify others in the team of this change. She may address the security bug successfully, but she also may have introduced subtle bugs into a codebase that was using a now-deprecated feature from Hibernate. Weeks later there is an exception on the integration machine which can't be reproduced on anyone's machine. Multiple developers then spend days on this issue only finally realising that the error would have easy to uncover if they knew that Hibernate had been upgraded from 2.5 to 3.0.5.

在 jar 文件中包含版本号提高了在你的项目中的表现，并且让它们更易于维护。这种做法也减少了潜在的错误。
Versions in jar names increase the expressiveness of your project and make them easier to maintain. This practice also reduces the potential for error.

传递依赖管理是一种技术，让你的项目能够依赖那些反过来依赖其他库的库。这种递归模式传递依赖的结果是，在一个依赖树中，会包含你的项目的第一级依赖、第二级依赖，等等。如果你不把你的依赖作为层次结构树的第一级和第二级依赖的模型，那么在对未组织的依赖进行混乱的组装之后，就会很容易地失去控制。考虑 Gradle 项目本身，虽然 Gradle 仅有几个直接的第一级依赖，当 编译 Gradle 时在它的类路径上会需要超过一百个的依赖。在更大的规模上，使用 Spring，Hibernate和其他的库，旁边数百或数千个内部项目的企业应用，也有非常大的依赖树。
Transitive dependency management is a technique that enables your project to depend on libraries which, in turn, depend on other libraries. This recursive pattern of transitive dependencies results in a tree of dependencies including your project's first-level dependencies, second-level dependencies, and so on. If you don't model your dependencies as a hierarchical tree of first-level and second-level dependencies it is very easy to quickly lose control over an assembled mess of unstructured dependencies. Consider the Gradle project itself, while Gradle only has a few direct, first-level dependencies, when Gradle is compiled it needs more that one hundred dependencies on the classpath. On a far larger scale, Enterprise projects using Spring, Hibernate, and other libraries, alongside hundreds or thousands of internal projects can have very large dependency trees.

当这些大的依赖树需要更改时，你经常得解决一些依赖的版本冲突。比如说一个开源库需要一个日志库的一个版本，而另一个库需要日志库的另一个版本。Gradle 和其他的构建工具都能够处理这种关系树和解决冲突问题，但不同的是，Gradle 让你可以控制传递依赖和冲突的解决。
When these large dependency trees need to change, you'll often have to solve some dependency version conflicts. Say one open source library needs one version of a logging library and a another uses an alternative version. Gradle and other build tools all have the ability to solve this dependency tree and resolve conflicts, but what differentiates Gradle is the control it gives you over transitive dependencies and conflict resolution.

虽然你可以尝试手动管理这个问题，你很快就会发现这种方法不能扩展。如果你想要摆脱第一级的依赖，你不能真正确定还有哪些 jar 文件你是需要删除的。第一级依赖的依赖项也可能是第一级依赖本身，或者也可能是另一个第一级依赖的传递依赖。如果你尝试自己管理传递依赖，最终的结果是你的构建会变得很脆弱：没有人敢去改变你的依赖，因为破坏构建的风险太高。项目的类路径会变得一片狼藉，并且，如果类路径出现问题时，那简直就是人间地狱。
While you could try to manage this problem manually, you will quickly find that this approach doesn't scale. If you want to get rid of a first level dependency you really can't be sure which other jars you should remove. A dependency of a first level dependency might also be a first level dependency itself, or it might be a transitive dependency of yet another first level dependency. If you try to manage transitive dependencies yourself, the end of the story is that your build becomes brittle: no one dares to change your dependencies because the risk of breaking the build is too high. The project classpath becomes a complete mess, and, if a classpath problem arises, hell on earth invites you for a ride.

Gradle 向你提供了不同的方式来表达第一级的和传递的依赖。通过 Gradle 你可以混合使用和适配一些方法；例如，你可以在 SCM 中存储你的 jar 包，而不需要 XML 描述符文件，并且仍然使用传递依赖管理。
Gradle offers you different ways to express first-level and transitive dependencies. With Gradle you can mix and match approaches; for example, you could store your jars in an SCM without XML descriptor files and still use transitive dependency management.

相同的 jar 包的冲突版本应该被检测到，并且要么解决，要么抛出异常。如果你不使用传递依赖管理，版本冲突没被发现，那么在类路径中无法预测的顺序，将导致不知道会使用哪一个版本的依赖。对于许多开发人员都会更改依赖的大型项目，成功的构建将会少之又少，因为依赖的顺序可能会直接影响到构建是否成功（或者在产品中是否会出现一个 bug）。
Conflicting versions of the same jar should be detected and either resolved or cause an exception. If you don't use transitive dependency management, version conflicts are undetected and the often accidental order of the classpath will determine what version of a dependency will win. On a large project with many developers changing dependencies, successful builds will be few and far between as the order of dependencies may directly affect whether a build succeeds or fails (or whether a bug appears or disappears in production).

如果你还没有处理过在类路径中 jar 包版本冲突的麻烦，这里有一个小趣闻等着你。在一个有30个子模块的大型项目中，向子项目添加的一个依赖改变了类路径的顺序， Spring 2.5 与老的 2.4 版本的顺序被交换。虽然可以继续构建，开发者已经开始注意到在生产中出现了各种令人惊讶（和惊人可怕）的 bug。然而，更糟糕的是，无意降低版本的 Spring 向系统引入了几个安全漏洞，现在需要在整个组织中进行全面的安全审核。
If you haven't had to deal with the curse of conflicting versions of jars on a classpath, here is a small anecdote of the fun that awaits you. In a large project with 30 submodules, adding a dependency to a subproject changed the order of a classpath, swapping Spring 2.5 for an older 2.4 version. While the build continued to work, developers were starting to notice all sorts of surprising (and surprisingly awful) bugs in production. Worse yet, this unintentional downgrade of Spring introduced several security vulnerabilities into the system, which now required a full security audit throughout the organization.

总之，版本冲突是很不好的，你应该管理你的传递依赖，以避免它们。你也可能想要了解版本冲突用到的地方，并且在你的整个组织中统一一个指定版本的依赖。通过一个好的冲突报告工具，像 Gradle，这些信息可以用于与整个组织沟通，并在一个单一的版本上实现标准化。如果你觉得你不会发生版本冲突，再想想。 不同的第一级依赖，依赖于一系列不同的重叠版本的其他依赖，这种情况是很常见的，而 JVM 还不能提供简单的方法，使得能在类路径中让相同的 jar 包可以有不同的版本（请参阅第 50.1.2 节，“依赖管理和 Java”）。
In short, version conflicts are bad, and you should manage your transitive dependencies to avoid them. You might also want to learn where conflicting versions are used and consolidate on a particular version of a dependency across your organization. With a good conflict reporting tool like Gradle, that information can be used to communicate with the entire organization and standardize on a single version. If you think version conflicts don't happen to you, think again. It is very common for different first-level dependencies to rely on a range of different overlapping versions for other dependencies, and the JVM doesn't yet offer an easy way to have different versions of the same jar in the classpath (see Section 50.1.2, “Dependency management and Java”).

Gradle 提供了以下的冲突解决策略：
Gradle offers the following conflict resolution strategies:

虽然上面介绍的策略通常足够解决大部分的冲突，但是 Gradle 也提供更细粒度的机制，以解决版本冲突：
While the strategies introduced above are usually enough to solve most conflicts, Gradle provides more fine-grained mechanisms to resolve version conflicts:

为了解决版本冲突问题，报告依赖关系图也是很有帮助的。这些报告是依赖管理的另一个功能。
To deal with problems due to version conflicts, reports with dependency graphs are also very helpful. Such reports are another feature of dependency management.

有许多情况，是你想要使用一个特定依赖的最新版本，或者是某个版本范围内的最新版。这可以是在开发中需要，或者你可能正在开发一个库，它被设计为使用一个范围内的依赖版本。你可以通过使用动态版本很容易地依赖这些不断变化的依赖。一个动态的版本可以是一个版本范围（例如2.+），也可以是表示可用的最新版本的占位符（例如latest.integration）。
There are many situation when you want to use the latest version of a particular dependency, or the latest in a range of versions. This can be a requirement during development, or you may be developing a library that is designed to work with a range of dependency versions. You can easily depend on these constantly changing dependencies by using a dynamic version. A dynamic version can be either a version range (e.g. 2.+) or it can be a placeholder for the latest version available (e.g. latest.integration).

另外，你请求的模块随着时间推移，即使是同一版本，有时也可能改变了。这种变化模块的类型的一个例子是 MavenSNAPSHOT模块，它总是指向最新发布的构件。换句话说，一个标准的 Maven snapshot 是一个这样的模块，它永远不会不变，可以说，它是“不断变化的模块”。
Alternatively, sometimes the module you request can change over time, even for the same version. An example of this type of changing module is a Maven SNAPSHOT module, which always points at the latest artifact published. In other words, a standard Maven snapshot is a module that never stands still so to speak, it is a "changing module".

动态版本和变化模块的主要区别是，当你解析一个动态版本时，你会得到真正的、 静态的版本作为模块名称。当你解析一个变化模块时，这个 artifacts 使用你请求的版本进行命名，但下层的 artifacts 可能随时会有变化。
The main difference between a dynamic version and a changing module is that when you resolve a dynamic version, you'll get the real, static version as the module name. When you resolve a changing module, the artifacts are named using the version you requested, but the underlying artifacts may change over time.

默认情况下，Gradle 对动态版本和变化模块的缓存时间是24小时。你可以使用命令行选项重写默认的缓存模式。你可以通过resolution strategy修改你的构建的缓存到期时间（见第 50.9.3 节，“调整控制依赖缓存”）。
By default, Gradle caches dynamic versions and changing modules for 24 hours. You can override the default cache modes using command line options. You can change the cache expiry times in your build using the resolution strategy (see Section 50.9.3, “Fine-tuned control over dependency caching”).

外部模块依赖是最常见的依赖。它们引用外部仓库中的模块。
External module dependencies are the most common dependencies. They refer to a module in an external repository.

dependencies {
    runtime group: 'org.springframework', name: 'spring-core', version: '2.5'
    runtime 'org.springframework:spring-core:2.5', 'org.springframework:spring-aop:2.5'
    runtime(
        [group: 'org.springframework', name: 'spring-core', version: '2.5'],
        [group: 'org.springframework', name: 'spring-aop', version: '2.5']
    )
    runtime('org.hibernate:hibernate:3.0.5') {
        transitive = true
    }
    runtime group: 'org.hibernate', name: 'hibernate', version: '3.0.5', transitive: true
    runtime(group: 'org.hibernate', name: 'hibernate', version: '3.0.5') {
        transitive = true
    }
}

有关更多的例子和完整的参考，请参阅DependencyHandler 。
See DependencyHandler for more examples and a complete reference.

Gradle 为模块依赖提供了不同的标记法。有 string 标记法和 map 标记法。模块依赖有一个 API，用于进行进一步的配置。要了解所有该 API 的内容，可以参阅ExternalModuleDependency 。该 API 提供了一些属性和配置方法。通过 string 标记法，你可以定义一个属性的子集。而通过使用 map 标记法，你可以定义所有的属性。要访问完整的 API，使用 map 或 string 标记法，你可以把单个的依赖与一个闭包一起指定给一个配置。
Gradle provides different notations for module dependencies. There is a string notation and a map notation. A module dependency has an API which allows for further configuration. Have a look at ExternalModuleDependency to learn all about the API. This API provides properties and configuration methods. Via the string notation you can define a subset of the properties. With the map notation you can define all properties. To have access to the complete API, either with the map or with the string notation, you can assign a single dependency to a configuration together with a closure.

如果你定义了一个模块依赖，Gradle 会在仓库中查找相应的模块描述符文件（pom.xml或ivy.xml）。如果存在此类模块描述符文件，它会进行分析，并下载此模块的 artifacts （例如hibernate-3.0.5.jar）以及其依赖项（例如 cglib）。如果不存在这样的模块描述符文件，Gradle 会查找一个hibernate-3.0.5.jar 文件。在 Maven 中，一个模块仅能有一个 artifact。在 Gradle 和 Ivy 中，一个模块可以具有多个 artifacts。每个 artifact 可以有一组不同的依赖。
If you declare a module dependency, Gradle looks for a corresponding module descriptor file (pom.xml or ivy.xml) in the repositories. If such a module descriptor file exists, it is parsed and the artifacts of this module (e.g. hibernate-3.0.5.jar) as well as its dependencies (e.g. cglib) are downloaded. If no such module descriptor file exists, Gradle looks for a file called hibernate-3.0.5.jar to retrieve. In Maven, a module can have one and only one artifact. In Gradle and Ivy, a module can have multiple artifacts. Each artifact can have a different set of dependencies.

dependencies {
    runtime "org.groovy:groovy:2.2.0@jar"
    runtime group: 'org.groovy', name: 'groovy', version: '2.2.0', ext: 'jar'
}

compile "org.gradle.test.classifiers:service:1.0:jdk15@jar"
    otherConf group: 'org.gradle.test.classifiers', name: 'service', version: '1.0', classifier: 'jdk14'

它可以轻松地遍历一个配置的依赖 artifacts：
It is easy to iterate over the dependency artifacts of a configuration:

task listJars << {
    configurations.compile.each { File file -> println file.name }
}

> gradle -q listJars
hibernate-core-3.6.7.Final.jar
antlr-2.7.6.jar
commons-collections-3.1.jar
dom4j-1.6.1.jar
hibernate-commons-annotations-3.2.0.Final.jar
hibernate-jpa-2.0-api-1.0.1.Final.jar
jta-1.1.jar
slf4j-api-1.6.1.jar

客户端模块依赖允许直接在构建脚本中声明传递依赖。它们是外部库的模块描述符的替代者。
Client module dependencies allow to declare transitive dependencies directly in the build script. They are a replacement for a module descriptor in an external repository.

dependencies {
    runtime module("org.codehaus.groovy:groovy-all:2.2.0") {
        dependency("commons-cli:commons-cli:1.0") {
            transitive = false
        }
        module(group: 'org.apache.ant', name: 'ant', version: '1.9.3') {
            dependencies "org.apache.ant:ant-launcher:1.9.3@jar", "org.apache.ant:ant-junit:1.9.3"
        }
    }
}

这里定义了一个对 Groovy 的依赖。Groovy 本身具有依赖。但 Gradle 不会去查找一个 XML 描述符来找出它的依赖，而是从构建文件中获取信息。一个客户端模块的依赖可以是正常的模块依赖，或者是 artifact 依赖项或是另一个客户端模块。可以看一看 API 文档： ClientModule
This declares a dependency on Groovy. Groovy itself has dependencies. But Gradle does not look for an XML descriptor to figure them out but gets the information from the build file. The dependencies of a client module can be normal module dependencies or artifact dependencies or another client module. Have also a look at the API documentation: ClientModule

在当前版本客户端模块有一个缺陷。假设你的项目是一个库，你想要这个库上传到你公司的 Maven 或Ivy 仓库。Gradle 会将你的项目的 jar 包以及这仆依赖的 XML 描述文件上传到公司仓库。如果你使用了客户端模块，在 XML 描述符文件中的依赖声明就会不正确。我们将在未来版本的 Gradle 修正这一点。
In the current release client modules have one limitation. Let's say your project is a library and you want this library to be uploaded to your company's Maven or Ivy repository. Gradle uploads the jars of your project to the company repository together with the XML descriptor file of the dependencies. If you use client modules the dependency declaration in the XML descriptor file is not correct. We will improve this in a future release of Gradle.

对于多项目构建，Gradle 能区分外部依赖与作为多项目构建的一部分的某个项目上的依赖。对于后者，你可以声明项目依赖。
Gradle distinguishes between external dependencies and dependencies on projects which are part of the same multi-project build. For the latter you can declare Project Dependencies.

dependencies {
    compile project(':shared')
}

详细信息请参阅ProjectDependency的 API 文档
For more information see the API documentation for ProjectDependency

多项目构建将在第 56 章，多项目生成中进行详述。
Multi-project builds are discussed inChapter 56, Multi-project Builds.

文件依赖允许你直接将一组文件添加到配置中，而不用先将它们添加到存储库。这将会非常有用，比如你无法，或者是不想要把某些文件放到仓库。或者是你如果不想使用任何仓库来存储你的依赖。
File dependencies allow you to directly add a set of files to a configuration, without first adding them to a repository. This can be useful if you cannot, or do not want to, place certain files in a repository. Or if you do not want to use any repositories at all for storing your dependencies.

如果想添加一些文件作为配置的依赖，你只需要传一个文件集合作为依赖：
To add some files as a dependency for a configuration, you simply pass a file collection as a dependency:

dependencies {
    runtime files('libs/a.jar', 'libs/b.jar')
    runtime fileTree(dir: 'libs', include: '*.jar')
}

文件依赖项不会包含在你的项目的发布的依赖描述中。然而，文件依赖会被包含在同一个构建的传递项目依赖里。这意味着它们不能在当前的构建外使用，但它们可以在同一个构建中使用。
File dependencies are not included in the published dependency descriptor for your project. However, file dependencies are included in transitive project dependencies within the same build. This means they cannot be used outside the current build, but they can be used with the same build.

你可以声明哪些任务将产生作为文件依赖的文件。例如，你可以在通过构建生成文件的时候这样做。
You can declare which tasks produce the files for a file dependency. You might do this when, for example, the files are generated by the build.

dependencies {
    compile files("$buildDir/classes") {
        builtBy 'compile'
    }
}

task compile << {
    println 'compiling classes'
}

task list(dependsOn: configurations.compile) << {
    println "classpath = ${configurations.compile.collect {File file -> file.name}}"
}

> gradle -q list
compiling classes
classpath = [classes]

你可以通过使用DependencyHandler.gradleApi()方法，来声明一个当前的 Gradle 版本的 API 上的依赖。当你在开发自定义 Gradle 任务或插件时将会很有用。
You can declare a dependency on the API of the current version of Gradle by using the DependencyHandler.gradleApi() method. This is useful when you are developing custom Gradle tasks or plugins.

dependencies {
    compile gradleApi()
}

可以通过使用DependencyHandler.localGroovy()方法，来声明对与 Gradle 一起发布的 Groovy 的依赖。当你在开发自定义 Gradle 任务或在 Groovy 中的插件时将会很有用。
You can declare a dependency on the Groovy that is distributed with Gradle by using the DependencyHandler.localGroovy() method. This is useful when you are developing custom Gradle tasks or plugins in Groovy.

dependencies {
    compile localGroovy()
}

通过配置或者是通过依赖，你可以排除一个传递依赖：
You can exclude a transitive dependency either by configuration or by dependency:

configurations {
    compile.exclude module: 'commons'
    all*.exclude group: 'org.gradle.test.excludes', module: 'reports'
}

dependencies {
    compile("org.gradle.test.excludes:api:1.0") {
        exclude module: 'shared'
    }
}

如果你为一个特定的配置定义一个 exclude，则解析此配置或任何继承的配置时，对于所有的依赖，所排除的传递依赖将会被过滤掉。如果你想要从你的所有配置中排除传递依赖，你可以用简明的方式，使用 Groovy 的 spread-dot 运算符来表示，如这个例子所示例。在定义一个 exclude 时，你可以只指定 organization 或者 module 名称，或者是两者都指定。可以看看 Dependency 和 Configuration 的 API 文档。
If you define an exclude for a particular configuration, the excluded transitive dependency will be filtered for all dependencies when resolving this configuration or any inheriting configuration. If you want to exclude a transitive dependency from all your configurations you can use the Groovy spread-dot operator to express this in a concise way, as shown in the example. When defining an exclude, you can specify either only the organization or only the module name or both. Have also a look at the API documentation of Dependency and Configuration.

不是每个传递依赖都可以被排除 — — 一些传递依赖可能是应用程序能正确运行的必要条件。一般来说，可以被排除的传递依赖，在运行时并不需要，或者是保证在目标环境或平台上可用。
Not every transitive dependency can be excluded - some transitive dependencies might be essential for correct runtime behavior of the application. Generally, one can exclude transitive dependencies that are either not required by runtime or that are guaranteed to be available on the target environment/platform.

你应排除每个依赖或每个配置吗？事实证明，在大多数情况下你想要排除每一个配置。下面是为什么可能想要排除传递依赖的一些原因。记住，对于其中一些用例，有着比排除更好的解决方案！
Should you exclude per-dependency or per-configuration? It turns out that in majority of cases you want to use the per-configuration exclusion. Here are the some exemplary reasons why one might want to exclude a transitive dependency. Bear in mind that for some of those use cases there are better solutions than exclusions!

基本上，在大多数情况下对每一个配置都是排除传递依赖。这种依赖声明的方式更加明确。它也更准确，因为每个依赖排除规则并不能保证给定的传递依赖不会显示在配置中。例如，某些其他的依赖，并没有任何排除规则，可能会带上那个多余的传递依赖。
Basically, in most of the cases excluding the transitive dependency should be done per configuration. This way the dependency declaration is more explicit. It is also more accurate because a per-dependency exclude rule does not guarantee the given transitive dependency does not show up in the configuration. For example, some other dependency, which does not have any exclude rules, might pull in that unwanted transitive dependency.

其他相关依赖关系排除的示例，可以参考 ModuleDependency或DependencyHandler。
Other examples of the dependency exclusions can be found in the reference for ModuleDependency or DependencyHandler.

一个依赖的所有属性都是可选的，除了 name。这取决于仓库类型，这些信息实际上需要用于在仓库中找到这个依赖。请参阅 50.6 节，“仓库”。例如，如果你使用 Maven 仓库，你需要定义group，name 和 version。如果你使用文件系统仓库，你可能只需要 name 或 name 和 version。
All attributes for a dependency are optional, except the name. It depends on the repository type, which information is need for actually finding the dependencies in the repository. See Section 50.6, “Repositories”. If you work for example with Maven repositories, you need to define the group, name and version. If you work with filesystem repositories you might only need the name or the name and the version.

dependencies {
    runtime ":junit:4.10", ":testng"
    runtime name: 'testng' 
}

你也可以向一个配置指定依赖 notations 的集合或数组：
You can also assign collections or arrays of dependency notations to a configuration:

List groovy = ["org.codehaus.groovy:groovy-all:2.2.0@jar",
               "commons-cli:commons-cli:1.0@jar",
               "org.apache.ant:ant:1.9.3@jar"]
List hibernate = ['org.hibernate:hibernate:3.0.5@jar', 'somegroup:someorg:1.0@jar']
dependencies {
    runtime groovy, hibernate
}

在 Gradle ，一个依赖可以有不同的配置 (就像你的项目可以有不同的配置)。如果你不显式指定任何东西，Gradle 会使用依赖的默认配置。对于 Maven 存储库的依赖，至少默认配置是唯一可用的一个。如果你使用 Ivy 存储库，并且想要为你的依赖定义一个非默认配置，就要使用 map 标记法并且声明：
In Gradle a dependency can have different configurations (as your project can have different configurations). If you don't specify anything explicitly, Gradle uses the default configuration of the dependency. For dependencies from a Maven repository, the default configuration is the only available one anyway. If you work with Ivy repositories and want to declare a non-default configuration for your dependency you have to use the map notation and declare:

dependencies {
    runtime group: 'org.somegroup', name: 'somedependency', version: '1.0', configuration: 'someConfiguration'
}

同样的项目依赖，你需要声明：
To do the same for project dependencies you need to declare:

dependencies {
    compile project(path: ':api', configuration: 'spi')
}

你可以从命令行生成依赖报告 （参阅 第11.6.4节，“列出项目依赖”）。通过使用 Project report 插件（参阅 第 41 章， Project Report 插件），在构建中可以创建一个这样的报告。
You can generate dependency reports from the command line (see Section 11.6.4, “Listing project dependencies”). With the help of the Project report plugin (see Chapter 41, The Project Report Plugin) such a report can be created by your build.

从 Gradle 1.2 起，有一个新的编程 API 用于访问解析的依赖信息。依赖报告（见前面一段）正是使用此 API。这个 API 可以让你查看解析的依赖图，并提供有关依赖的信息。在未来的版本，这个API 将提供更多有关解析结果的详细信息。关于这个 API 的更多信息，请参考 ResolvableDependencies.getResolutionResult()上的文档。ResolutionResult API的可能用法：
Since Gradle 1.2 there is also a new programmatic API to access the resolved dependency information. The dependency reports (see the previous paragraph) are using this API under the covers. The API lets you to walk the resolved dependency graph and provides information about the dependencies. With the coming releases the API will grow to provide more information about the resolution result. For more information about the API please refer to the javadocs on ResolvableDependencies.getResolutionResult(). Potential usages of the ResolutionResult API:

若要添加中央 Maven 2 仓库（http://repo1.maven.org/maven2），只需添加下面的代码到你的构建脚本中：
To add the central Maven 2 repository (http://repo1.maven.org/maven2) simply add this to your build script:

repositories {
    mavenCentral()
}

现在 Gradle 将会在此仓库中查找你的依赖。
Now Gradle will look for your dependencies in this repository.

BintrayJCenter 是所有流行的 Maven OSS artifacts 的up-to-date 集合，包括直接发布到 Bintray 的 artifacts。
Bintray's JCenter is an up-to-date collection of all popular Maven OSS artifacts, including artifacts published directly to Bintray.

若要添加 JCenter Maven 仓库（http://jcenter.bintray.com），只需添加下面的内容到你的构建脚本中：
To add the JCenter Maven repository (http://jcenter.bintray.com) simply add this to your build script:

repositories {
    jcenter()
}

现在 Gradle 将会在 JCenter 仓库中查找你的依赖。
Now Gradle will look for your dependencies in the JCenter repository.

你可以这样把本地的 Maven 缓存作为仓库使用：
To use the local Maven cache as a repository you can do:

repositories {
    mavenLocal()
}

Gradle 使用与 Maven 相同的逻辑来标识你本地的 Maven 缓存的位置。如果在settings.xml中定义一个本地仓库的位置，那么这个位置将会被使用。在USER_HOME/.m2 的settings.xml 比在 M2_HOME/conf的settings.xml优先。如果没有settings.xml可用，Gradle 将使用默认的位置USER_HOME/.m2/repository。
Gradle uses the same logic as Maven to identify the location of your local Maven cache. If a local repository location is defined in a settings.xml, this location will be used. The settings.xml in USER_HOME/.m2 takes precedence over the settings.xml in M2_HOME/conf. If no settings.xml is available, Gradle uses the default location USER_HOME/.m2/repository.

要添加一个自定义的 Maven 仓库，你可以如下操作：
For adding a custom Maven repository you can do:

repositories {
    maven {
        url "http://repo.mycompany.com/maven2"
    }
}

有时候，一个仓库会出现 POM 文件发布在一个地方，而 JAR 文件和其他构件发布在另一个地方。要定义一个这样的仓库，你可以这样：
Sometimes a repository will have the POMs published to one location, and the JARs and other artifacts published at another location. To define such a repository, you can do:

repositories {
    maven {
        // Look for POMs and artifacts, such as JARs, here
        url "http://repo2.mycompany.com/maven2"
        // Look for artifacts here if not found at the above location
        artifactUrls "http://repo.mycompany.com/jars"
        artifactUrls "http://repo.mycompany.com/jars2"
    }
}

Gradle 将会在第一个URL中查找 POM 和 JAR 文件。如果那里找不到 JAR，就会用 artifact URLs 来查找 JAR 文件。
Gradle will look at the first URL for the POM and the JAR. If the JAR can't be found there, the artifact URLs are used to look for JARs.

repositories {
    maven {
        credentials {
            username 'user'
            password 'password'
        }
        url "http://repo.mycompany.com/maven2"
    }
}

如果你想要把一个（平面）文件系统目录作为仓库使用，只需输入：
If you want to use a (flat) filesystem directory as a repository, simply type:

repositories {
    flatDir {
        dirs 'lib'
    }
    flatDir {
        dirs 'lib1', 'lib2'
    }
}

这将会添加一些用于查找依赖的仓库，它会在一个或多个目录中寻找。如果你只使用平面目录解析器，那么你不需要去设置一个依赖的所有属性。请参阅 第50.4.8 节，“可选属性”
This adds repositories which look into one or more directories for finding dependencies. If you only work with flat directory resolvers you don't need to set all attributes of a dependency. See Section 50.4.8, “Optional attributes”

使用一个标准布局的 Ivy 存储库：
To use an Ivy repository with a standard layout:

repositories {
    ivy {
        url "http://repo.mycompany.com/repo"
        layout "maven"
    }
}

详细信息请参阅IvyArtifactRepository 。
See IvyArtifactRepository for details.

repositories {
    ivy {
        url "http://repo.mycompany.com/repo"
        layout "pattern", {
            artifact "[module]/[revision]/[type]/[artifact].[ext]"
        }
    }
}

repositories {
    ivy {
        url "http://repo.mycompany.com/repo"
        layout "pattern", {
            artifact "[organisation]/[module]/[revision]/[artifact]-[revision].[ext]"
            m2compatible = true
        }
    }
}

repositories {
    ivy {
        url "http://repo.mycompany.com/repo"
        layout "pattern", {
            artifact "3rd-party-artifacts/[organisation]/[module]/[revision]/[artifact]-[revision].[ext]"
            artifact "company-artifacts/[organisation]/[module]/[revision]/[artifact]-[revision].[ext]"
            ivy "ivy-files/[organisation]/[module]/[revision]/ivy.xml"
        }
    }
}

repositories {
    ivy {
        url 'http://repo.mycompany.com'
        credentials {
            username 'user'
            password 'password'
        }
    }
}

若要访问一个仓库：
To access a repository:

println repositories.localRepository.name
    println repositories['localRepository'].name

要配置一个仓库：
To configure a repository:

repositories {
    flatDir {
        name 'localRepository'
    }
}
repositories {
    localRepository {
        dirs 'lib'
    }
}
repositories.localRepository {
    dirs 'lib'
}

Gradle由于 Ivy 在它的 hood 之下，对仓库非常灵活。
Gradle, thanks to Ivy under its hood, is extremely flexible regarding repositories:

比方说，你可以声明一个junit:junit:3.8.2库的依赖。现在 Gradle 是如何发现它在存储库中的?某种程度上依赖信息必须映射到一个路径上。相比于固定路径的 Maven，使用 Gradle 你可以定义一个模式，该模式定义了路径的样子。这里有一些例子：^[16]
Let's say, you declare a dependency on the junit:junit:3.8.2 library. Now how does Gradle find it in the repositories? Somehow the dependency information has to be mapped to a path. In contrast to Maven, where this path is fixed, with Gradle you can define a pattern that defines what the path will look like. Here are some examples: ^[16]

// Maven2 layout (if a repository is marked as Maven2 compatible, the organization (group) is split into subfolders according to the dots.)
someroot/[organisation]/[module]/[revision]/[module]-[revision].[ext]

// Typical layout for an Ivy repository (the organization is not split into subfolder)
someroot/[organisation]/[module]/[revision]/[type]s/[artifact].[ext]

// Simple layout (the organization is not used, no nested folders.)
someroot/[artifact]-[revision].[ext]

要添加任何一种仓库 (你可以很简单地编写你自己的) ，你可以：
To add any kind of repository (you can pretty easy write your own ones) you can do:

repositories {
    ivy {
        ivyPattern "$projectDir/repo/[organisation]/[module]-ivy-[revision].xml"
        artifactPattern "$projectDir/repo/[organisation]/[module]-[revision](-[classifier]).[ext]"
    }
}

其中由 Ivy （也因此由 Gradle ）提供解析器的，它的概述可以在这里找到。通过Gradle，你只是不用通过XML来配置它们，而是通过它们的API。
An overview of which Resolvers are offered by Ivy and thus also by Gradle can be found here. With Gradle you just don't configure them via XML but directly via their API.

强制一个模块的版本，是告诉 Gradle 对于指定的依赖（不管是否传递依赖），始终使用一个特定的版本，而覆盖在发布的模块描述符中所指定的任何版本。当解决版本冲突时，这可能非常有用——有关详细信息请参阅第 50.2.3 节，“解决版本冲突”。
Forcing a module version tells Gradle to always use a specific version for given dependency (transitive or not), overriding any version specified in a published module descriptor. This can be very useful when tackling version conflicts - for more information see Section 50.2.3, “Resolve version conflicts”.

强制版本也可以用于处理传递依赖所带来的流氓元数据。如果传递依赖有质量较差的元数据，导致了依赖解析时的问题时，你可以强制 Gradle 对于这一依赖使用一个较新的，固定的版本。有关示例，请参见ResolutionStrategy。请注意，“依赖解析规则”（见下文），提供了一种更强大的机制，来取代一个损坏的模块依赖。请参阅50.8.2.3 节，“黑名单替换指定版本”。
Force versions can also be used to deal with rogue metadata of transitive dependencies. If a transitive dependency has poor quality metadata that leads to problems at dependency resolution time, you can force Gradle to use a newer, fixed version of this dependency. For an example, see ResolutionStrategy. Note that 'dependency resolve rules' (outlined below) provide a more powerful mechanism for replacing a broken module dependency. See Section 50.8.2.3, “Blacklisting a particular version with a replacement”.

一个依赖解析规则为每一个解析依赖执行，并提供功能强大的 api 用于在解析依赖之前处理这个依赖的请求。此功能还在孵化中，但目前提供了对于一个请求的依赖更改组、 名称及版本的功能，允许在解析过程中，把一个依赖替换为另一个完全不同的模块。
A dependency resolve rule is executed for each resolved dependency, and offers a powerful api for manipulating a requested dependency prior to that dependency being resolved. This feature is incubating, but currently offers the ability to change the group, name and/or version of a requested dependency, allowing a dependency to be substituted with a completely different module during resolution.

依赖解析规则提供了一种非常强大的方式来控制依赖解析过程，并可以用于实现在依赖管理中各种高级模式的排序。下面将概述其中的某些模式。更多的信息和代码示例请参阅ResolutionStrategy。
Dependency resolve rules provide a very powerful way to control the dependency resolution process, and can be used to implement all sorts of advanced patterns in dependency management. Some of these patterns are outlined below. For more information and code samples see ResolutionStrategy.

configurations.all {
    resolutionStrategy.eachDependency { DependencyResolveDetails details ->
        if (details.requested.group == 'org.gradle') {
            details.useVersion '1.4'
        }
    }
}

configurations.all {
    resolutionStrategy.eachDependency { DependencyResolveDetails details ->
        if (details.requested.version == 'default') {
            def version = findDefaultVersionInCatalog(details.requested.group, details.requested.name)
            details.useVersion version
        }
    }
}

def findDefaultVersionInCatalog(String group, String name) {
    //some custom logic that resolves the default version into a specific version
    "1.0"
}

configurations.all {
    resolutionStrategy.eachDependency { DependencyResolveDetails details ->
        if (details.requested.group == 'org.software' && details.requested.name == 'some-library' && details.requested.version == '1.2') {
            //prefer different version which contains some necessary fixes
            details.useVersion '1.2.1'
        }
    }
}

configurations.all {
    resolutionStrategy.eachDependency { DependencyResolveDetails details ->
        if (details.requested.name == 'groovy-all') {
            //prefer 'groovy' over 'groovy-all':
            details.useTarget group: details.requested.group, name: 'groovy', version: details.requested.version
        }
        if (details.requested.name == 'log4j') {
            //prefer 'log4j-over-slf4j' over 'log4j', with fixed version:
            details.useTarget "org.slf4j:log4j-over-slf4j:1.7.5"
        }
    }
}

Gradle 的Ivy 仓库实现支持相当于 Ivy 的动态解析的模式。通常情况下，Gradle 将rev属性用于在ivy.xml文件中包含的每个依赖定义。在动态解析模式中，Gradle 将优先使用revConstraint属性来代替rev属性，用于一个给定的依赖定义。如果不存在revConstraint属性，则使用rev属性。
Gradle's Ivy repository implementations support the equivalent to Ivy's dynamic resolve mode. Normally, Gradle will use the rev attribute for each dependency definition included in an ivy.xml file. In dynamic resolve mode, Gradle will instead prefer the revConstraint attribute over the rev attribute for a given dependency definition. If the revConstraint attribute is not present, the rev attribute is used instead.

若要启用动态解析模式，你需要在仓库定义进行合适的设置。下面展示了几个例子。注意，动态解析模式只对 Gradle 的 Ivy 仓库有效。它不能用于 Maven 仓库，或自定义的 Ivy DependencyResolver实现。
To enable dynamic resolve mode, you need to set the appropriate option on the repository definition. A couple of examples are shown below. Note that dynamic resolve mode is only available for Gradle's Ivy repositories. It is not available for Maven repositories, or custom Ivy DependencyResolver implementations.

// Can enable dynamic resolve mode when you define the repository
repositories {
    ivy {
        url "http://repo.mycompany.com/repo"
        resolve.dynamicMode = true
    }
}

// Can use a rule instead to enable (or disable) dynamic resolve mode for all repositories
repositories.withType(IvyArtifactRepository) {
    resolve.dynamicMode = true
}

每个模块（也称为组件）都有相关的元数据上，像它的组，名称，版本，依赖，等等。这个元数据通常来源于模块的描述符。元数据规则允许模块的元数据在构建脚本中被操纵。它们在模块描述符下载之后，被所有候选版本之间选择之前生效。这使得元数据成为自定义依赖解析的另一种手段。
Each module (also called component) has metadata associated with it, such as its group, name, version, dependencies, and so on. This metadata typically originates in the module's descriptor. Metadata rules allow certain parts of a module's metadata to be manipulated from within the build script. They take effect after a module's descriptor has been downloaded, but before it has been selected among all candidate versions. This makes metadata rules another instrument for customizing dependency resolution.

其中一个 Gradle 能理解的模块元数据是模块的状态模式。这一概念，也可以从 Ivy 中，随着时间推移，一个模块发展的成熟水平可以得知。默认状态模式，按状态的成熟程度排序，分别是integration、milestone、release。除了状态模式以外，模块也有一个（当前） 的状态，这个状态必须是它的状态模式中的值之一。如果没有在（Ivy）描述符中指定，Ivy 模块和 Maven snapshot模块的状态默认为integration ，不是snapshot 的 Maven 模块则默认为release。
One piece of module metadata that Gradle understands is a module's status scheme. This concept, also known from Ivy, models the different levels of maturity that a module transitions through over time. The default status scheme, ordered from least to most mature status, is integration, milestone, release. Apart from a status scheme, a module also has a (current) status, which must be one of the values in its status scheme. If not specified in the (Ivy) descriptor, the status defaults to integration for Ivy modules and Maven snapshot modules, and release for Maven modules that aren't snapshots.

一个模块的状态以及状态模式，会在解析 latest 版本选择器时考虑到。具体而言，latest.someStatus 将会解析成有着someStatus 或更成熟状态的最高的模块版本。例如，在适当的位置使用默认的状态模式，latest.integration将选择最高的模块版本，不论其状态（因为integration是成熟度最低的状态），而latest.release将选择release状态的最高模块版本。这里是在代码中的表现：
A module's status and status scheme are taken into consideration when a latest version selector is resolved. Specifically, latest.someStatus will resolve to the highest module version that has status someStatus or a more mature status. For example, with the default status scheme in place, latest.integration will select the highest module version regardless of its status (because integration is the least mature status), whereas latest.release will select the highest module version with status release. Here is what this looks like in code:

dependencies {
    config1 "sea.fish:tuna:latest.integration"
    config2 "sea.fish:tuna:latest.release"
}

task listFish << {
    configurations.config1.each { println it.name }
    println()
    configurations.config2.each { println it.name}
}

> gradle -q listFish
tuna-1.5.jar

tuna-1.4.jar

下一个示例演示了基于在一个模块的元数据规则中声明的自定义状态模式的latest选择器：
The next example demonstrates latest selectors based on a custom status scheme declared in a module metadata rule:

dependencies {
    config3 "air.birds:albatros:latest.silver"
    components {
        eachComponent { ComponentMetadataDetails details ->
            if (details.id.group == "air.birds") {
                details.statusScheme = ["bronze", "silver", "gold", "platinum"]
            }
        }
    }
}

task listBirds << {
    configurations.config3.each { println it.name }
}

> gradle -q listBirds
albatros-2.0.jar

你可以在一个配置中通过使用ResolutionStrategy对缓存的某些方面进行微调。
You can fine-tune certain aspects of caching using the ResolutionStrategy for a configuration.

默认情况下，Gradle 缓存动态版本的时间为 24 小时。如果要改变Gradle对解析一个动态版本的缓存时间，可以使用：
By default, Gradle caches dynamic versions for 24 hours. To change how long Gradle will cache the resolved version for a dynamic version, use:

configurations.all {
    resolutionStrategy.cacheDynamicVersionsFor 10, 'minutes'
}

默认情况下，Gradle 的变化模块将缓存 24 小时。要修改 Gradle 对变化模块的元数据和构件的缓存时间，请使用：
By default, Gradle caches changing modules for 24 hours. To change how long Gradle will cache the meta-data and artifacts for a changing module, use:

configurations.all {
    resolutionStrategy.cacheChangingModulesFor 4, 'hours'
}

更多详细信息请参阅ResolutionStrategy的 API 文档。
For more details, take a look at the API documentation forResolutionStrategy.

还有另外一种方法，用于处理没有XML 描述符文件的传递依赖。你可以使用 Gradle 来做，但我们不推荐它。我们提到它是为了完整性，以及和其他构建工具进行比较。
There is another way to deal with transitive dependencies without XML descriptor files. You can do this with Gradle, but we don't recommend it. We mention it for the sake of completeness and comparison with other build tools.

诀窍是只使用构件依赖，并在列表中对它们进行分组。对于这种方法，你将用某种方式表达，你第一级的依赖项和传递依赖是什么（见第 50.4.8 条，“可选属性”）。但缺点是，对于 Gradle 依赖管理而言，所有的依赖都被认为是第一级依赖。依赖报告不会显示你真正的依赖关系图，并且compile任务会使用所有的依赖，而不只是第一级依赖。总之，比起使用客户端模块，你的构建不再那么容易维护和可靠。而你不会有其他收获。
The trick is to use only artifact dependencies and group them in lists. That way you have somehow expressed, what are your first level dependencies and what are transitive dependencies (see Section 50.4.8, “Optional attributes”). But the draw-back is, that for the Gradle dependency management all dependencies are considered first level dependencies. The dependency reports don't show your real dependency graph and the compile task uses all dependencies, not just the first level dependencies. All in all, your build is less maintainable and reliable than it could be when using client modules. And you don't gain anything.