Spring Cloud Alibaba Reference Documentation

Service discovery is one of the key components in the microservices architecture. In such a architecture, configuring a service list for every client manually could be a daunting task, and makes dynamic scaling extremely difficult. Nacos Discovery helps you to register your service to the Nacos server automatically, and the Nacos server keeps track of the services and refreshes the service list dynamically. In addition, Nacos Discovery registers some of the metadata of the service instance, such as host, port, health check URL, homepage to Nacos. For details about how to download and start Nacos, refer to the Nacos Website.

please use the starter with the group ID as com.alibaba.cloud and the artifact ID as spring-cloud-starter-alibaba-nacos-discovery.

Nacos Discovery integrate with the Netflix Ribbon, RestTemplate or OpenFeign can be used for service-to-service calls.

Nacos Discovery provides an Endpoint internally with a corresponding endpoint id of nacosdiscovery.

Endpoint exposed json contains two properties:

The followings shows how a service instance accesses the Endpoint:

The following shows the other configurations of the starter of Nacos Discovery:

please use the starter with the group ID as com.alibaba.cloud and the artifact ID as spring-cloud-starter-alibaba-nacos-config.

Nacos Config uses DataId and GROUP to determine a configuration.

The following figure shows that the DataId uses myDataid, GROUP uses DEFAULT_GROUP, and configures a configuration item of the format Properties:

Nacos Config supports yaml format as well. You only need to complete the following 2 steps.

1、In the bootstrap.properties file, add the following line to claim that the format of DataId is yaml. As follows:

2、Add a configuration with the DataId in yaml format on the Nacos console, as shown below:

After completing the preivous two steps, restart the testing program and you will see the following result.

Nacos Config also supports dynamic configuration updates. The code for starting Spring Boot application testing is as follows:

When user.name is changed, the latest value can be retrieved from the application, as shown below:

When configurations are loaded by Nacos Config, basic configurations with DataId of ${spring.application.name}. ${file-extension:properties} , and DataId of ${spring.application.name}-${profile}. ${file-extension:properties} are also loaded. If you need to use different configurations from different environments, you can use the ${spring.profiles.active} configuration provided by Spring.

Add a basic configuration in Nacos, with a DataId of nacos-config-develop.yaml, as shown below:

Run the following Spring Boot application testing code:

After started, you can see the output as follows in the console:

To switch to the production environment, you only need to change the parameter of ${spring.profiles.active}. As show below:

At the same time, add the basic configuration with the DataId in the Nacos of your production environment. For example, you can add the configuration with the DataId of nacos-config-product.yaml in Nacos of your production environment:

Start the testing program and you will see the following result:

For details about namespaces in Nacos, refer to Nacos Concepts

The “Public” namespace of Nacos is used if no namespace is specified in ${spring.cloud.nacos.config.namespace}. You can also specify a custom namespace in the following way：

DEFAULT_GROUP is used by default when no {spring.cloud.nacos.config.group} configuration is defined. If you need to define your own group, you can define it in the following property:

As of Spring Cloud Alibaba Nacos Config, data id can be self-defined. For detailed design of this part, refer to Github issue. The following is a complete sample:

We can see that:

The configuration of custom Data Id allows the sharing of configurations among multiple applications, and also enables support of multiple configurations for one application.

To share the data id among multiple applications in a clearer manner, you can also use the following method:

We can see that:

Nacos Config provides an Endpoint internally with a corresponding endpoint id of nacos-config.

Endpoint exposed json contains three properties:

The followings shows how a service instance accesses the Endpoint:

set spring.cloud.nacos.config.enabled = false to disable Spring Cloud Nacos Config AutoConfiguration.

The following shows the other configurations of the starter of Nacos Config:

As microservices become popular, the stability of service calls is becoming increasingly important. Sentinel takes "flow" as the breakthrough point, and works on multiple fields including flow control, circuit breaking and load protection to protect service reliability.

Sentinel has the following features:

If you want to use Sentinel in your project, please use the starter with the group ID as com.alibaba.cloud and the artifact ID as spring-cloud-starter-alibaba-sentinel.

The following is a simple example of how to use Sentinel:

The @SentinelResource annotation is used to identify if a resource is rate limited or degraded. In the above sample, the 'hello' attribute of the annotation refers to the resource name.

@SentinelResource also provides attributes such as blockHandler, blockHandlerClass, and fallback to identify rate limiting or degradation operations. For more details, refer to Sentinel Annotation Support.

The above examples are all used in the WebServlet environment. Sentinel currently supports WebFlux and needs to cooperate with the spring-boot-starter-webflux dependency to trigger the WebFlux-related automation configuration in sentinel starter.

Sentinel is compatible with the OpenFeign component. To use it, in addition to introducing the sentinel-starter dependency, complete the following 2 steps:

This is a simple usage of FeignClient:

The corresponding resource name of the echo method in the EchoService interface is GET:http://service-provider/echo/{str}.

Spring Cloud Alibaba Sentinel supports the protection of RestTemplate service calls using Sentinel. To do this, you need to add the @SentinelRestTemplate annotation when constructing the RestTemplate bean.

The attribute of the @SentinelRestTemplate annotation support flow control(blockHandler, blockHandlerClass) and circuit breaking(fallback, fallbackClass).

==

The blockHandler or fallback is the static method of blockHandlerClass or fallbackClass.

The parameter and return value of method in @SentinelRestTemplate is same as org.springframework.http.client.ClientHttpRequestInterceptor#interceptor, but it has one more parameter BlockException to catch the exception by Sentinel.

The method signature of handleException in ExceptionUtil above should be like this:

The attribute of the @SentinelRestTemplate annotation is optional.

It will return RestTemplate request block by sentinel when you using RestTemplate blocked by Sentinel. You can override it by your own logic. We provide SentinelClientHttpResponse to handle the response.

Sentinel RestTemplate provides two granularities for resource rate limiting:

SentinelProperties provide datasource attribute to configure datasource.

For example, 4 data sources are configures：

This method follows the configuration of Spring Cloud Stream Binder. TreeMap is used for storage internally, and comparator is String.CASE_INSENSITIVE_ORDER.

Every data source has 3 common configuration items: data-type, converter-class and rule-type.

data-type refers to Converter. Spring Cloud Alibaba Sentinel provides two embedded values by default: json and xml (the default is json if not specified). If you do not want to use the embedded json or xml Converter, you can also fill in custom to indicate that you will define your own Converter, and then configure the converter-class. You need to specify the full path of the class for this configuration.

rule-type refers to the rule type in datasource(flow，degrade，authority，system, param-flow, gw-flow, gw-api-group).

To learn more about how dynamic data sources work in Sentinel, refer to Dynamic Rule Extension.

Refer API Gateway Flow Control

If you want to use Sentinel Starter with Spring Cloud Gateway, you need to add the spring-cloud-alibaba-sentinel-gateway dependency and add the spring-cloud-starter-gateway dependency to let Spring Cloud Gateway AutoConfiguration class in the module takes effect:

Sentinel provides an Endpoint internally with a corresponding endpoint id of sentinel.

Endpoint exposed json contains multi properties:

The followings shows how a service instance accesses the Endpoint:

The following table shows that when there are corresponding bean types in ApplicationContext, some actions will be taken:

The following table shows all the configurations of Spring Cloud Alibaba Sentinel:

RocketMQ is an open-source distributed message system. It is based on highly available distributed cluster technologies and provides message publishing and subscription service with low latency and high stability. RocketMQ is widely used in a variety of industries, such as decoupling of asynchronous communication, enterprise solutions, financial settlements, telecommunication, e-commerce, logistics, marketing, social media, instant messaging, mobile applications, mobile games, videos, IoT, and Internet of Vehicles.

It has the following features:

Download Latest Binary File of RocketMQ, and decompress it.

The decompressed directory is as follows:

Send messages:

Output when the message is successfully sent: SendResult [sendStatus=SEND_OK, msgId= …​

Receive messages:

Output when the message is successfully received： ConsumeMessageThread_%d Receive New Messages: [MessageExt…​

Spring Cloud Stream is a microservice framework used to build architectures based on messages. It helps you to create production-ready single-server Spring applications based on SpringBoot, and connects with Broker using Spring Integration.

Spring Cloud Stream provides unified abstractions of message middleware configurations, and puts forward concepts such as publish-subscribe, consumer groups and partition.

There are two concepts in Spring Cloud Stream: Binder and Binding

For example, Kafka uses KafkaMessageChannelBinder, RabbitMQ uses RabbitMessageChannelBinder, while RocketMQ uses RocketMQMessageChannelBinder.

Binding serves as a bridge between message middleware and the provider and consumer of the applications. Developers only need to use the Provider or Consumer to produce or consume data, and do not need to worry about the interactions with the message middleware.

Now let’s use Spring Cloud Stream to write a simple code for sending and receiving messages:

All the message types in this code are provided by the `spring-messaging`module. It shields the lower-layer implementations of message middleware. If you would like to change the message middleware, you only need to configure the related message middleware information in the configuration file and modify the binder dependency.

The lower layer of Spring Cloud Stream also implements various code abstractions based on the previous code.

For using the Spring Cloud Alibaba RocketMQ Binder, you just need to add it to your Spring Cloud Stream application, using the following Maven coordinates:

Alternatively, you can also use the Spring Cloud Stream RocketMQ Starter:

This is the implementation architecture of Spring Cloud Stream RocketMQ Binder:

The implementation of RocketMQ Binder depend on the RocketMQ-Spring framework.

RocketMQ Spring framework is an integration of RocketMQ and Spring Boot. It provides three main features:

RocketMQMessageChannelBinder is a standard implementation of Binder, it will build RocketMQInboundChannelAdapter and RocketMQMessageHandler internally.

RocketMQMessageHandler will construct RocketMQTemplate based on the Binding configuration. RocketMQTemplate will convert the org.springframework.messaging.Message message class of spring-messaging module to the RocketMQ message class org.apache.rocketmq.common .message.Message internally, then send it out.

RocketMQInboundChannelAdapter will also construct RocketMQListenerBindingContainer based on the Binding configuration, and RocketMQListenerBindingContainer will start the RocketMQ Consumer to receive the messages.

Currently Binder supports setting the relevant key in Header to set the properties of the RocketMQ message.

For example, TAGS, DELAY, TRANSACTIONAL_ARG, KEYS, WAIT_STORE_MSG_OK, FLAG represent the labels corresponding to the RocketMQ message.

Or use StreamBridge

If you want to use ANS in your project, please use the starter with the group ID as com.alibaba.cloud and the artifact ID as spring-cloud-starter-alicloud-ans.

When Spring Cloud AliCloud ANS Starter is introduced on the client, the metadata of the service such as IP, port number and weight will be registered to the registration center automatically. The client will maintain heartbeat with the server to prove that it is capable of providing service properly.

The following is a simple illustration.

As the service will registered to the registration center, we will need to configure the address of the registration center. We also need to add the following address in application.properties.

ANS uses two types of registration centers. One is the free lightweight configuration center and the other is the registration center on cloud, which is provided through EDAS. Generally, you can use the lightweight version for application development and local testing, and use EDAS for canary deployment or production.

If you want to use ACM in your project, please use the starter with the group ID as com.alibaba.cloud and the artifact ID as spring-cloud-starter-alicloud-acm.

When Spring Cloud Alibaba Cloud ACM Starter is introduced into the client, the application will automatically get configuration information from the configuration management server when it starts, and inject the configuration into Spring Environment.

The following is a simple illustration.

As we need to obtain configuration information from the configuration server, we will need to configure the address of the server. We also need to add the following information in bootstrap.properties.

The default file extension of dataId in spring-cloud-starter-alicloud-acm is properties. In addition to properties, yaml is also supported. You can set the file extension using spring.cloud.alicloud.acm.file-extension. Just set it to yaml or `yml`for yaml format.

spring-cloud-starter-alicloud-acm supports dynamic configuration updates. RefreshEvent in Spring is published when you update configuration in the configuration center. All classes with @RefreshScope and @ConfigurationProperties annotations will be refreshed automatically.

When configuration is loaded by spring-cloud-starter-alicloud-acm, configuration with DataId {spring.application.name}. {file-extension} will be loaded first. If there is content in spring.profiles.active, the content of spring.profile, and configuration with the dataid format of{spring.application.name}-{profile}. {file-extension} will also be loaded in turn, and the latter has higher priority.

spring.profiles.active is the configuration metadata, and should also be configured in bootstrap.properties or bootstrap.yaml. For example, you can add the following content in bootstrap.properties.

Note: You can also configure the granularity through JVM parameters such as -Dspring.profiles.active=develop or --spring.profiles.active=develop, which have higher priority. Just follow the specifications of Spring Boot.

the default timeout of ACM client get config from sever is 3000 ms . If you need to define a timeout, set configuration spring.cloud.alicloud.acm.timeout,the unit is millisecond.

DEFAULT_GROUP is used by default when no {spring.cloud.alicloud.acm.group} configuration is defined. If you need to define your own group, you can use the following method:

the Actuator endpoint of ACM is /acm, config represents the ACM metadata configuration information, runtime.sources corresponds to the configuration information obtained from the ACM server and the last refresh time, runtime.refreshHistory corresponds to the dynamic refresh history.

We’ve released Spring Cloud Alibaba version 0.2.1. You will need to add dependency management POM first.

Next we need to introduce Spring Cloud Alibaba Cloud OSS Starter.

Spring Cloud Alibaba Cloud OSS integrates the Resource of the Spring framework, which allows you to use the OSS resources easily.

The following is a simple example of how to use Resource.

In addition to AccessKeys, Spring Cloud Alibaba Cloud OSS also supports STS authentication. STS is an authentication method with temporary security tokens, and is usually used for a third party to access its resources temporarily.

For a third party to access resources temporarily, it only needs to complete the following configurations.

Among which, spring.cloud.alicloud.oss.authorization-mode is the enumeration type. Fill in STS here means that STS authentication is used. For endpoint information, refer to the OSS Documentation and fill in the endpoint for your region.

Access-key, secret-key and the security-token need to be issued by the authentication side. For more information about STS, refer to STS Documentation.

In addition to basic configurations, Spring Cloud Alibaba Cloud OSS also supports many other configurations, which are also included in the application.properties file.

Here are some examples.

For more configurations, refer to the table at the bottom of OSSClient Configurations.

If you want to use SchedulerX in your project, please use the starter with the group ID as com.alibaba.cloud and the artifact ID as spring-cloud-starter-alicloud-schedulerX.

After Spring Cloud Alibaba Cloud SchedulerX Starter is introduced into the client, you only need to complete a few simple configurations and you will be able to initialize the SchedulerX service automatically.

The following is a simple example.

Add the following configurations in the application.properties file.

Before getting the group-id, please Register an Alibaba Cloud account, and then Sign up for EDAS and Sign up for SchedulerX as well.

To get the group-id, refer to the SchedulerX Documentation.

Simple job is the most commonly used job type. You only need to implement the ScxSimpleJobProcessor interface.

The following is a sample of a simple single-server job.

Go to the SchedulerX Jobs page, select the “Test” region, and click “Create Job” on the upper-right corner to create a job, as shown below.

The job above is a “Simple Single-Server Job”, and specified a Cron expression of "0 * * * * ?" . This means that the job will be executed once and once only in every minute.

For more job types, refer to SchedulerX Documentation.

The previous examples shows how to use SchedulerX in the “Test” region, which is mainly used for local testing.

At the production level, you need to complete some other configurations in addition to the group-id and namespace as mentioned above. See examples below:

The way to get the group-id is the same as described in the previous examples, and you can get the namespace by clicking “Namespaces” in the left-side navigation pane of the EDAS console.

Access-key and secret-key are the AK/SK of your Alibaba Cloud account. If you deploy you applications on EDAS, then you do not need to fill in this information. Otherwise please go to Security Information to get your AccessKeys.

Domain-name is not mandatory. You can refer to SchedulerX Documentation for details.

If you want to use SMS in your project, please use the starter with the group ID as com.alibaba.cloud and the artifact ID as spring-cloud-starter-alicloud-sms.

In order to reduce the cost of learning, the API interface of the Spring Cloud Alicloud SMS package is kept as consistent as the API and Example provided by the official website.

Refer to the following example to quickly develop a feature with bulk SMS sending. Add the following code in the Controller or create a new Controller:

More parameter descriptions can be reference here

Refer to the following example to quickly develop a history of sending SMS messages based on a specified number. Add the following code in the Controller or create a new Controller:

More parameter descriptions can be found at reference here

By subscribing to the SmsReport SMS status report, you can know the status of each SMS message and whether it knows the status and related information of the terminal user. These efforts have been encapsulated internally by Spring Cloud AliCloud SMS. You only need to complete the following two steps.

1、Configure the queue name for SmsReport in the application.properties configuration file (which can also be application.yaml).

2、Implement the SmsReportMessageListener interface and initialize a Spring Bean.

More message body format for Message can be reference here.

By subscribing to the SmsUp upstream SMS message, you can know the content of the end user replying to the SMS. These efforts have also been packaged by Spring Cloud AliCloud SMS. You only need to complete the following two steps.

1、Configure the queue name for SmsReport in the application.properties configuration file (which can also be application.yaml).

2、Implement the SmsUpMessageListener interface and initialize a Spring Bean.

More message body format for Message can be reference here.

One of the biggest changes of Spring Boot 3.0 is the support for GraalVM native images, which the official takes a lot of time and effort. GraalVM, as an alternative to JRE, precompels java applications through technologies such as Ahead Of Time (AOT), which enables Spring to grasp more information about applications when running applications and makes the whole application start faster. In addition, the final application is smaller and has a lower memory footprint by eliminating unnecessary content during the compilation process through the compilation tool. It is excellent for some scenarios that require very high startup speed, such as Serverless and FaaS scenarios. This Spring Boot 3.0 directly moves it from Spring Native to Spring Boot, which also indicates that this technology begins to mature gradually and Spring ecology begins to enter the GraalVM stage!

GraalVM has the following features compared to the JVM compilation deployment:

Part of the middleware clients included in Spring Cloud Alibaba 2022.0.0.0 version of this release have completed the adaptation of constructing GraalVM native applications. The following is a sample application related to service registration, discovery module supported by the community. After upgrading to Spring Boot 3.0, GraalVM is used to build a native application image to test the startup speed and runtime usage. (Sentinel, Seata and RocketMQ are still being adapted. The following test process is simulated for 5 times respectively under the environment of MacOS 11.4, 2.6GHz 6-Core Intel Core i7 processor and 16G memory) :

From the above comparison, we can see that the latest Spring Cloud Alibaba application that supports Spring Boot 3.0 based on GraalVM will reduce application’s startup time, runtime memory usage and application package size. For example, Among them, the startup speed of the service registration consumption application is increased by nearly 10 times, and the running memory usage is reduced by nearly 2/3 compared with the original, which has a very obvious effect. This gives the cloud native era, hosting in the cloud application has brought significant advantages, so that it can be faster elastic expansion and contraction capacity and reduce the overall cost of the enterprise cloud!