mirror of
https://github.com/spring-projects/spring-boot.git
synced 2024-09-03 04:26:12 +08:00
Improve how to configure configuration keys of a custom starter
Closes gh-17573
This commit is contained in:
parent
300f07b2a8
commit
30fe10613d
@ -8403,16 +8403,55 @@ assume that you are creating a starter for "acme" and that you name the auto-con
|
||||
module `acme-spring-boot-autoconfigure` and the starter `acme-spring-boot-starter`. If
|
||||
you only have one module that combines the two, name it `acme-spring-boot-starter`.
|
||||
|
||||
Also, if your starter provides configuration keys, use a unique namespace for them. In
|
||||
|
||||
|
||||
[[boot-features-custom-starter-configuration-keys]]
|
||||
==== Configuration keys
|
||||
If your starter provides configuration keys, use a unique namespace for them. In
|
||||
particular, do not include your keys in the namespaces that Spring Boot uses (such as
|
||||
`server`, `management`, `spring`, and so on). If you use the same namespace, we may modify
|
||||
these namespaces in the future in ways that break your modules.
|
||||
these namespaces in the future in ways that break your modules. As a rule of thumb,
|
||||
prefix all your keys with a namespace that you own (e.g. `acme`).
|
||||
|
||||
Make sure that configuration keys are documented by adding field javadoc for each
|
||||
property, as shown in the following example:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
@ConfigurationProperties("acme")
|
||||
public class AcmeProperties {
|
||||
|
||||
/**
|
||||
* Whether to check the location of acme resources.
|
||||
*/
|
||||
private boolean checkLocation = true;
|
||||
|
||||
/**
|
||||
* Timeout for establishing a connection to the acme server.
|
||||
*/
|
||||
private Duration loginTimeout = Duration.ofSeconds(3);
|
||||
|
||||
// getters & setters
|
||||
|
||||
}
|
||||
----
|
||||
|
||||
Here are some rules we follow internally to make sure descriptions are consistent:
|
||||
|
||||
* Do not start the description by "The" or "A".
|
||||
* For `boolean` types, start the description with "Whether" or "Enable".
|
||||
* For collection-based types, start the description with "Comma-separated list"
|
||||
* Use `java.time.Duration` rather than `long` and describe the default unit if it differs
|
||||
from milliseconds, e.g. "If a duration suffix is not specified, seconds will be used".
|
||||
* Do not provide the default value in the description unless it has to be determined at
|
||||
runtime.
|
||||
|
||||
Make sure to
|
||||
<<appendix-configuration-metadata#configuration-metadata-annotation-processor,trigger
|
||||
meta-data generation>> so that IDE assistance is available for your keys as well. You may
|
||||
want to review the generated meta-data (`META-INF/spring-configuration-metadata.json`) to
|
||||
make sure your keys are properly documented.
|
||||
want to review the generated metadata (`META-INF/spring-configuration-metadata.json`) to
|
||||
make sure your keys are properly documented. Using your own starter in a compatible IDE is
|
||||
also a good idea to validate that quality of the metadata.
|
||||
|
||||
|
||||
|
||||
|
Loading…
Reference in New Issue
Block a user