Integrate with Spring Cloud SOFA-Scalable Open Financial Architecture(SOFAStack)-阿里云帮助中心

Spring Cloud SOFA is a development framework based on the Spring Cloud ecosystem. It provides a one-stop solution for microservice development. Spring Cloud SOFA includes the components required to develop distributed applications. You can use the Spring Cloud programming model to connect your application to SOFA middleware. This lets you quickly build finance-grade, cloud-native distributed applications.

Compatible versions

Spring Cloud SOFA is compatible with a wide range of Spring Cloud versions.

Spring Cloud SOFA version	Spring Cloud version	Spring Boot version
2021.X	Greenwich	2.1.X
	Hoxton	2.2.X ~ 2.3.X
	2020.X	2.4.5 ~ 2.5.X
	2021.X	2.6.X ~ 2.7.X
2023.x	2023.x	3.2.x

Import common dependencies

In your project's Maven configuration, add the Spring Cloud SOFA version to the dependencyManagement section to manage the versions of related Spring Cloud SOFA dependencies. Note that version mappings may change with official Spring Cloud upgrades. The following code provides an example:

<dependencyManagement>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-dependencies</artifactId>
        <version>2.7.16</version>
        <type>pom</type>
        <scope>import</scope>
    </dependency>
    <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-dependencies</artifactId>
        <version>2021.0.8</version>
        <type>pom</type>
        <scope>import</scope>
    </dependency>
    <dependency>
        <groupId>com.alipay.cloud</groupId>
        <artifactId>spring-cloud-sofa-dependencies</artifactId>
        <version>2021.0.0</version>
        <type>pom</type>
        <scope>import</scope>
    </dependency>
</dependencyManagement>

Add common configurations

You can configure the following common parameters in application.properties to connect Spring Cloud SOFA to the SOFA commercial middleware products.

spring.application.name={your-project-name}
spring.cloud.sofa.instanceid={sofa-middleware-instance-id}
spring.cloud.sofa.acvip.endpoint={sofa-acvip-lb-address}
spring.cloud.sofa.mw.access={sofa-middleware-ak}
spring.cloud.sofa.mw.secret={sofa-middleware-sk}
spring.cloud.sofa.ldc.region={sofa-application-region}
spring.cloud.sofa.ldc.datacenter={sofa-application-data-center}
spring.cloud.sofa.ldc.zone={sofa-application-zone}

Parameter descriptions:

Parameter	Description
spring.application.name	The application name. It identifies the current application. This parameter is required and must be globally unique. It is used to identify the application in features such as service discovery, service administration, and dynamic configuration.
spring.cloud.sofa.instanceid	The instance ID. It is used to distinguish between tenants. Data is isolated between different instances.
spring.cloud.sofa.acvip.endpoint	The ACVIP address. ACVIP manages the server addresses for SOFA middleware and provides advanced features such as node probing, connection convergence, and multi-datacenter disaster recovery. Configure the correct ACVIP address to connect to all SOFA middleware. You do not need to configure a separate address for each middleware.
spring.cloud.sofa.mw.access	The AccessKey (AK) for middleware authentication. If authentication is enabled, a valid AK and Secret Key (SK) are required to connect to the middleware.
spring.cloud.sofa.mw.secret	Middleware authentication: If enabled, you must provide a valid AK and SK to connect to the middleware.
spring.cloud.sofa.ldc.region	The application's location information. This identifies the region where the application belongs.
spring.cloud.sofa.ldc.datacenter	The application's location information. This identifies the data center where the application belongs.
spring.cloud.sofa.ldc.zone	The application's location information. This identifies the zone where the application belongs.

If you have developed applications with SOFABoot, you can continue to use its common configuration keys. The common configuration keys in Spring Cloud SOFA are compatible with those in the SOFABoot framework, so configurations that use SOFABoot keys also work in Spring Cloud SOFA.

Spring Cloud SOFA configuration key	SOFABoot configuration key
spring.cloud.sofa.instanceid	com.alipay.instanceid
spring.cloud.sofa.acvip.endpoint	com.antcloud.antvip.endpoint
spring.cloud.sofa.mw.access	com.antcloud.mw.access
spring.cloud.sofa.mw.secret	com.antcloud.mw.secret
spring.cloud.sofa.ldc.region	com.alipay.ldc.region
spring.cloud.sofa.ldc.datacenter	com.alipay.ldc.datacenter
spring.cloud.sofa.ldc.zone	com.alipay.ldc.zone

Note that when you use the dynamic configuration feature (Bootstrap mode), the configurations related to middleware connections must be moved to the bootstrap.properties file. For more information, see Bootstrap mode.

Add Spring Cloud SOFA components

Spring Cloud SOFA provides the following components for integrating with SOFA commercial middleware:

Component name	Component description	Component type
spring-cloud-starter-sofa-registry	The registry module. It connects applications to the SOFA registry and provides advanced features such as graceful online publishing, proximity-based routing, dual registration, and dual subscription.	Microservice
spring-cloud-starter-sofa-service	The service routing module. It adds routing capabilities to applications, such as dynamic routing and grayscale routing. It also supports custom service routing extensions.	Microservice
spring-cloud-starter-sofa-guardian	The service administration module. It provides administration features such as throttling, circuit breaking, service degradation, authentication, and fault injection.	Microservice
spring-cloud-starter-sofa-drm	The dynamic configuration module. It connects applications to the DRM configuration center. It supports features such as hosted application configuration, dynamic configuration delivery, and high consistency guarantees.	Microservice
spring-cloud-starter-sofa-health	The health check module. It extends Spring Boot's Actuator with readiness probes and advanced features like application readiness callbacks.	Common module
spring-cloud-starter-sofa-tracer	The tracing module. It integrates SOFA Tracer to print full-link logs. It supports a wide range of SOFA and open source mainstream middleware and frameworks.	Common module

You can import these modules individually to use specific features. Spring Cloud SOFA is highly compatible with other open source and commercial Spring Cloud ecosystems, so you can combine them as needed. However, we recommend that you import a complete set of components of a specific type, such as all microservice components. This provides access to all enhanced features and simplifies integration with the SOFA middleware console.