From 972d40ee4cac1ab7bcb066dbbafef9665413a1a1 Mon Sep 17 00:00:00 2001 From: Yanming Zhou Date: Mon, 20 Jan 2025 15:39:39 +0800 Subject: [PATCH] Revise documents Signed-off-by: Yanming Zhou --- .../application-context-services.adoc | 20 +++++++++---------- .../common-abstractions.adoc | 3 ++- .../spring-cloud-commons/loadbalancer.adoc | 2 +- 3 files changed, 13 insertions(+), 12 deletions(-) diff --git a/docs/modules/ROOT/pages/spring-cloud-commons/application-context-services.adoc b/docs/modules/ROOT/pages/spring-cloud-commons/application-context-services.adoc index 151cff399..8f2bbef20 100644 --- a/docs/modules/ROOT/pages/spring-cloud-commons/application-context-services.adoc +++ b/docs/modules/ROOT/pages/spring-cloud-commons/application-context-services.adoc @@ -41,12 +41,12 @@ If you build an application context from `SpringApplication` or `SpringApplicati It is a feature of Spring that child contexts inherit property sources and profiles from their parent, so the "`main`" application context contains additional property sources, compared to building the same context without Spring Cloud Config. The additional property sources are: -* "`bootstrap`": If any `PropertySourceLocators` are found in the bootstrap context and if they have non-empty properties, an optional `CompositePropertySource` appears with high priority. +* "`bootstrap`": If any `PropertySourceLocator`s are found in the bootstrap context and if they have non-empty properties, an optional `CompositePropertySource` appears with high priority. An example would be properties from the Spring Cloud Config Server. See "`xref:spring-cloud-commons/application-context-services.adoc#customizing-bootstrap-property-sources[Customizing the Bootstrap Property Sources]`" for how to customize the contents of this property source. -NOTE: Prior to Spring Cloud 2022.0.3 `PropertySourceLocators` (including the ones for Spring Cloud Config) were run during -the main application context and not in the Bootstrap context. You can force `PropertySourceLocators` to be run during the +NOTE: Prior to Spring Cloud 2022.0.3 `PropertySourceLocator`s (including the ones for Spring Cloud Config) were run during +the main application context and not in the Bootstrap context. You can force `PropertySourceLocator`s to be run during the Bootstrap context by setting `spring.cloud.config.initialize-on-context-refresh=true` in `bootstrap.[properties | yaml]`. * "`applicationConfig: [classpath:bootstrap.yml]`" (and related files if Spring profiles are active): If you have a `bootstrap.yml` (or `.properties`), those properties are used to configure the bootstrap context. @@ -96,7 +96,7 @@ Once that flag is set, two finer-grained settings control the location of the re The bootstrap context can be set to do anything you like by adding entries to `/META-INF/spring.factories` under a key named `org.springframework.cloud.bootstrap.BootstrapConfiguration`. This holds a comma-separated list of Spring `@Configuration` classes that are used to create the context. Any beans that you want to be available to the main application context for autowiring can be created here. -There is a special contract for `@Beans` of type `ApplicationContextInitializer`. +There is a special contract for `@Bean`s of type `ApplicationContextInitializer`. If you want to control the startup sequence, you can mark classes with the `@Order` annotation (the default order is `last`). WARNING: When adding custom `BootstrapConfiguration`, be careful that the classes you add are not `@ComponentScanned` by mistake into your "`main`" application context, where they might not be needed. @@ -104,7 +104,7 @@ Use a separate package name for boot configuration classes and make sure that na The bootstrap process ends by injecting initializers into the main `SpringApplication` instance (which is the normal Spring Boot startup sequence, whether it runs as a standalone application or is deployed in an application server). First, a bootstrap context is created from the classes found in `spring.factories`. -Then, all `@Beans` of type `ApplicationContextInitializer` are added to the main `SpringApplication` before it is started. +Then, all `@Bean`s of type `ApplicationContextInitializer` are added to the main `SpringApplication` before it is started. [[customizing-bootstrap-property-sources]] == Customizing the Bootstrap Property Sources @@ -138,10 +138,10 @@ If you create a jar with this class in it and then add a `META-INF/spring.factor org.springframework.cloud.bootstrap.BootstrapConfiguration=sample.custom.CustomPropertySourceLocator ---- -As of Spring Cloud 2022.0.3, Spring Cloud will now call `PropertySourceLocators` twice. The first fetch +As of Spring Cloud 2022.0.3, Spring Cloud will now call `PropertySourceLocator`s twice. The first fetch will retrieve any property sources without any profiles. These property sources will have the opportunity to -activate profiles using `spring.profiles.active`. After the main application context starts `PropertySourceLocators` -will be called a second time, this time with any active profiles allowing `PropertySourceLocators` to locate +activate profiles using `spring.profiles.active`. After the main application context starts `PropertySourceLocator`s +will be called a second time, this time with any active profiles allowing `PropertySourceLocator`s to locate any additional `PropertySources` with profiles. [[logging-configuration]] @@ -155,7 +155,7 @@ For example, using `custom.loggin.logpath` is not recognized by Spring Cloud whe [[environment-changes]] == Environment Changes -The application listens for an `EnvironmentChangeEvent` and reacts to the change in a couple of standard ways (additional `ApplicationListeners` can be added as `@Beans` in the normal way). +The application listens for an `EnvironmentChangeEvent` and reacts to the change in a couple of standard ways (additional `ApplicationListener`s can be added as `@Bean`s in the normal way). When an `EnvironmentChangeEvent` is observed, it has a list of key values that have changed, and the application uses those to: * Re-bind any `@ConfigurationProperties` beans in the context. @@ -209,7 +209,7 @@ management: ---- NOTE: `@RefreshScope` works (technically) on a `@Configuration` class, but it might lead to surprising behavior. -For example, it does not mean that all the `@Beans` defined in that class are themselves in `@RefreshScope`. +For example, it does not mean that all the `@Bean`s defined in that class are themselves in `@RefreshScope`. Specifically, anything that depends on those beans cannot rely on them being updated when a refresh is initiated, unless it is itself in `@RefreshScope`. In that case, it is rebuilt on a refresh and its dependencies are re-injected. At that point, they are re-initialized from the refreshed `@Configuration`). diff --git a/docs/modules/ROOT/pages/spring-cloud-commons/common-abstractions.adoc b/docs/modules/ROOT/pages/spring-cloud-commons/common-abstractions.adoc index 6e4112d6c..65f612d2e 100644 --- a/docs/modules/ROOT/pages/spring-cloud-commons/common-abstractions.adoc +++ b/docs/modules/ROOT/pages/spring-cloud-commons/common-abstractions.adoc @@ -110,6 +110,7 @@ are using. By default, the `ServiceRegistry` implementation auto-registers the running service. To disable that behavior, you can set: + * `@EnableDiscoveryClient(autoRegister=false)` to permanently disable auto-registration. * `spring.cloud.service-registry.auto-registration.enabled=false` to disable the behavior through configuration. @@ -537,7 +538,7 @@ For the reactive implementation, you can additionally set: For the reactive implementation, you can also implement your own `LoadBalancerRetryPolicy` to have more detailed control over the load-balanced call retries. -For both implementations, you can also set the exceptions that trigger the replies by adding a list of values under the `spring.cloud.loadbalancer.[serviceId].retry.retryable-exceptions` property. If you do, we make sure to add `RetryableStatusCodeExceptions` to the list of exceptions provided by you, so that we also retry on retryable status codes. If you do not specify any exceptions via properties, the exceptions we use by default are `IOException`, `TimeoutException` and `RetryableStatusCodeException`. You can also enable retrying on all exceptions by setting `spring.cloud.loadbalancer.[serviceId].retry.retry-on-all-exceptions` to `true`. +For both implementations, you can also set the exceptions that trigger the replies by adding a list of values under the `spring.cloud.loadbalancer.[serviceId].retry.retryable-exceptions` property. If you do, we make sure to add `RetryableStatusCodeException`s to the list of exceptions provided by you, so that we also retry on retryable status codes. If you do not specify any exceptions via properties, the exceptions we use by default are `IOException`, `TimeoutException` and `RetryableStatusCodeException`. You can also enable retrying on all exceptions by setting `spring.cloud.loadbalancer.[serviceId].retry.retry-on-all-exceptions` to `true`. WARNING: If you use the blocking implementation with Spring Retries, if you want to keep the behaviour from previous releases, set `spring.cloud.loadbalancer.[serviceId].retry.retry-on-all-exceptions` to `true` as that used to be the default mode for the blocking implementation. diff --git a/docs/modules/ROOT/pages/spring-cloud-commons/loadbalancer.adoc b/docs/modules/ROOT/pages/spring-cloud-commons/loadbalancer.adoc index 6468a80f4..870468704 100644 --- a/docs/modules/ROOT/pages/spring-cloud-commons/loadbalancer.adoc +++ b/docs/modules/ROOT/pages/spring-cloud-commons/loadbalancer.adoc @@ -516,7 +516,7 @@ NOTE: For some implementations, such as `BlockingLoadBalancerClient`, request an NOTE: The meters are registered in the registry when at least one record is added for a given meter. -TIP: You can further configure the behavior of those metrics (for example, add https://micrometer.io/docs/concepts#_histograms_and_percentiles[publishing percentiles and histograms]) by https://docs.spring.io/spring-boot/docs/current/reference/html/production-ready-features.html#production-ready-metrics-per-meter-properties[adding `MeterFilters`]. +TIP: You can further configure the behavior of those metrics (for example, add https://micrometer.io/docs/concepts#_histograms_and_percentiles[publishing percentiles and histograms]) by https://docs.spring.io/spring-boot/docs/current/reference/html/production-ready-features.html#production-ready-metrics-per-meter-properties[adding `MeterFilter`s]. [[configuring-individual-loadbalancerclients]] == Configuring Individual LoadBalancerClients