Alibaba Cloud Unveils New Spring Boot Scaffold

Image for post
Image for post

By Chen Xi (Liangming), a technical expert at Alibaba. Mr. Chen is a member of the app container and service framework team and a member of the Spring Cloud Alibaba project, committed to optimizing Alibaba Cloud for Java developers.


Image for post
Image for post

However, the project skeleton only includes the component coordinate information, with no demo code or usage methods. Therefore, developers have to refer to relevant tutorials or sample code. In the case of inappropriate references or version mismatch, developers have to spend a lot of time troubleshooting, significantly increasing the development workload.

Software engineering abstraction is usually divided into various layers from the top-down, including industry, solution, application, function, and component. Currently, only supports the component layer. The component layer contains a lifecycle that runs through component introduction, component configuration, and function development to online O&M. only implements component introduction.

Our goal is to optimize Alibaba Cloud for Java developers. To achieve this goal, we need to enable support for the component introduction and add the sample code as well as the methods and instructions for using components to projects.

Based on this approach, we launched our own bootstrap website:

To avoid reinventing the wheel, we implement component introduction through Spring Initializr rather than creating a project to build the underlying framework followed by developing new features to help developers.

Spring Initializr: provides the following features to developers:

  • An Independent demo code and a configuration sample are provided for each component. This feature is currently available.
  • Project instructions are built in to facilitate document retrieval. This feature is partially available.
  • Developers only need to perform subtraction, not addition. This feature is partially available.
  • A solution for multi-component integration is provided. This feature is under development.
  • We regularly follow up updates so that everyone uses the latest features of Spring

In the future, we will provide more support to developers, enabling them to better integrate components, access more features and services, and quickly build applications.

This article uses as an example to describe how to use and extend the Spring Initializr framework.

How to Use Spring Initializr

1) Basic Usage

Introduce Dependencies

We must introduce Spring Initializr before using it. Thus, directly introduce the BOM dependency, which ensures that there is no need to worry about internal component versions.


Generally, we also need to introduce specific components.


The following submodules are available:

  • initializr-actuator provides additional information about monitoring and diagnosis. It is not described here.
  • initializr-bom supports the external use of BOM dependency.
  • initializr-docs provides instruction documentation.
  • initializr-generator provides a library for creating core projects.
  • initializr-generator-spring is used to create typical Spring Boot projects.
  • initializr-generator-test provides a test framework.
  • initializr-metadata implements the basic structure for all metadata in a project.
  • initializr-service-sample provides basic use cases.
  • initializr-version-resolver provides the version parsing capability.
  • initializr-web provides a web portal to third-party clients.

Complete Basic Configuration

After introducing Spring Initializr, we need to complete the basic configuration.

  • Supported languages: Java, Groovy, and Kotlin
  • Supported versions: 1.8, 11, and 13
  • Supported packaging methods: JAR and WAR

Add the preceding information to the application.yml file as follows:

- name: Jar
id: jar
default: true
- name: War
id: war
default: false
- id: 13
default: false
- id: 11
default: false
- id: 1.8
name: 8
default: true
- name: Java
id: java
default: true
- name: Kotlin
id: kotlin
default: false
- name: Groovy
id: groovy
default: false

“name” is optional and “id” is required.

To assign a default value to each configuration item, set “default” to “true”. In addition to the basic configuration items, define the supported project types.

- name: Maven Project
id: maven-project
description: Generate a Maven based project archive.
build: maven
format: project
default: true
action: /
- name: Maven POM
id: maven-build
description: Generate a Maven pom.xml.
build: maven
format: build
default: false
action: /pom.xml
- name: Gradle Project
id: gradle-project
description: Generate a Gradle based project archive.
build: gradle
format: project
default: false
action: /
- name: Gradle Config
id: gradle-build
description: Generate a Gradle build file.
build: gradle
format: build
default: false
action: /build.gradle

By default, Spring Initializr supports four project types:

  • /pom.xml creates a Maven configuration file named pom.xml.
  • /build.gradle creates the Gradle configuration file.
  • / creates a project file compressed in ZIP format.
  • /starter.tgz creates a project file compressed as a TGZ file.

Use tags to define different compilation methods (builds) and packaging formats.

Configure Basic Dependencies

After completing the basic configuration, let’s configure optional dependent components.

For dependency configuration, the key is dependency. The same configuration exists in the initializr part of the application.yml file. Here is a simple example.

- name: Web
- name: Web
id: web
description: Full-stack web development with Tomcat and Spring MVC
- name: Developer Tools
- 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.

Define groups in the dependencies part. Define groups for easy display and quick search. To set a group, we only require the “name” attribute, and the “id” attribute is not required. The “content” attribute specifies the content of a group or the definitions of components in this group. It’s possible to define multiple groups in the form of a list. Also, set common configurations for the components in each group.

Each dependency includes the following basic information:

  • id: the unique identifier of a component.
  • groupId & artifactId: the coordinates of the component.
  • Name: the name displayed.
  • Description: the descriptive information displayed.
  • Version: the version of the component.

If groupId & artifactId is set, the created project uses the configured coordinates to locate the component. If groupId & artifactId is not set, Spring Initializr determines that the component is a standard Spring Boot component and automatically adds spring-boot-starter-{id} as the created dependent coordinates.

If “version” is directly set for a component, Spring Initializr uses the set value as the component-dependent version. However, in many cases, the component version is affected by the Spring Boot version. Hence, there is a need to define and manage versions in a special way.

Configure Dependent Version Management

First, let’s take a look at the version naming rules. A version includes information such as major version, minor version, revised version, and version qualifier.

The version range has upper and lower bounds, which are expressed by brackets [] or parentheses (). Brackets represent a closed interval between the upper and lower bounds, and parentheses represent an open interval between the upper and lower bounds.

For example, “[1.1.6.RELEASE,1.3.0.M1)” specifies all versions from 1.1.6.RELEASE to 1.3.0.M1, including 1.1.6.RELEASE but not 1.3.0.M1.

The version range can also be set to a single version, such as 1.2.0.RELEASE. In this case, the version range covers the set version and all later versions.

To use the concept of “the latest release”, enter the letter x to specify a version.

For example, 1.4.x.BUILD-SNAPSHOT specifies the latest snapshot version of 1.4.x.

To specify all versions from 1.1.0.RELEASE to 1.3.x, enter [1.1.0.RELEASE,1.3.x.RELEASE].

Version qualifiers are sorted in ascending order:

  • M: milestone version
  • RC: candidate version for release
  • RELEASE: released version
  • BUILD-SNAPSHOT: snapshot version built for development

BUILD-SNAPSHOT takes precedence over other version qualifiers. For example, to apply the latest Spring Boot version to a component, enter 1.5.x.BUILD-SNAPSHOT, assuming 1.5 is the latest Spring Boot version.

The version range applies to the Spring Boot version, not the component version.

As mentioned earlier, define a component version through the “version” attribute. If the component version is associated with the Spring Boot version, set the dependent version range through compatibilityRange.

compatibilityRange is defined in two ways:

  • Directly Define compatibilityRange in the Component or BOM

Using this method, the component only supports Spring Boot versions within a certain range. See the following configuration:

- name: Stuff
- name: Foo
id: foo
compatibilityRange: 1.2.0.M1
- name: Bar
id: bar
compatibilityRange: "[1.5.0.RC1,2.0.0.M1)"

Foo supports all versions later than Spring Boot 1.2.0. Bar supports versions from Spring Boot 1.5.0 to 2.0.0, excluding 2.0.0.

  • Define compatibilityRange in the “mapping” Attribute

Set a component in a different way under each Spring Boot version and reset all or some attributes of the component. The following example specifically defines artifactId.

- name: Stuff
- name: Foo
id: foo
artifactId: foo-spring-boot-starter
compatibilityRange: 1.3.0.RELEASE
- compatibilityRange: "[1.3.0.RELEASE,1.3.x.RELEASE]"
artifactId: foo-starter
- compatibilityRange: "1.4.0.RELEASE"

In this example, artifactId is set to foo-starter for Foo’s coordinates in Spring Boot 1.3. In Spring Boot 1.4.0.RELEASE and later, artifactId is still set to foo-spring-boot-starter.

Version Management Through BOM

No need to set the component version while using BOM to manage component versions

To use BOM, define BOM as follows:

groupId: org.acme
artifactId: my-api-dependencies
version: 1.0.0.RELEASE
repositories: my-api-repo-1

Note: Define BOM under initializr.env.boms.

The attributes of BOM are basically the same as those of dependent components, including the coordinates and version. BOM supports version range management.

After defining BOM, reference BOM in components as follows:

- name: Other
- name: My API
id : my-api
groupId: org.acme
artifactId: my-api
bom: my-api-bom

When the my-api is selected, Spring Initializr automatically adds the BOM dependency my-api-dependencies to the created project.

2) Advanced Customization

If was started before, "Fetching boot metadata from" is logged. We recommend using Spring Initializr with caching to avoid frequent checking of the Spring Boot version.

First, introduce the cache framework:


Add the @EnableCaching annotation to the SpringBootApplication class:

Image for post
Image for post

To define a custom cache, adjust the following cache settings:

Image for post
Image for post

Add demo code: Different components have different functions, so add demo code to the project if necessary.

Add independent configuration (spring.factories) to different components: To add configuration items, add an extension entry specific to the sample code of different components.


Add the ConditionalOnRequestedDependency annotation to SpringCloudProjectGenerationConfiguration to differentiate components.

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;
public OSSDemoCodeContributor ossContributor() {
return new OSSDemoCodeContributor(description, templateRenderer);

The preceding code creates an OSSDemoCodeContributor used to generate the demo code of the selected sca-oss component.

Generate the demo code: OSSDemoCodeContributor is a ProjectContributor that is created and called in the project file space. Add the required metadata (such as ProjectDescription) to generate the demo code when OSSDemoCodeContributor is instantiated.

It is easy to generate code by using the mstache template engine provided by Spring Initializr.

Put the demo code in the resources folder in the form of a template.

Image for post
Image for post

Parse the template files by using the template engine and copy the template files to the project directory.

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.write(filePath, code.getBytes("UTF-8"));

In addition to the template code, write the template configuration to the file.

Generate code to create a template, parse the template, and append files. The specific code is not provided here.

How Spring Initializr Works

The following sections describe two phases of implementing Spring Initializr: the startup phase and the creation phase.

  • The startup phase includes operations such as application startup, configuration loading, and extended information initialization.
  • The creation phase covers the complete process of project creation, from when a request is received to when content is returned.

1) Startup Phase

The extension system of Spring Initializr uses many of Spring’s SPIs, with the following 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

One spring.factories is located in, and the other four spring.factories are located in the Spring Initializr project. For more information about spring.factories, see the "References" section.

The definitions of spring.factories only indicate the extensions of each SPI. The phases of creating and implementing a project vary depending on different SPIs.

In the application startup phase, only the io.spring.initializr.web.autoconfigure.InitializrAutoConfiguration SPI is loaded (actuator is not considered for the moment).

public class InitializrAutoConfiguration {
public ProjectDirectoryFactory projectDirectoryFactory()
public IndentingWriterFactory indentingWriterFactory()
public MustacheTemplateRenderer templateRenderer(Environment environment, ObjectProvider<CacheManager> cacheManager)
public InitializrMetadataUpdateStrategy initializrMetadataUpdateStrategy(RestTemplateBuilder restTemplateBuilder,
ObjectMapper objectMapper)
public InitializrMetadataProvider initializrMetadataProvider(InitializrProperties properties,
InitializrMetadataUpdateStrategy initializrMetadataUpdateStrategy)
public DependencyMetadataProvider dependencyMetadataProvider()
static class InitializrWebConfiguration {
InitializrWebConfig initializrWebConfig()
ProjectGenerationController<ProjectRequest> projectGenerationController(
InitializrMetadataProvider metadataProvider, ApplicationContext applicationContext)
ProjectMetadataController projectMetadataController(InitializrMetadataProvider metadataProvider,
DependencyMetadataProvider dependencyMetadataProvider)
CommandLineMetadataController commandLineMetadataController(InitializrMetadataProvider metadataProvider,
TemplateRenderer templateRenderer)
SpringCliDistributionController cliDistributionController(InitializrMetadataProvider metadataProvider)

The following steps will execute:

  • Initialize the metadata provider.
  • Create a template engine.
  • Create a directory and indent factory.
  • Initialize the web configuration.
  • Create a web portal for Spring MVC.
  • Create various types of ProjectGenerationController.

The key step is metadata loading. The Spring environment configuration is written to InitializrProperties by using the EnableConfigurationProperties annotation.

Image for post
Image for post

The application.yml file contains the following configuration information, which stores the actual project dependency metadata:

Image for post
Image for post

The actions in the startup phase are simple, so it only takes a few seconds to start

More logic is implemented in the project creation phase.

2) Creation Phase

The following figure shows the process flowchart.

Image for post
Image for post
  • The blue classes are created and filled with data during the application startup phase. The class lifecycle is the same as the application lifecycle.
  • The yellow classes are created during the project build process. The class lifecycle lasts until the end of the project creation process.

The sequence diagram shows a typical creation behavior, in which ProjectGenerationController receives a project creation request from the web, the request is converted by ProjectGenerationInvoker, and the request enters ProjectGenerator, which implements the core build process.

Main Process

Image for post
Image for post

In line 106, a new ProjectGenerationContext is built through contextFactory.

Let’s take a look at the context inheritance. It comes from AnnotationConfigApplicationContext provided by Spring.

Based on the refresh() method in line 110, see the refresh process of ApplicationContext in Spring.

Image for post
Image for post

In line 107, the resolve method injects a provider named ProjectDescription into the context. The code is as follows:

Image for post
Image for post

The provider is registered, so the logic is implemented when the context executes the refresh action.

ProjectDescriptionCustomizer is an extension of ProjectDescription and used to adjust the input ProjectDescription. Changes are made to mandatory dependencies, such as the language version.

In line 108, a configuration is registered to the context.

The following code shows the configuration content.

Image for post
Image for post

The configuration includes ProjectGenerationConfiguration, an SPI implemented in spring.factories many times. For more information, see the “References” section.

In the extension system of Spring Initializr, an instance is created only at this point.

In line 109 of ProjectGenerator, the accept action is executed on the consumer by calling the following code:

Image for post
Image for post

setParent is used to set the primary context of the application as the parent node of this ProjectGenerationContext.

A metadata object is registered to this ProjectGenerationContext.

In line 112 of ProjectGenerator, the generate method of projectAssetGenerator is called. The code is as follows:

Image for post
Image for post

The preceding code builds a project by using multiple ProjectContributors.

This completes the main process.

In the main process, no files are written, and only the root folder is created. The main process only defines the mechanisms and processes of loading data and extensions, with all implementations as parts of extensions.

Extension Process

Image for post
Image for post

According to the method signature, the only input parameter specifies the project’s root path to where project files are saved. This extension point is flexible and supports the writing of any code and configuration files.

Related dependencies are obtained by ProjectGenerationContext, and files are created by custom logic.

Spring Initializr and provide the following ProjectContributors:

Image for post
Image for post

The main ProjectContributors are as follows:

  • MavenBuildProjectContributor: writes the pom.xml file of a Maven project.
  • WebFoldersContributor: creates a resource folder for a Web project.
  • ApplicationPropertiesContributor: writes the file.
  • MainSourceCodeProjectContributor: writes the file of the application entry class.
  • HelpDocumentProjectContributor: writes the file of help documentation.

Unlike ProjectContributor, xxxxxCustomizer is not a unified interface. It is a concept that specifies a naming convention. Each Customizer has a specific name and corresponds to trigger logic and responsibility boundaries.

Spring Initializr provides the following Customizers:

  • MainApplicationTypeCustomizer: customizes the MainApplication class.
  • MainCompilationUnitCustomizer: customizes the MainApplication compilation unit.
  • MainSourceCodeCustomizer: customizes the MainApplication source code.
  • BuildCustomizer: customizes the configuration of the project build tool.
  • GitIgnoreCustomizer: customizes the .gitignore file of a project.
  • HelpDocumentCustomizer: customizes the help document of a project.
  • InitializrMetadataCustomizer: customizes the metadata configured for project initialization. This Customizer is special and called when a metadata configuration is loaded for the first time.
  • ProjectDescriptionCustomizer: customizes ProjectDescription. The project description can be modified before project files are created.
  • ServletInitializerCustomizer: customizes the class-related configuration of web applications.
  • TestApplicationTypeCustomizer: customizes the test application class.
  • TestSourceCodeCustomizer: customizes the source code of the test application class.


1) Links

2) Details of spring.factories










Original Source:

Follow me to keep abreast with the latest technology news, industry insights, and developer trends.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store