作者 | 良名 阿里巴巴技术专家
背景
相信很多人都使用过 start.spring.io 来初始化自己的 Spring Boot 工程，这个工具为开发者提供了丰富的可选组件，并且可以选择多种打包方式，大大方便了开发人员的使用。最近，阿里的 Nacos、Sentinel 也进入 start.spring.io 的选项中，进一步的方便开发者使用阿里云的产品。
但是，生成的工程骨架中，只有组件坐标信息，缺少对应的使用方法和 Demo 代码；于是，开发者还是需要去寻找相关使用教程，或者样例代码；如果找的不对，或者是版本不匹匹配，还需要花费不少时间去排查和解决问题；这些问题都在无形中增加用户的工作量。我们将对软件工程的抽象层次自上而下进行切分，会得到如下的几个层级：行业、解决方案、应用、功能、组件；明显的， start.spring.io 目前只能提供组件级别的支持。再将组件这层展开，会发现这样一个生命周期：组件引入、组件配置、功能开发、线上运维。start.spring.io 也只实现了“组件引入”这一功能。我们的目标是“让阿里云成为广大 Java 开发者最好用的云”。要实现这个目标，是否可以再向前走几步，在解决“组件引入”问题的基础上，将组件的典型使用方法、样例代码、使用说明也加入到工程中呢？基于这种思考，我们上线了自己的 bootstrap 站点 start.aliyun.com ：https://start.aliyun.com/当然，本着不重复造轮子的原则，我们不再构建一套工程生成底层框架，而是使用 Spring Initializr 来实现这部分功能。在此之上专注于增加新特性，实现服务广大开发者的目标。Spring Initializr：https://github.com/spring-io/initializr在 start.aliyun.com 中，我们为广大开发者带来了如下便利特性：为每个组件提供了单独的 DemoCode 和对应的配置样例(本次已发布)；
工程内置说明，减少用户查找文档的困难(部分实现)；
开发者只需要做减法，而非加法的使用方式(部分实现)；
提供多组件集成的解决方案(开发中)；
定期跟进 start.spring.io 的更新，方便大家使用到 spring 的最新功能。
使用篇
由于 spring-initializr 提供了灵活的扩展能力，以及丰富的默认实现；其使用方式也是非常的灵活多变；为了便于说明，我们直接通过 start.spring.io ，看看 Spring 自己是怎么使用这套框架的。1. 基本用法
基本用法的原则，是尽量少写代码，甚至是不写代码。只通过配置就可以实现 initializr 工程的创建。依赖引入
要使用 spring-initializr ，首先要引入这套框架。很简单，直接依赖 bom 即可：<dependencyManagement>
<dependencies>
<dependency>
<groupId>io.spring.initializrgroupId>
<artifactId>initializr-bomartifactId>
<version>0.9.0.BUILD-SNAPSHOTversion>
<type>pomtype>
<scope>importscope>
dependency>
dependencies>
dependencyManagement>有了这个 bom 依赖，我们就不用再关心内部组件的版本等信息了。<dependency>
<groupId>io.spring.initializrgroupId>
<artifactId>initializr-generator-springartifactId>
dependency>
<dependency>
<groupId>io.spring.initializrgroupId>
<artifactId>initializr-version-resolverartifactId>
dependency>
<dependency>
<groupId>io.spring.initializrgroupId>
<artifactId>initializr-webartifactId>
dependency>- initializr-actuator: 监控诊断的附加信息，这个暂时忽略；
- initializr-bom: 便于外部使用的bom依赖；
- initializr-docs: 使用文档；
- initializr-generator: 核心工程生成库；
- initializr-generator-spring: 用于生成典型的spring boot工程；
- initializr-generator-test: 测试框架；
- initializr-metadata: 项目各个方面的元数据基础结构；
- initializr-service-sample: 基本使用案例；
- initializr-version-resolver:版本号解析能力；
- initializr-web: 提供给三方客户端使用的web入口。
基本配置
完成了框架引入，就需要做一些基础配置了
支持哪些语言：Java、groovy、Kotlin
支持哪些版本：1.8、11、13
支持哪些打包方式：jar、war
initializr:
packagings:
- name: Jar
id: jar
default: true
- name: War
id: war
default: false
javaVersions:
- id: 13
default: false
- id: 11
default: false
- id: 1.8
name: 8
default: true
languages:
- name: Java
id: java
default: true
- name: Kotlin
id: kotlin
default: false
- name: Groovy
id: groovy
default: falseinitializr:
types:
- name: Maven Project
id: maven-project
description: Generate a Maven based project archive.
tags:
build: maven
format: project
default: true
action: /starter.zip
- name: Maven POM
id: maven-build
description: Generate a Maven pom.xml.
tags:
build: maven
format: build
default: false
action: /pom.xml
- name: Gradle Project
id: gradle-project
description: Generate a Gradle based project archive.
tags:
build: gradle
format: project
default: false
action: /starter.zip
- name: Gradle Config
id: gradle-build
description: Generate a Gradle build file.
tags:
build: gradle
format: build
default: false
action: /build.gradle- /pom.xml 生成一个 Maven 的 pom.xml 配置文件
- /build.gradle 生成 Gradle 的配置文件
- /starter.zip 生成 zip 方式压缩的工程文件
- /starter.tgz 生成以 tgz 方式压缩的工程文件
配置基本依赖
完成了基本配置以后，就可以配置可选的依赖组件了。依赖配置以 dependency 为 key ，同样配置在 application.yml 的 initializr 下面，这里给出一个简单的样例：initializr:
dependencies:
- name: Web
content:
- name: Web
id: web
description: Full-stack web development with Tomcat and Spring MVC
- name: Developer Tools
content:
- name: Spring Boot DevTools
id: devtools
groupId: org.springframework.boot
artifactId: spring-boot-devtools
description: Provides fast application restarts, LiveReload, and configurations for enhanced development experience.
- name: Lombok
id: lombok
groupId: org.projectlombok
artifactId: lombok
description: Java annotation library which helps to reduce boilerplate code.- id：组件的唯一标识符
- groupId & artifactId：组件的坐标
- name：显示名称
- description：描述信息，主要用于展示用途
- version：组件版本
关于 groupId & artifactId：如果设置了坐标，生成的项目里会使用这里的坐标定位组件；但是如果没有设置坐标，框架会认为这是一个标准的 spring-boot 组件，自动添加 spring-boot-starter-{id} 作为生成的依赖坐标。
关于 version：如果直接在组件上设置版本信息，框架会直接使用这个值作为组件依赖的版本；但是很多时候，组件的版本会受到 spring-boot 版本的影响，此时就需要对版本做特殊的定义 & 管理。
配置依赖版本管理
这里需要先了解一下版本命名规则：一个典型的版本，一般包含如下 4 个信息：大版本、小版本、修正版本、版本限定符。版本范围有一个上界和下界，可以方括号 [] 或者圆括号 () 表示。方括号代表上下界的闭区间，圆括号代表上下界的开区间。例如：“[1.1.6.RELEASE,1.3.0.M1)”代表所有从 1.1.6.RELEASE 到 1.3.0.M1 之间所有的版本(包含 1.1.6.RELEASE ，但不包含 1.3.0.M1 )。同时，可以使用单一版本号作为版本范围，例如 “1.2.0.RELEASE”。单一版本号的版本范围代表“从这个版本以及之后的所有版本”。如果需要使用“最新的 Release 版本”的概念，可以使用一个字母 x 代表具体的版本号。例如， 1.4.x.BUILD-SNAPSHOT 代表 1.4.x 的最新快照版本。再比如：如果需要表达，从 1.1.0.RELEASE 到 1.3.x 之间的所有版本，可以用[1.1.0.RELEASE,1.3.x.RELEASE]来表达。另外，版本限定符也是有顺序的(升序)：- M：里程碑版本
- RC：发布候选版本
- RELEASE：发布版本
- BUILD-SNAPSHOT：为开发构建的快照版本
直接定义在组件(或 Bom )上
initializr:
dependencies:
- name: Stuff
content:
- name: Foo
id: foo
...
compatibilityRange: 1.2.0.M1
- name: Bar
id: bar
...
compatibilityRange: "[1.5.0.RC1,2.0.0.M1)"定义在组件的 mappgin 属性下
initializr:
dependencies:
- name: Stuff
content:
- name: Foo
id: foo
groupId: org.acme.foo
artifactId: foo-spring-boot-starter
compatibilityRange: 1.3.0.RELEASE
mappings:
- compatibilityRange: "[1.3.0.RELEASE,1.3.x.RELEASE]"
artifactId: foo-starter
- compatibilityRange: "1.4.0.RELEASE"使用 Bom 管理版本：有时候，需要使用 Bom 的方式管理组件版本；此时不需要对组件单独设置版本号。
要使用 Bom ，首先要配置 Bom 定义：initializr:
env:
boms:
my-api-bom:
groupId: org.acme
artifactId: my-api-dependencies
version: 1.0.0.RELEASE
repositories: my-api-repo-1注意：Bom 信息，定义在 initializr.env.boms下面。initializr:
dependencies:
- name: Other
content:
- name: My API
id : my-api
groupId: org.acme
artifactId: my-api
bom: my-api-bom2. 高级定制
启用缓存
如果你启动过 start.spring.io 项目，你会在日志里发现这样的输出 “Fetching boot metadata from spring.io/project_metadata/spring-boot” 为了避免过于频繁的检查 Spring Boot 版本，官方是建议配合缓存一起使用。首先需要引入缓存框架：<dependency>
<groupId>javax.cachegroupId>
<artifactId>cache-apiartifactId>
dependency>
<dependency>
<groupId>org.ehcachegroupId>
<artifactId>ehcacheartifactId>
dependency>
如果需要自己定义缓存，可以调整如下缓存配置：
为不同的组件增加独立配置：还记得原理篇中提到的 spring.factories 吗？对，我们要增加自己的配置项，就需要在这里增加针对不同组件样例代码的扩展入口。
io.spring.initializr.generator.project.ProjectGenerationConfiguration=\
com.alibaba.alicloud.initializr.extension.dependency.springboot.SpringCloudProjectGenerationConfiguration@ProjectGenerationConfiguration
public class SpringCloudAlibabaProjectGenerationConfiguration {
private final InitializrMetadata metadata;
private final ProjectDescription description;
private final IndentingWriterFactory indentingWriterFactory;
private final TemplateRenderer templateRenderer;
public SpringCloudAlibabaProjectGenerationConfiguration(InitializrMetadata metadata,
ProjectDescription description,
IndentingWriterFactory indentingWriterFactory,
TemplateRenderer templateRenderer) {
this.metadata = metadata;
this.description = description;
this.indentingWriterFactory = indentingWriterFactory;
this.templateRenderer = templateRenderer;
}
@Bean
@ConditionalOnRequestedDependency("sca-oss")
public OSSDemoCodeContributor ossContributor() {
return new OSSDemoCodeContributor(description, templateRenderer);
}
......
}生成具体的 Demo 代码：继续以 OSSDemoCodeContributor 为例，它是一个 ProjectContributor ，会在项目文件空间创建完成了调用。我们需要为这个 Contributor 在实例化时增加生成过程中需要的元数据信息，例如 ProjectDescription 。
代码生成过程，比较简单，可以直接复用框架中就提供的 mstache 模板引擎。我们直接将 Demo 代码，以模板的形式，放置在 resources 文件夹之下：
然后，我们再通过模板引擎，解析这些模板文件，再拷贝到项目目录下即可： private void writeCodeFile(TemplateRenderer templateRenderer, Language langeuage,
Map<String, Object> params, Path path, String temp) throws IOException {
......
Path pkgPath = 生成包路径
Path filePath = 成成代码文件路径
// 渲染模板
String code = templateRenderer.render(temp, params);
// demo 文件写入
Files.createDirectories(pkgPath);
Files.write(filePath, code.getBytes("UTF-8"));
}
原理篇
原理篇，主要介绍 spring.initializr 是如何实现项目工程构建的，以及作为一个框架，如何提供丰富的扩展能力的。在原理篇，我们将 initializr 的执行分为两个阶段：启动阶段和生成阶段。- 启动阶段：启动应用，加载配置，扩展信息初始化；
- 生成阶段：一个项目生成，从收到请求，到返回内容的完整流程。
1. 启动阶段
再开始启动流程之前，先要看一下 initializr 的扩展体系。整个架构大量使用了 spring 的 spi 机制，我们来看一下一共有哪些 spring.factories ：initializr-generator/src/main/resources/META-INF/spring.factories
initializr-generator-spring/src/main/resources/META-INF/spring.factories
initializr-web/src/main/resources/META-INF/spring.factories
initializr-actuator/src/main/resources/META-INF/spring.factories
start-site/src/main/resources/META-INF/spring.factories
@Configuration
@EnableConfigurationProperties(InitializrProperties.class)
public class InitializrAutoConfiguration {
@Bean
@ConditionalOnMissingBean
public ProjectDirectoryFactory projectDirectoryFactory()
@Bean
@ConditionalOnMissingBean
public IndentingWriterFactory indentingWriterFactory()
@Bean
@ConditionalOnMissingBean(TemplateRenderer.class)
public MustacheTemplateRenderer templateRenderer(Environment environment, ObjectProvider cacheManager)@Bean@ConditionalOnMissingBeanpublic InitializrMetadataUpdateStrategy initializrMetadataUpdateStrategy(RestTemplateBuilder restTemplateBuilder,
ObjectMapper objectMapper)@Bean@ConditionalOnMissingBean(InitializrMetadataProvider.class)public InitializrMetadataProvider initializrMetadataProvider(InitializrProperties properties,
InitializrMetadataUpdateStrategy initializrMetadataUpdateStrategy)@Bean@ConditionalOnMissingBeanpublic DependencyMetadataProvider dependencyMetadataProvider()@Configuration@ConditionalOnWebApplication
static class InitializrWebConfiguration {@Bean
InitializrWebConfig initializrWebConfig()@Bean@ConditionalOnMissingBean
ProjectGenerationController projectGenerationController(
InitializrMetadataProvider metadataProvider, ApplicationContext applicationContext)@Bean@ConditionalOnMissingBean
ProjectMetadataController projectMetadataController(InitializrMetadataProvider metadataProvider,
DependencyMetadataProvider dependencyMetadataProvider)@Bean@ConditionalOnMissingBean
CommandLineMetadataController commandLineMetadataController(InitializrMetadataProvider metadataProvider,
TemplateRenderer templateRenderer)@Bean@ConditionalOnMissingBean
SpringCliDistributionController cliDistributionController(InitializrMetadataProvider metadataProvider)
}
}- 初始化元数据 Provider
- 创建模板引擎
- 创建目录、缩进工厂
- 初始化 web 配置
- 创建 spring mvc 的 web 入口
- 各种 ProjectGenerationController
在 application.yml 文件中，可以找到如下的配置信息，这里就是实际的项目依赖关系元数据的配置存储点：
整体来看，启动阶段的动作还是比较简单的，这也是为什么 start.spring.io 启动只需要数秒的原因。更多的逻辑，都被留在了工程生成阶段。2. 生成阶段
生成阶段，spring-initializr 使用了一个很有意思的实现方式：initializr 框架会为每一次项目生成，创建一个独立的 context 用于存放生成流程中需要使用到的各种 bean 。先来一张时序图：
蓝色的类，是在应用启动阶段就完成了创建和数据填充；其生命周期和整个应用一致；
黄色的类，会在具体的项目构建过程中生成；其生命周期在一次项目生成流程之内结束。
主干流程
下图，是 ProjectGenerator 的核心构建流程：
106 行，通过 contextFactory 构建了一个新的 ProjectGenerationContext 。看一下这个context的继承关系，原来于spring提供的AnnotationConfigApplicationContext 。再结合 110 行的 refresh() 方法，是不是发现了什么？就是 spring 的 ApplicationContext 的刷新流程。
107 行的 resolve 方法，向 context 中注册了一个 ProjectDescription的Provider，代码如下：
由于注册的是 Provider ，所以这段逻辑会在 Context 执行 refresh 时运行。这里的 ProjectDescriptionCustomizer 就是针对 ProjectDescription 的扩展，用于对用户传入的 ProjectDescription 做调整。这里主要是一些强制依赖关系的调整，例如语言版本等。这时候再看 108 行，这里向 Context 注册一个 Configuration 。那么这个这个 Configuration 包含了什么内容呢？一起来看下面这段代码：
ProjectGenerationConfiguration！！！前面提到的 spring.factories 中有很多这个 SPI 的实现(参见参考资料)。原来，initializr 的整个扩展体系，在这里才开始创建实例；ProjectGenerator 的 109 行，对一个 consumer 做了 accept 操作；其实就是调用了下面的代码：
这里通过 setParent 将应用的主上下文设置为这次 ProjectGenerationContext 的父节点。并且向这次 ProjectGenerationContext 中注册了元数据对象。最后，在 ProjectGenerator 的 112 行，调用了 projectAssetGenerator 的 generate 方法，实现如下：
通过上面的代码可以发现，这里对实际的工程构建工作，其实就是很多的 ProjectContributor 共同叠加；至此，主干流程已经结束了。我们可以发现，在主干流程中，没有做任何写文件的操作(只创建了根文件夹)；它仅仅是定义了一套数据加载、扩展加载的机制与流程，将所有的具体实现都作为扩展的一部分。扩展流程
spring-initializr 提供了 2 种主要扩展途径：ProjectContributor 和 xxxxxCustomizer。
从方法签名就可以看出，入参只有一个项目的根路径，其职责就是向这个路径下些人项目文件。这个扩展点非常的灵活，几乎可以支持任何的代码、配置文件写入工作。实现过程中，可以通过 ProjectGenerationContext 获取相关依赖，然后通过自定义逻辑完成文件生成工作。下面是 initializr 和 start.spring.io 提供的 ProjectContributor 实现：
拿几个主要的实现看看：- MavenBuildProjectContributor：写入 maven 项目 pom.xml 文件；
- WebFoldersContributor：创建 web 项目的资源文件夹；
- ApplicationPropertiesContributor：写入 application.properties 文件；
- MainSourceCodeProjectContributor：写入应用入口类 xxxApplication.java 文件；
- HelpDocumentProjectContributor：写入帮助文档 HELP.md 文件。
- MainApplicationTypeCustomizer：自定义 MainApplication 类；
- MainCompilationUnitCustomizer：自定义 MainApplication 编译单元；
- MainSourceCodeCustomizer：自定义 MainApplication 源码；
- BuildCustomizer：自定义项目构建工具的配置内容；
- GitIgnoreCustomizer：自定义项目的 .gitignore 文件；
- HelpDocumentCustomizer：自定义项目的帮助文档；
- InitializrMetadataCustomizer：自定义项目初始化配置元数据；这个 Customizer 比较特殊，框架会在首次加载元数据配置时调用；
- ProjectDescriptionCustomizer：自定义 ProjectDescription ；即在生成项目文件之前，允许调整项目描述信息；
- ServletInitializerCustomizer：自定义 web 应用在类上的配置内容；
- TestApplicationTypeCustomizer：自定义测试 Application 类；
- TestSourceCodeCustomizer：自定义测试 Application 类的源码。
参考资料
1. 相关链接
initializr 说明文档
spring-initializr 项目地址
start.spring.io 项目地址
2. spring.factories 明细
initializr-generator/src/main/resources/META-INF/spring.factoriesio.spring.initializr.generator.buildsystem.BuildSystemFactory=\
io.spring.initializr.generator.buildsystem.gradle.GradleBuildSystemFactory,\
io.spring.initializr.generator.buildsystem.maven.MavenBuildSystemFactory
io.spring.initializr.generator.language.LanguageFactory=\
io.spring.initializr.generator.language.groovy.GroovyLanguageFactory,\
io.spring.initializr.generator.language.java.JavaLanguageFactory,\
io.spring.initializr.generator.language.kotlin.KotlinLanguageFactory
io.spring.initializr.generator.packaging.PackagingFactory=\
io.spring.initializr.generator.packaging.jar.JarPackagingFactory,\
io.spring.initializr.generator.packaging.war.WarPackagingFactory
io.spring.initializr.generator.project.ProjectGenerationConfiguration=\
io.spring.initializr.generator.spring.build.BuildProjectGenerationConfiguration,\
io.spring.initializr.generator.spring.build.gradle.GradleProjectGenerationConfiguration,\
io.spring.initializr.generator.spring.build.maven.MavenProjectGenerationConfiguration,\
io.spring.initializr.generator.spring.code.SourceCodeProjectGenerationConfiguration,\
io.spring.initializr.generator.spring.code.groovy.GroovyProjectGenerationConfiguration,\
io.spring.initializr.generator.spring.code.java.JavaProjectGenerationConfiguration,\
io.spring.initializr.generator.spring.code.kotlin.KotlinProjectGenerationConfiguration,\
io.spring.initializr.generator.spring.configuration.ApplicationConfigurationProjectGenerationConfiguration,\
io.spring.initializr.generator.spring.documentation.HelpDocumentProjectGenerationConfiguration,\
io.spring.initializr.generator.spring.scm.git.GitProjectGenerationConfigurationorg.springframework.boot.autoconfigure.EnableAutoConfiguration=\
io.spring.initializr.web.autoconfigure.InitializrAutoConfiguration
org.springframework.boot.env.EnvironmentPostProcessor=\
io.spring.initializr.web.autoconfigure.CloudfoundryEnvironmentPostProcessororg.springframework.boot.autoconfigure.EnableAutoConfiguration=\
io.spring.initializr.actuate.autoconfigure.InitializrActuatorEndpointsAutoConfiguration,\
io.spring.initializr.actuate.autoconfigure.InitializrStatsAutoConfigurationio.spring.initializr.generator.project.ProjectGenerationConfiguration=\
io.spring.start.site.extension.build.gradle.GradleProjectGenerationConfiguration,\
io.spring.start.site.extension.build.maven.MavenProjectGenerationConfiguration,\
io.spring.start.site.extension.dependency.DependencyProjectGenerationConfiguration,\
io.spring.start.site.extension.dependency.springamqp.SpringAmqpProjectGenerationConfiguration,\
io.spring.start.site.extension.dependency.springboot.SpringBootProjectGenerationConfiguration,\
io.spring.start.site.extension.dependency.springcloud.SpringCloudProjectGenerationConfiguration,\
io.spring.start.site.extension.dependency.springdata.SpringDataProjectGenerationConfiguration,\
io.spring.start.site.extension.dependency.springintegration.SpringIntegrationProjectGenerationConfiguration,\
io.spring.start.site.extension.dependency.springrestdocs.SpringRestDocsProjectGenerationConfiguration,\
io.spring.start.site.extension.description.DescriptionProjectGenerationConfiguration,\
io.spring.start.site.extension.code.kotin.KotlinProjectGenerationConfiguration
戳原文，立即预约直播！
