# 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 的项目风格约定 |
图 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
文件。
图 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 断言
转到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
,以便在构建中跳过重复检查。
如果需要将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
为了避免传播构建 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 中的以下指南相对应。
https://github.com/spring-guides/gs-guide1 (opens new window)
https://github.com/spring-guides/gs-guide2 (opens new window)
https://github.com/spring-guides/gs-guide3 (opens new window)
如果你使用-Pguides
配置文件来部署你的项目,则如下所示
$ ./mvnw clean deploy -Pguides
将会发生的情况是,对于 GA 项目版本,我们将克隆gs-guide1
、gs-guide2
和gs-guide3
,并使用位于guides
项目下的内容更新它们的内容。
通过不添加guides
配置文件,或者在打开配置文件时传递-DskipGuides
系统属性,你可以跳过此操作。
你可以通过guides-project.version
(默认为${project.version}
)配置传递给指南的项目版本。指南更新的阶段可以通过guides-update.phase
进行配置(默认为deploy
)。