root
/
spring-boot
mirror of https://github.com/spring-projects/spring-boot.git
1
0
Fork 0
Code Issues Actions 12 Packages Projects Releases Wiki Activity

Polish auto-configuration documentation 

Remove references to outdated information, emphasize use of the
`@AutoConfiguration` annotation and attributes, and edit for clarity.

Closes gh-32174
This commit is contained in:
Scott Frederick 2022-09-01 15:35:59 -05:00
parent ed77567fce
commit 7763a5df7d
1 changed files with 9 additions and 21 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
spring-boot-project/spring-boot-docs/src/docs/asciidoc/features/developing-auto-configuration.adoc
View File

@ -6,19 +6,17 @@ Auto-configuration classes can be bundled in external jars and still be picked-u
Auto-configuration can be associated to a "`starter`" that provides the auto-configuration code as well as the typical libraries that you would use with it.
We first cover what you need to know to build your own auto-configuration and then we move on to the <<features#features.developing-auto-configuration.custom-starter,typical steps required to create a custom starter>>.
TIP: A https://github.com/snicoll-demos/spring-boot-master-auto-configuration[demo project] is available to showcase how you can create a starter step-by-step.
[[features.developing-auto-configuration.understanding-auto-configured-beans]]
=== Understanding Auto-configured Beans
Under the hood, auto-configuration is implemented with the `@AutoConfiguration` annotation.
Classes that implement auto-configuration are annotated with `@AutoConfiguration`.
This annotation itself is meta-annotated with `@Configuration`, making auto-configurations standard `@Configuration` classes.
Additional `@Conditional` annotations are used to constrain when the auto-configuration should apply.
Usually, auto-configuration classes use `@ConditionalOnClass` and `@ConditionalOnMissingBean` annotations.
This ensures that auto-configuration applies only when relevant classes are found and when you have not declared your own `@Configuration`.
You can browse the source code of {spring-boot-autoconfigure-module-code}[`spring-boot-autoconfigure`] to see the `@Configuration` classes that Spring provides (see the {spring-boot-code}/spring-boot-project/spring-boot-autoconfigure/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports[`META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports`] file).
You can browse the source code of {spring-boot-autoconfigure-module-code}[`spring-boot-autoconfigure`] to see the `@AutoConfiguration` classes that Spring provides (see the {spring-boot-code}/spring-boot-project/spring-boot-autoconfigure/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports[`META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports`] file).
@ -26,7 +24,7 @@ You can browse the source code of {spring-boot-autoconfigure-module-code}[`sprin
=== Locating Auto-configuration Candidates
Spring Boot checks for the presence of a `META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports` file within your published jar.
The file should list your configuration classes, as shown in the following example:
The file should list your configuration classes, with one class name per line, as shown in the following example:
[indent=0]
----
@ -34,18 +32,16 @@ The file should list your configuration classes, as shown in the following examp
com.mycorp.libx.autoconfigure.LibXWebAutoConfiguration
----
TIP: You can use comments via `#` in this file.
TIP: You can add comments to the imports file using the `#` character.
NOTE: Auto-configurations must be loaded that way _only_.
NOTE: Auto-configurations must be loaded _only_ by being named in the imports file.
Make sure that they are defined in a specific package space and that they are never the target of component scanning.
Furthermore, auto-configuration classes should not enable component scanning to find additional components.
Specific ``@Import``s should be used instead.
You can use the {spring-boot-autoconfigure-module-code}/AutoConfigureAfter.java[`@AutoConfigureAfter`] or {spring-boot-autoconfigure-module-code}/AutoConfigureBefore.java[`@AutoConfigureBefore`] annotations if your configuration needs to be applied in a specific order.
If your configuration needs to be applied in a specific order, you can use the `before`, `beforeName`, `after` and `afterName` attributes on the {spring-boot-autoconfigure-module-code}/AutoConfiguration.java[`@AutoConfiguration`] annotation or the dedicated {spring-boot-autoconfigure-module-code}/AutoConfigureBefore.java[`@AutoConfigureBefore`] and {spring-boot-autoconfigure-module-code}/AutoConfigureAfter.java[`@AutoConfigureAfter`] annotations.
For example, if you provide web-specific configuration, your class may need to be applied after `WebMvcAutoConfiguration`.
TIP: If you are using the {spring-boot-autoconfigure-module-code}/AutoConfiguration.java[`@AutoConfiguration`] annotation, you can use the `before`, `beforeName`, `after` and `afterName` attribute aliases instead of the dedicated annotations.
If you want to order certain auto-configurations that should not have any direct knowledge of each other, you can also use `@AutoConfigureOrder`.
That annotation has the same semantic as the regular `@Order` annotation but provides a dedicated order for auto-configuration classes.
@ -264,7 +260,8 @@ If you do it that way, the library is not provided and, by default, Spring Boot
Spring Boot uses an annotation processor to collect the conditions on auto-configurations in a metadata file (`META-INF/spring-autoconfigure-metadata.properties`).
If that file is present, it is used to eagerly filter auto-configurations that do not match, which will improve startup time.
It is recommended to add the following dependency in a module that contains auto-configurations:
When building with Maven, it is recommended to add the following dependency in a module that contains auto-configurations:
[source,xml,indent=0,subs="verbatim"]
----
@ -299,16 +296,7 @@ If you have defined auto-configurations directly in your application, make sure
</project>
----
With Gradle 4.5 and earlier, the dependency should be declared in the `compileOnly` configuration, as shown in the following example:
[source,gradle,indent=0,subs="verbatim"]
----
dependencies {
compileOnly "org.springframework.boot:spring-boot-autoconfigure-processor"
}
----
With Gradle 4.6 and later, the dependency should be declared in the `annotationProcessor` configuration, as shown in the following example:
With Gradle, the dependency should be declared in the `annotationProcessor` configuration, as shown in the following example:
[source,gradle,indent=0,subs="verbatim"]
----