spring-cloud-build.md

# Spring Cloud构建

Spring Cloud构建是 Spring Cloud用于插件和依赖管理的一个常见实用程序项目。

## [构建和部署](#_building_and_deploying)

要在本地安装：

```
$ mvn install -s .settings.xml
```

并将快照部署到 repo。 Spring.io:

```
$ mvn deploy -DaltSnapshotDeploymentRepository=repo.spring.io::default::https://repo.spring.io/snapshot
```

用于发布版本的构建使用

```
$ mvn deploy -DaltReleaseDeploymentRepository=repo.spring.io::default::https://repo.spring.io/release
```

供 JCenter 使用

```
$ mvn deploy -DaltReleaseDeploymentRepository=bintray::default::https://api.bintray.com/maven/spring/jars/org.springframework.cloud:build
```

供 Maven 中央使用

```
$ mvn deploy -P central -DaltReleaseDeploymentRepository=sonatype-nexus-staging::default::https://oss.sonatype.org/service/local/staging/deploy/maven2
```

（“central”profile 可用于 Spring Cloud 中的所有项目，并且它设置了 GPG jar 签名，并且存储库必须为该项目单独指定，因为它是启动器父程序的父程序，用户反过来将其作为自己的父程序）。

## [贡献](#_contributing)

Spring Cloud 是在非限制性的 Apache2.0 许可下发布的，遵循非常标准的 GitHub 开发流程，使用 GitHub Tracker 处理问题，并将拉请求合并到 Master 中。如果你想贡献一些微不足道的东西，请不要犹豫，但要遵循下面的指导方针。

### [签署贡献者许可协议](#_sign_the_contributor_license_agreement)

在我们接受一个重要的补丁或拉请求之前，我们需要你签署[贡献者许可协议](https://cla.pivotal.io/sign/spring)。签署贡献者协议并不会授予任何人对主库的提交权限，但这确实意味着我们可以接受你的贡献，并且如果我们接受了，你将获得作者信用。活跃的贡献者可能会被要求加入核心团队，并被赋予合并拉请求的能力。

### [行为守则](#_code_of_conduct)

该项目遵守贡献者契约[行为守则](https://github.com/spring-cloud/spring-cloud-build/blob/master/docs/src/main/asciidoc/code-of-conduct.adoc)。通过参与，你将被期望坚持这一准则。请向[[电子邮件保护]]报告不可接受的行为（/cdn-cgi/l/email-protection#DBA8aba9b2b5bcf6b8b4bfbef6b4bdf6b8b8b4b5bfaeb8af9babb2adb4afbab7f5b2b4）。

### [守则惯例和内部管理](#_code_conventions_and_housekeeping)

这些都不是拉请求所必需的，但它们都会有所帮助。它们也可以在原始的拉请求之后但在合并之前添加。

* 使用 Spring 框架代码格式约定。如果使用 Eclipse，则可以使用`eclipse-code-formatter.xml`文件从[Spring Cloud Build](https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/spring-cloud-dependencies-parent/eclipse-code-formatter.xml)项目导入格式化设置。如果使用 IntelliJ，可以使用[Eclipse 代码格式化插件](https://plugins.jetbrains.com/plugin/6546)导入相同的文件。

* 确保所有新的`.java`文件都有一个简单的 Javadoc 类注释，其中至少有一个`@author`标记来标识你，并且最好至少有一个段落来说明类的用途。

* 将 ASF 许可标头注释添加到所有新的`.java`文件（从项目中的现有文件复制）

* 将自己作为`@author`添加到你要进行实质性修改的.java 文件中（不仅仅是外观上的更改）。

* 添加一些 Javadocs，如果你更改了名称空间，还可以添加一些 XSDDOC 元素。

* 几个单元测试也会有很大帮助——必须有人去做。

* 如果没有其他人正在使用你的分支，请将它重新设置为当前的主分支（或主项目中的其他目标分支）。

* 在编写提交消息时，请遵循[这些约定](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)，如果你正在修复现有的问题，请在提交消息的末尾添加`Fixes gh-XXXX`（其中 xxxx 是问题编号）。

### [Checkstyle](#_checkstyle)

Spring Cloud构建附带了一组 checkstyle 规则。你可以在`spring-cloud-build-tools`模块中找到它们。该模块下最值得注意的文件是：

Spring-云构建工具/

```
└── src
    ├── checkstyle
    │   └── checkstyle-suppressions.xml (3)
    └── main
        └── resources
            ├── checkstyle-header.txt (2)
            └── checkstyle.xml (1)
```

|**1**|默认的 checkstyle 规则|
|-----|-------------------------|
|**2**|文件头设置|
|**3**|默认抑制规则|

#### [checkstyle 配置](#_checkstyle_configuration)

checkstyle 规则是**默认禁用**。要将 checkstyle 添加到项目中，只需定义以下属性和插件。

POM.xml

```
<properties>
<maven-checkstyle-plugin.failsOnError>true</maven-checkstyle-plugin.failsOnError> (1)
        <maven-checkstyle-plugin.failsOnViolation>true
        </maven-checkstyle-plugin.failsOnViolation> (2)
        <maven-checkstyle-plugin.includeTestSourceDirectory>true
        </maven-checkstyle-plugin.includeTestSourceDirectory> (3)
</properties>

<build>
        <plugins>
            <plugin> (4)
                <groupId>io.spring.javaformat</groupId>
                <artifactId>spring-javaformat-maven-plugin</artifactId>
            </plugin>
            <plugin> (5)
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-checkstyle-plugin</artifactId>
            </plugin>
        </plugins>

    <reporting>
        <plugins>
            <plugin> (5)
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-checkstyle-plugin</artifactId>
            </plugin>
        </plugins>
    </reporting>
</build>
```

|**1**|构建 checkstyle 错误失败|
|-----|--------------------------------------------------------------------------------------------------------------|
|**2**|构建 checkstyle 冲突失败|
|**3**|CheckStyle 还分析了测试源|
|**4**|添加 Spring Java 格式插件，该插件将重新格式化你的代码，以传递大多数 CheckStyle 格式设置规则|
|**5**|将 CheckStyle 插件添加到构建和报告阶段|

如果你需要抑制一些规则（例如行长需要更长），那么在`${project.root}/src/checkstyle/checkstyle-suppressions.xml`下定义一个文件就足够了。示例：

projectRoot/SRC/checkstyle/checkstyle-suppresions.xml

```
<?xml version="1.0"?>
<!DOCTYPE suppressions PUBLIC
		"-//Puppy Crawl//DTD Suppressions 1.1//EN"
		"https://www.puppycrawl.com/dtds/suppressions_1_1.dtd">
<suppressions>
	<suppress files=".*ConfigServerApplication\.java" checks="HideUtilityClassConstructor"/>
	<suppress files=".*ConfigClientWatch\.java" checks="LineLengthCheck"/>
</suppressions>
```

建议将`${spring-cloud-build.rootFolder}/.editorconfig`和`${spring-cloud-build.rootFolder}/.springformat`复制到你的项目中。这样，将应用一些默认的格式设置规则。你可以通过运行以下脚本来实现此目的：

```
$ curl https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/.editorconfig -o .editorconfig
$ touch .springformat
```

### [IDE setup](#_ide_setup)

#### [Intellij 思想](#_intellij_idea)

为了设置 IntelliJ，你应该导入我们的编码约定、检查配置文件并设置 CheckStyle 插件。以下文件可以在[Spring Cloud Build](https://github.com/spring-cloud/spring-cloud-build/tree/master/spring-cloud-build-tools)项目中找到。

Spring-云构建工具/

```
└── src
    ├── checkstyle
    │   └── checkstyle-suppressions.xml (3)
    └── main
        └── resources
            ├── checkstyle-header.txt (2)
            ├── checkstyle.xml (1)
            └── intellij
                ├── Intellij_Project_Defaults.xml (4)
                └── Intellij_Spring_Boot_Java_Conventions.xml (5)
```

|**1**|默认的 checkstyle 规则|
|-----|--------------------------------------------------------------------------|
|**2**|文件头设置|
|**3**|默认抑制规则|
|**4**|适用大多数 CheckStyle 规则的 IntelliJ 的项目默认值|
|**5**|适用大多数 CheckStyle 规则的 IntelliJ 的项目风格约定|

![Code style](https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/docs/src/main/asciidoc/images/intellij-code-style.png)

图 1。代码样式

转到`File``Settings``Editor``Code style`。点击`Scheme`区域旁边的图标。在这里，单击`Import Scheme`值并选择`Intellij IDEA code style XML`选项。导入`spring-cloud-build-tools/src/main/resources/intellij/Intellij_Spring_Boot_Java_Conventions.xml`文件。

![Code style](https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/docs/src/main/asciidoc/images/intellij-inspections.png)

图 2。检查剖面

转到`File``Settings``Editor``Inspections`。点击`Profile`区域旁边的图标。在那里，单击`Import Profile`并导入`spring-cloud-build-tools/src/main/resources/intellij/Intellij_Project_Defaults.xml`文件。

Checkstyle

要让 IntelliJ 使用 CheckStyle，你必须安装`Checkstyle`插件。建议还安装`Assertions2Assertj`来自动转换 JUnit 断言

![Checkstyle](https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/docs/src/main/asciidoc/images/intellij-checkstyle.png)

转到`File``Settings``Other settings``Checkstyle`。点击`+`区域中的`Configuration file`图标。在这里，你必须定义应该从哪里选择 CheckStyle 规则。在上面的图片中，我们从克隆的云构建存储库中选择了规则。但是，你可以指向 Spring Cloud Build 的 GitHub 存储库（例如`checkstyle.xml`:`[https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/spring-cloud-build-tools/src/main/resources/checkstyle.xml](https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/spring-cloud-build-tools/src/main/resources/checkstyle.xml)`）。我们需要提供以下变量：

* `checkstyle.header.file`-请将其指向 Spring Cloud Build 的`spring-cloud-build-tools/src/main/resources/checkstyle-header.txt`文件，可以在你的克隆 repo 中，也可以通过`[https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/spring-cloud-build-tools/src/main/resources/checkstyle-header.txt](https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/spring-cloud-build-tools/src/main/resources/checkstyle-header.txt)`URL。

* `checkstyle.suppressions.file`-默认抑制。请将它指向 Spring Cloud Build 的`spring-cloud-build-tools/src/checkstyle/checkstyle-suppressions.xml`文件，或者在你的克隆 repo 中，或者通过`[https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/spring-cloud-build-tools/src/checkstyle/checkstyle-suppressions.xml](https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/spring-cloud-build-tools/src/checkstyle/checkstyle-suppressions.xml)`URL。

* `checkstyle.additional.suppressions.file`-此变量对应于本地项目中的抑制。例如，你正在处理`spring-cloud-contract`。然后指向`project-root/src/checkstyle/checkstyle-suppressions.xml`文件夹。`spring-cloud-contract`的例子是：`/home/username/spring-cloud-contract/src/checkstyle/checkstyle-suppressions.xml`。

|   |请记住将`Scan Scope`设置为`All sources`，因为我们为生产和测试源应用了 checkstyle 规则。|
|---|------------------------------------------------------------------------------------------------------------------|

### [重复查找器](#_duplicate_finder)

Spring Cloud构建带来了`basepom:duplicate-finder-maven-plugin`，它允许在 Java Classpath 上标记重复的和冲突的类和资源。

#### [重复查找器配置](#_duplicate_finder_configuration)

重复查找器是**默认启用**，将在 Maven 构建的`verify`阶段运行，但是只有在将`duplicate-finder-maven-plugin`添加到项目的`build`部分`POM.xml`时，它才会在项目中生效。

pom.xml

```
<build>
    <plugins>
        <plugin>
            <groupId>org.basepom.maven</groupId>
            <artifactId>duplicate-finder-maven-plugin</artifactId>
        </plugin>
    </plugins>
</build>
```

对于其他属性，我们设置了[插件文档](https://github.com/basepom/duplicate-finder-maven-plugin/wiki)中列出的默认值。

你可以轻松地重写它们，但可以使用`duplicate-finder-maven-plugin`前缀设置所选属性的值。例如，将`duplicate-finder-maven-plugin.skip`设置为`true`，以便在构建中跳过重复检查。

如果需要将`ignoredClassPatterns`或`ignoredResourcePatterns`添加到设置中，请确保将它们添加到项目的插件配置部分中：

```
<build>
    <plugins>
        <plugin>
            <groupId>org.basepom.maven</groupId>
            <artifactId>duplicate-finder-maven-plugin</artifactId>
            <configuration>
                <ignoredClassPatterns>
				    <ignoredClassPattern>org.joda.time.base.BaseDateTime</ignoredClassPattern>
					<ignoredClassPattern>.*module-info</ignoredClassPattern>
				</ignoredClassPatterns>
                <ignoredResourcePatterns>
                    <ignoredResourcePattern>changelog.txt</ignoredResourcePattern>
                </ignoredResourcePatterns>
            </configuration>
        </plugin>
    </plugins>
</build>
```

## [压平 Poms](#_flattening_the_poms)

为了避免传播构建 Spring Cloud项目所需的构建设置，我们使用了 Maven Flaten 插件。它的优点是允许你在将“Clean” POM 发布到存储库时使用所需的任何功能。

为了添加它，将`org.codehaus.mojo:flatten-maven-plugin`添加到你的`pom.xml`中。

```
<build>
	<plugins>
		<plugin>
			<groupId>org.codehaus.mojo</groupId>
			<artifactId>flatten-maven-plugin</artifactId>
		</plugin>
	</plugins>
</build>
```

## [重用文档](#_reusing_the_documentation)

Spring Cloud Build 发布其`spring-cloud-build-docs`模块，该模块包含有用的脚本（例如 Readme Generation Ruby 脚本）和用于 Spring Cloud文档的 CSS、XSLT 和图像。如果你想遵循生成文档的相同约定方法，只需将这些插件添加到`docs`模块中

```
<properties>
	<upload-docs-zip.phase>deploy</upload-docs-zip.phase> (8)
</properties>
<profiles>
	<profile>
		<id>docs</id>
		<build>
			<plugins>
				<plugin>
					<groupId>pl.project13.maven</groupId>
					<artifactId>git-commit-id-plugin</artifactId> (1)
				</plugin>
				<plugin>
					<groupId>org.apache.maven.plugins</groupId>
					<artifactId>maven-dependency-plugin</artifactId> (2)
				</plugin>
				<plugin>
					<groupId>org.apache.maven.plugins</groupId>
					<artifactId>maven-resources-plugin</artifactId> (3)
				</plugin>
				<plugin>
					<groupId>org.codehaus.mojo</groupId>
					<artifactId>exec-maven-plugin</artifactId> (4)
				</plugin>
				<plugin>
					<groupId>org.asciidoctor</groupId>
					<artifactId>asciidoctor-maven-plugin</artifactId> (5)
				</plugin>
				<plugin>
					<groupId>org.apache.maven.plugins</groupId>
					<artifactId>maven-antrun-plugin</artifactId> (6)
				</plugin>
				<plugin>
					<artifactId>maven-deploy-plugin</artifactId> (7)
				</plugin>
			</plugins>
		</build>
	</profile>
</profiles>
```

|**1**|这个插件下载设置了项目的所有 Git 信息。|
|-----|----------------------------------------------------------------------------------------------------------------------------------------------------------|
|**2**|此插件下载`spring-cloud-build-docs`模块的资源|
|**3**|此插件解包`spring-cloud-build-docs`模块的资源|
|**4**|这个插件生成一个`adoc`文件，其中包含 Classpath 中的所有配置属性。|
|**5**|解析 ASCIIDoctor 文档需要使用此插件。|
|**6**|需要此插件来将资源复制到正确的最终目的地，并生成主 readme.ADOC，并断言没有文件使用未解决的链接|
|**7**|此插件确保生成的 ZIP DOCS 将被发布|
|**8**|此属性打开 \<7\>的“部署”阶段|

|   |插件声明的顺序很重要！|
|---|---------------------------------------------|

为了使构建生成带有所有配置属性的`adoc`文件，你的`docs`模块应该包含与 Classpath 相关的所有依赖项，你需要扫描这些依赖项以获取配置属性。该文件将被输出到`${docsModule}/src/main/asciidoc/_configprops.adoc`文件（可通过`configprops.path`属性进行配置）。

如果你想修改将哪些配置属性放入表中，你可以调整`configprops.inclusionPattern`模式，以仅包括属性的一个子集（例如`<configprops.inclusionPattern>spring.sleuth.*</configprops.inclusionPattern>`）。

Spring Cloud构建 DOCS 附带了一组可以重用的 ASCIIDoctor 属性。

```
<attributes>
	<docinfo>shared</docinfo>
	<allow-uri-read>true</allow-uri-read>
	<nofooter/>
	<toc>left</toc>
	<toc-levels>4</toc-levels>
	<sectlinks>true</sectlinks>
	<sources-root>${project.basedir}/[email protected]</sources-root>
	<asciidoc-sources-root>${project.basedir}/src/main/[email protected]</asciidoc-sources-root>
	<generated-resources-root>${project.basedir}/target/[email protected]
	</generated-resources-root>
	<!-- Use this attribute the reference code from another module -->
	<!-- Note the @ at the end, lowering the precedence of the attribute -->
	<project-root>${maven.multiModuleProjectDirectory}@</project-root>
	<!-- It's mandatory for you to pass the docs.main property -->
	<github-repo>${docs.main}@</github-repo>
	<github-project>https://github.com/spring-cloud/${docs.main}@</github-project>
	<github-raw>
		https://raw.githubusercontent.com/spring-cloud/${docs.main}/${github-tag}@
	</github-raw>
	<github-code>https://github.com/spring-cloud/${docs.main}/tree/${github-tag}@
	</github-code>
	<github-issues>https://github.com/spring-cloud/${docs.main}/issues/@</github-issues>
	<github-wiki>https://github.com/spring-cloud/${docs.main}/[email protected]</github-wiki>
	<github-master-code>https://github.com/spring-cloud/${docs.main}/tree/[email protected]
	</github-master-code>
	<index-link>${index-link}@</index-link>

	<!-- Spring Cloud specific -->
	<!-- for backward compatibility -->
	<spring-cloud-version>${project.version}@</spring-cloud-version>
	<project-version>${project.version}@</project-version>
	<github-tag>${github-tag}@</github-tag>
	<version-type>${version-type}@</version-type>
	<docs-url>https://docs.spring.io/${docs.main}/docs/${project.version}@</docs-url>
	<raw-docs-url>${github-raw}@</raw-docs-url>
	<project-version>${project.version}@</project-version>
	<project-name>${docs.main}@</project-name>
</attributes>
```

## [更新指南](#_updating_the_guides)

我们假设你的项目包含`guides`文件夹下的指南。

```
.
└── guides
	├── gs-guide1
	├── gs-guide2
	└── gs-guide3
```

这意味着该项目包含 3 个指南，与 Spring Guides org 中的以下指南相对应。

* [https://github.com/spring-guides/gs-guide1](https://github.com/spring-guides/gs-guide1)

* [https://github.com/spring-guides/gs-guide2](https://github.com/spring-guides/gs-guide2)

* [https://github.com/spring-guides/gs-guide3](https://github.com/spring-guides/gs-guide3)

如果你使用`-Pguides`配置文件来部署你的项目，则如下所示

```
$ ./mvnw clean deploy -Pguides
```

将会发生的情况是，对于 GA 项目版本，我们将克隆`gs-guide1`、`gs-guide2`和`gs-guide3`，并使用位于`guides`项目下的内容更新它们的内容。

通过不添加`guides`配置文件，或者在打开配置文件时传递`-DskipGuides`系统属性，你可以跳过此操作。

你可以通过`guides-project.version`（默认为`${project.version}`）配置传递给指南的项目版本。指南更新的阶段可以通过`guides-update.phase`进行配置（默认为`deploy`）。

如果{{{i[’GoogleAnalyticsObject’]=r；i[r]=i[r]|function（）{q=i[r].push（参数）}，i[r].l=1\*new date（）；a=s.createElement（o），m=s.getelementsbyName（0）；a.parentsName（1）；a.A.SRC=g；m.M.analytnode（gua，m.com.com）；（google=document=’，’，’’’’’’’’），’documents’，’’.’’’’’’’’’’’，’’’’’’