# Spring Cloud构建

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

# 构建和部署

要在本地安装:

$ 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 签名,并且存储库必须为该项目单独指定,因为它是启动器父程序的父程序,用户反过来将其作为自己的父程序)。

# 贡献

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

# 签署贡献者许可协议

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

# 行为守则

该项目遵守贡献者契约行为守则 (opens new window)。通过参与,你将被期望坚持这一准则。请向[[电子邮件保护]]报告不可接受的行为(/cdn-cgi/l/email-protection#DBA8aba9b2b5bcf6b8b4bfbef6b4bdf6b8b8b4b5bfaeb8af9babb2adb4afbab7f5b2b4)。

# 守则惯例和内部管理

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

  • 使用 Spring 框架代码格式约定。如果使用 Eclipse,则可以使用eclipse-code-formatter.xml文件从Spring Cloud Build (opens new window)项目导入格式化设置。如果使用 IntelliJ,可以使用Eclipse 代码格式化插件 (opens new window)导入相同的文件。

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

  • 将 ASF 许可标头注释添加到所有新的.java文件(从项目中的现有文件复制)

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

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

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

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

  • 在编写提交消息时,请遵循这些约定 (opens new window),如果你正在修复现有的问题,请在提交消息的末尾添加Fixes gh-XXXX(其中 xxxx 是问题编号)。

# 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 规则是默认禁用。要将 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

# Intellij 思想

为了设置 IntelliJ,你应该导入我们的编码约定、检查配置文件并设置 CheckStyle 插件。以下文件可以在Spring Cloud Build (opens new window)项目中找到。

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

图 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

图 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

转到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 规则。

# 重复查找器

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

# 重复查找器配置

重复查找器是默认启用,将在 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>

对于其他属性,我们设置了插件文档 (opens new window)中列出的默认值。

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

如果需要将ignoredClassPatternsignoredResourcePatterns添加到设置中,请确保将它们添加到项目的插件配置部分中:

<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

为了避免传播构建 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>

# 重用文档

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>

# 更新指南

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

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

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

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

$ ./mvnw clean deploy -Pguides

将会发生的情况是,对于 GA 项目版本,我们将克隆gs-guide1gs-guide2gs-guide3,并使用位于guides项目下的内容更新它们的内容。

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

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