第五十章. 依赖管理

在从一个构建系统迁移到另一个构建系统的过程当中，对于依赖管理而方，可能特别具有挑战性。 如果你要从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你正在使用Hibernate V3.0.5，也没有标准的方法来表示 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的版本通常在Manifest文件中，但当你要检查项目时它并不显而易见。如果有人让你看20个jar文件，你更愿意哪一种?名字像 commons-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的冲突版本应该被检测到，并且要么解决要么抛出异常。 如果不使用传递依赖管理，版本冲突没被检测到，那以在类路径中的无法预测的顺序将决定最终使用哪个版本的依赖。在有许多开发者更改依赖的大型项目上，成功的构建将会少之又少，因为依赖的顺序可能直接影响构建是否成功（或者在生产中是否出现错误）。
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).

或者，有时你请求的模块可能会随着时间的推移而变化，即使是版本相同。这种变化模块类型的一个例子是Maven的SNAPSHOT模块，它始终指向最新发布的工件。换句话说，一个标准的Maven快照是一个永远不会不变的模块，可以这样说，它是一个“变化模块”。
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".

动态版本 和 变化模块 之间的主要差别是，当你解析一个 动态版本时，你会得到真实的、静态的版本作为模块名称。当你解析一个 变化模块时，将使用你请求的版本来命名工件，但底层工件可能会随时间而变化。
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.

默认情况下，Grdale 对动态版本和变化模块的缓存时间是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 为模块依赖提供了不同的标记法，有字符串表示法和映射表示法。模块依赖有 API 可以让你进一步配置，请查看 ExternalModuleDependency 了解有关该 API 的所有内容。该 API 提供了属性和配置方法。通过字符串表示法，你可以定义一个属性子集。而通过映射表示法，你可以定义所有属性。要访问完整的 API（包括映射或字符串表示法），你可以通过一个闭包将一个依赖指定给配置。
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）。如果存在这样的模块描述符文件，它会进行解析，并下载此模块的工件（如 hibernate-3.0.5.jar）及其依赖（如 cglib）。如果不存在这样的模块描述符文件，Gradle将查找名为 hibernate-3.0.5.jar 的文件。在 Maven 中，一个模块只能有一个工件。在 Gradle 和 Ivy 中，一个模块可以有多个工件。每个工件都可以有一组不同的依赖。
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'

要遍历一个配置的依赖工件很容易：
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:2.3.3") {
        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 描述符来找出它的依赖，而是从构建文件中获取信息。客户端模块的依赖可以是正常模块依赖或工件依赖，或者是另一个客户端模块。还请查看 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 的依赖。
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 的依赖。当你使用 Groovy 开发自定义 Gradle 任务或插件时，这会很有用。
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'
    }
}

如果你为一个特定配置定义了排除，那么解析这个配置或任何继承的配置时，所有依赖的被排除的传递依赖都会被过滤掉。如果你要从所有配置中排除传递依赖，那么可以使用一种简明的方式，使用 Groovy 的 spread-dot 运算符来表示此操作，如示例中所示。定义排除时，你可以只指定组织或只指定模块名称，或者两者都指定。另请查看 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.

依赖的所有属性除了名称之外都是可选的。这取决于仓库类型，这些信息实际上用于查找仓库中的依赖。请参阅 第50.6节，《存储库》。 比如如果你使用 Maven 仓库，那么就需要定义组，名称及版本。如果你使用文件系统仓库，那么可能只需要名称或名称及版本。
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' 
}

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

List groovy = ["org.codehaus.groovy:groovy-all:2.3.3@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 仓库并且想为依赖声明一个非默认配置，那么必须使用映射表示法并声明：
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节，《列示项目依赖》）。在项目报告插件的帮助下（请参阅 第41章，《项目报告插件》) ，你的构建能够创建这样一个报告。
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 的更多信息，请参阅 ResolvableDependences.getResolutionResult()上的 javadocs。 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 和 Ivy 仓库支持使用各种传输协议，当前支持以下协议：
Maven and Ivy repositories support the use of various transport protocols. At the moment the following protocols are supported:

要定义仓库，请使用 repositories 配置块。在 repositories 闭包中，使用 maven 声明 Maven 仓库，使用 ivy 声明Ivy 仓库。传输协议是仓库 URL 定义的一部分。以下构建脚本演示了如何创建基于 HTTP 的 Maven 和 Ivy 仓库：
To define a repository use the repositories configuration block. Within the repositories closure, a Maven repository is declared with maven. An Ivy repository is declared with ivy. The transport protocol is part of the URL definition for a repository. The following build script demonstrates how to create a HTTP-based Maven and Ivy repository:

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

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

如果仓库需要认证，那么可以提供相关的凭证。以下示例展示了如何为 SFTP 仓库提供基于用户名/密码的认证：
If authentication is required for a repository, the relevant credentials can be provided. The following example shows how to provide username/password-based authentication for SFTP repositories:

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

    ivy {
        url "sftp://repo.mycompany.com:22/repo"
        credentials {
            username 'user'
            password 'password'
        }
    }
}

若要添加中央 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.

Bintray 的 JCenter 是所有流行的 Maven OSS 工件（包括直接发布到 Bintray 的工件）的最新集合。
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，那么会使用工件 URL 来查找 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”

要访问一个仓库：
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，它在仓库方面非常灵活。
Gradle, thanks to Ivy under its hood, is extremely flexible regarding repositories:

比如说，你声明了一个对 junit:jun: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 快照模块的状态默认是 integration，而不是快照的 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.