1. Project Overview

SOFABoot is an open-source development framework provided by Ant Financial based on Spring Boot. It provides capabilities such as Readiness Check, context isolation, class isolation, and log space isolation on top of Spring Boot. In addition to enhancing Spring Boot, SOFABoot provides the ability for users to easily use SOFA middleware in Spring Boot.

2. Open Source License

Licensed under Apache-2.0

3. Screenshots

4. Feature Overview

1. Background

Spring Boot is an extremely excellent open-source framework that can easily build a Spring-based application. However, during use, some problems will still be encountered:

• Spring Boot provides a basic health check capability, and both middleware and applications can be extended to implement their own health check logic. However, Spring Boot's health check only has Liveness Check capability, lacking Readiness Check capability, which will cause a fatal problem. When a microservice application starts, it must first ensure that the application is healthy after startup before allowing upstream traffic to be put in (from RPC, gateway, scheduling tasks, etc.), otherwise it may cause a large number of errors within a certain time period.
• Although Spring Boot uses dependency management to ensure the maximum compatibility between Spring Boot-managed JAR packages, it is unavoidable that conflicts will still occur when introducing other JAR packages. Moreover, resolving these conflicts is not always easy, especially when the conflicting packages are serialization-related libraries, such as Hessian. For example, if an application component needs to use Hessian 3, while another component must use Hessian 4, due to the incompatibility between Hessian 3 and Hessian 4, and serialization involves upstream and downstream services in microservices, unifying Hessian to a single version is not an easy task.
• In the scenario of large-scale microservice operation and maintenance, platformization of operation and maintenance capabilities is a problem that must be solved, and monitoring is a particularly important point. For log monitoring, Spring Boot does not provide any solutions. Most open-source components require users to decide which logs to print, where to print them, and what file path to print them to, resulting in each application having a unique log configuration, and each application needing to configure its own log monitoring in the monitoring system, resulting in a very high implementation cost for key monitoring.
• In enterprise-level application scenarios, modular development is an effective solution to solve the high communication cost between multiple teams. Each business team focuses on developing their own application modules, and each module is self-contained, making it easier to develop and self-test, reducing the communication cost between teams. However, Spring Boot does not support modular development by default, and all Beans share a single Spring context. In multi-team development, if different teams define the same BeanId, a BeanId conflict error will occur at runtime.

To solve the above problems, and because each component in SOFA middleware needs to integrate Spring Boot, Ant Financial Group developed and open-sourced SOFABoot based on Spring Boot to solve the above problems and make it easier for users to use SOFA middleware in Spring Boot.

2. Introduction to Functions

To solve the problems that Spring Boot encounters when implementing large-scale microservices architecture, SOFABoot provides the following capabilities:

2.1 Enhanced Health Check Capability of Spring Boot

To address the lack of Readiness Check capability in Spring Boot, SOFABoot has added the health check capability of Spring Boot, providing Readiness Check capability. By utilizing the Readiness Check capability, the components in SOFA middleware will only allow traffic to be introduced to the application instances after passing the Readiness Check. For example, RPC will only register with the service registry center after passing the Readiness Check, and then traffic from the upstream application will enter.

Besides using Readiness Check events to control incoming traffic, PAAS systems can also use http://localhost:8080/health/readiness to get the Readiness Check status of applications and control the incoming traffic of devices such as load balancers.

2.2 Provides Class Isolation Ability

To solve the class dependency conflicts under Spring Boot, SOFABoot based on SOFAArk provides class isolation ability on Spring Boot, in a SOFABoot system, as long as the SOFAArk related dependencies are introduced, the ClassLoader of SOFA middleware-related classes and application-related classes can be isolated, preventing class conflicts. Of course, users can also use SOFAArk to isolate other middleware, third-party dependencies, and application classes.

2.3 Log Space Isolation Ability

To unify the printing of middleware logs in large-scale microservice scenarios, SOFABoot provides log space isolation ability to SOFA middleware, after SOFA middleware components use log space isolation ability, they will automatically separate their own logs and application logs, and the log paths are also fixed, making it very convenient to monitor uniformly.

2.4 SOFA Middleware's Integration Management

Based on Spring Boot's automatic configuration capability, SOFABoot provides SOFA Middleware's unified and easy-to-use programming interface as well as Spring Boot's Starter, making it convenient to use SOFA Middleware in Spring Boot environment, and each component in SOFA Middleware is independently pluggable, saving development time and maintenance costs.

2.5 Modular Development

SOFABoot supports modular development capability based on Spring context isolation from version 2.4.0, each SOFABoot module uses an independent Spring context, avoiding BeanId conflicts between different SOFABoot modules, effectively reducing the communication costs between teams in enterprise-level multi-module development.

5. Tech Stack

Example

SOFABoot sample project sofaboot-samples includes the following demo projects:

• SOFABoot Sample Project
• SOFABoot Sample Project (with class isolation ability)
• SOFABoot Sample Project (with modular development ability)
• SOFABoot Sample Project (using SOFARPC)
• SOFABoot Sample Project (using scheduling tasks)

In this document, a Spring Boot project will be created, introducing SOFABoot basic dependencies and SOFABoot health check extension capabilities, demonstrating how to quickly get started with SOFABoot.

Environment Preparation

To use SOFABoot, the basic environment needs to be prepared first, SOFABoot depends on the following environment: - JDK7 or JDK8 - A version of Apache Maven 3.2.5 or above is required for compilation

Create a project

SOFABoot is directly built on top of Spring Boot, so Spring Boot's project generation tool can be used to generate it, in this document, we need to add a Web dependency to be able to view the effect in the browser later.

Introduce SOFABoot

After creating a good Spring Boot project, the next step is to introduce the SOFABoot dependency, first, you need to import the Spring Boot project generated in the previous text into the IDE, and then add the SOFABoot dependency to the project's pom.xml file.zip After unpacking, modify the configuration file of the maven project pom.xml， will be opened

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>${spring.boot.version}</version>
    <relativePath/> 
</parent>

Replace with:

<parent>
    <groupId>com.alipay.sofa</groupId>
    <artifactId>sofaboot-dependencies</artifactId>
    <version>${sofa.boot.version}</version>
</parent>

Here's ${sofa.boot.version} specifies a specific version of SOFABoot, refer to the release history. Then, add the dependency of SOFABoot health check extension capability and Web dependency (convenient for viewing health check results):

<dependency>
    <groupId>com.alipay.sofa</groupId>
    <artifactId>healthcheck-sofa-boot-starter</artifactId>
</dependency>

<dependency>
     <groupId>org.springframework.boot</groupId>
     <artifactId>spring-boot-starter-web</artifactId>
</dependency>

Finally, in the project's application.properties file, add the SOFABoot project's commonly used parameter configuration, where spring.application.name is a required parameter used to indicate the name of the current application; logging path is used to specify the output directory of the log.

# Application Name
spring.application.name=SOFABoot Demo
# logging path
logging.path=./logs

Run

You can import the project into the IDE and run the generated project in the main method (usually in the XXXApplication class) to start the application, or you can directly run the project in the root directory of the project mvn spring-boot:run, and you will see the startup printed logs in the console:

2018-04-05 21:36:26.572  INFO ---- Initializing ProtocolHandler ["http-nio-8080"]
2018-04-05 21:36:26.587  INFO ---- Starting ProtocolHandler [http-nio-8080]
2018-04-05 21:36:26.608  INFO ---- Using a shared selector for servlet write/read
2018-04-05 21:36:26.659  INFO ---- Tomcat started on port(s): 8080 (http)

You can view the current SOFABoot version information summary generated by the Maven plugin by entering http://localhost:8080/actuator/versions in the browser, with a result similar to the following:

[
  {
    GroupId: "com.alipay.sofa",
    Doc-Url: "https://github.com/sofastack/sofa-boot",
    ArtifactId: "infra-sofa-boot-starter",
    Built-Time: "2018-04-05T20:55:26+0800",
    Commit-Time: "2018-04-05T20:54:26+0800",
    Commit-Id: "049bf890bb468aafe6a3e07b77df45c831076996",
    Version: "2.4.4"
  }
]

Note: In SOFABoot 3.x, the endpoint path was adjusted, and sofaboot/versions was changed to actuator/versions

Can be viewed by entering http://localhost:8080/health/readiness in the browser, similar to the following:

{
  status: "UP",
  sofaBootComponentHealthCheckInfo: {
    status: "UP"
  },
  springContextHealthCheckInfo: {
    status: "UP"
  },
  DiskSpace: {
    status: "UP",
    total: 250140434432,
    free: 22845308928,
    threshold: 10485760
  }
}

Note: In SOFABoot 3.x, the endpoint path was adjusted, and health/readiness was changed to actuator/readiness

status: "UP" indicates the health of the application Readiness Check. Can be viewed by entering http://localhost:8080/health in the browser to view the runtime health status of the application (which may change over time).

Note: In SOFABOOT 3.X, the endpoint path was adjusted, and /health was changed to /actuator/health

View logs

In the above application.properties , the log printing directory configured is ./logs , which is the root directory of the current application (which can be configured according to our own practices), and in the root directory of the current project, you can see log files with a structure similar to the following:

./logs
├── health-check
│   ├── sofaboot-common-default.log
│   └── sofaboot-common-error.log
├── infra
│   ├── common-default.log
│   └── common-error.log
└── spring.log

If the application fails to start or the health check returns an error, you can find the error reason in the corresponding log file, and some need to pay attention to common-error.log logs.

Testing

We know that SpringBoot officially provides JUnit4 integration, SpringRunner, which is used for writing test cases; in SOFABoot, the original SpringRunner, can still be used, but it is recommended to use SOFABoot's own SofaBootRunner and SofaJUnit4Runner to write integrated tests and unit tests; the application needs to import the following Starter:

<dependency>
    <groupId>com.alipay.sofa</groupId>
    <artifactId>test-sofa-boot-starter</artifactId>
</dependency>

Note that if you need to use SOFABoot's class isolation capability, you must import the above dependency and use SofaBootRunner and SofaJUnit4Runner for testing.

Modular development

This part will demonstrate how to perform modular development in the SOFABoot environment. You can find the example code for this document directly under the project, which includes a total of four modules:

.
│
├── service-facade 
│ 
├── service-provider
│ 
├── service-consumer
│ 
└── sofa-boot-run

The functions of each module are as follows:

• service-facade: Demonstrates the API package for JVM service publishing and referencing;
• service-provider: Demonstrates XML method, Annotation method, and API method publishing JVM services;
• service-consumer: Demonstrates XML method, Annotation method, and API method referencing JVM services;
• sofa-boot-run: Starts the SOFA Boot application containing the SOFABoot module;

It is recommended to refer to the module isolation document before learning this Demo

Define service API

The service-facade module contains the API used to demonstrate JVM service publishing and referencing:

public interface SampleJvmService {
    String message();
}

Publish JVM service

service-provider is a SOFABoot module used to demonstrate XML method, Annotation method, and API method publishing JVM services.

Define SOFABoot module

Add a sofa-module.properties file to the service-provider module to define it as a SOFABoot module:

Module-Name=com.alipay.sofa.service-provider

XML method publishing service

Implement the SampleJvmService interface:

public class SampleJvmServiceImpl implements SampleJvmService {
    private String message;

    @Override
    public String message() {
        System.out.println(message);
        return message;
    }

    // getters and setters
}

Add a META-INF/spring/service-provide.xml file to publish SampleJvmServiceImpl as a JVM service:

<bean id="sampleJvmService" class="com.alipay.sofa.isle.sample.SampleJvmServiceImpl">
    <property name="message" value="Hello, jvm service xml implementation."/>
</bean>

<sofa:service ref="sampleJvmService" interface="com.alipay.sofa.isle.sample.SampleJvmService">
    <sofa:binding.jvm/>
</sofa:service>

Annotation method publishing service

Implement the SampleJvmService interface and add the @SofaService annotation:

@SofaService(uniqueId = "annotationImpl")
public class SampleJvmServiceAnnotationImpl implements SampleJvmService {
    @Override
    public String message() {
        String message = "Hello, jvm service annotation implementation.";
        System.out.println(message);
        return message;
    }
}

In order to distinguish the JVM services published by XML method, the uniqueId property needs to be added to the annotation.

Configure SampleJvmServiceAnnotationImpl as a Spring Bean to ensure the @SofaService annotation takes effect:

<bean id="sampleJvmServiceAnnotation" class="com.alipay.sofa.isle.sample.SampleJvmServiceAnnotationImpl"/>

API method publishing service

Add the PublishServiceWithClient class to demonstrate API method publishing service:

public class PublishServiceWithClient implements ClientFactoryAware {
    private ClientFactory clientFactory;

    public void init() {
        ServiceClient serviceClient = clientFactory.getClient(ServiceClient.class);
        ServiceParam serviceParam = new ServiceParam();
        serviceParam.setInstance(new SampleJvmServiceImpl("Hello, jvm service service client implementation."));
        serviceParam.setInterfaceType(SampleJvmService.class);
        serviceParam.setUniqueId("serviceClientImpl");
        serviceClient.service(serviceParam);
    }

    @Override
    public void setClientFactory(ClientFactory clientFactory) {
        this.clientFactory = clientFactory;
    }
}

Configure PublishServiceWithClient as a Spring Bean and set the init-method to publish the service when Spring is refreshed:

<bean id="publishServiceWithClient" class="com.alipay.sofa.isle.sample.PublishServiceWithClient" init-method="init"/>

Reference JVM service

service-consumer is a SOFABoot module used to demonstrate XML method, Annotation method, and API method referencing JVM services.

Define SOFABoot module

Add a sofa-module.properties file to the service-consumer module to define it as a SOFABoot module:

Module-Name=com.alipay.sofa.service-consumer
Require-Module=com.alipay.sofa.service-provider

In the sofa-module.properties file, specify Require-Module to ensure that the service-provider module is refreshed before the service-consumer module:

XML method referencing service

Add a META-INF/spring/service-consumer.xml file to reference the services published by the service-provider module:

<sofa:reference id="sampleJvmService" interface="com.alipay.sofa.isle.sample.SampleJvmService">
    <sofa:binding.jvm/>
</sofa:service>

Annotation method referencing service

Define the JvmServiceConsumer class and add the @SofaReference annotation to its sampleJvmServiceAnnotationImpl property:

public class JvmServiceConsumer implements ClientFactoryAware {
    @SofaReference(uniqueId = "annotationImpl")
    private SampleJvmService sampleJvmServiceAnnotationImpl;
}

Configure JvmServiceConsumer as a Spring Bean to ensure the @SofaReference annotation takes effect:

<bean id="consumer" class="com.alipay.sofa.isle.sample.JvmServiceConsumer" init-method="init" />

API method referencing service

JvmServiceConsumer implements the ClientFactoryAware interface and references the JVM service in its init method:

public class JvmServiceConsumer implements ClientFactoryAware {
    private ClientFactory    clientFactory;

    public void init() {
        ReferenceClient referenceClient = clientFactory.getClient(ReferenceClient.class);
        ReferenceParam<SampleJvmService> referenceParam = new ReferenceParam<>();
        referenceParam.setInterfaceType(SampleJvmService.class);
        referenceParam.setUniqueId("serviceClientImpl");
        SampleJvmService sampleJvmServiceClientImpl = referenceClient.reference(referenceParam);
        sampleJvmServiceClientImpl.message();
    }

    @Override
    public void setClientFactory(ClientFactory clientFactory) {
        this.clientFactory = clientFactory;
    }
}

Start the SOFABoot application

Configure the parent module as SOFABoot:

<parent>
    <groupId>com.alipay.sofa</groupId>
    <artifactId>sofaboot-dependencies</artifactId>
    <version>2.4.4</version>
</parent>

Add isle-sofa-boot-starter and service-provider, service-consumer dependencies to the module:

<dependency>
    <groupId>com.alipay.sofa</groupId>
    <artifactId>isle-sofa-boot-starter</artifactId>
</dependency>
<dependency>
    <groupId>com.alipay.sofa</groupId>
    <artifactId>service-provider</artifactId>
</dependency>
<dependency>
    <groupId>com.alipay.sofa</groupId>
    <artifactId>service-consumer</artifactId>
</dependency>

Start the ApplicationRun class, and the console will display the following output:

Hello, jvm service xml implementation.
Hello, jvm service annotation implementation.
Hello, jvm service service client implementation.

Write test cases

The SOFABoot moduleized testing method is consistent with the Spring Boot testing method. You only need to add the @SpringBootTest annotation and the @RunWith(SpringRunner.class) annotation to the test case. In the test case, you can also use the @SofaReference annotation to test the services published by the SOFABoot module:

@SpringBootTest
@RunWith(SpringRunner.class)
public class SofaBootWithModulesTest {
    @SofaReference
    private SampleJvmService sampleJvmService;

    @SofaReference(uniqueId = "annotationImpl")
    private SampleJvmService sampleJvmServiceAnnotationImpl;

    @SofaReference(uniqueId = "serviceClientImpl")
    private SampleJvmService sampleJvmServiceClientImpl;

    @Test
    public void test() {
        Assert.assertEquals("Hello, jvm service xml implementation.", sampleJvmService.message());
        Assert.assertEquals("Hello, jvm service annotation implementation.",
            sampleJvmServiceAnnotationImpl.message());
        Assert.assertEquals("Hello, jvm service service client implementation.",
            sampleJvmServiceClientImpl.message());
    }
}