spring-cloud-alibaba README

The project's README from github.com/alibaba/spring-cloud-alibaba. As one markdown file: README.md.

Spring Cloud Alibaba

CircleCI Maven Central License actions Leaderboard

A project maintained by Alibaba.

See the 中文文档 for Chinese readme.

Spring Cloud Alibaba provides a one-stop solution for distributed application development. It contains all the components required to develop distributed applications, making it easy for you to develop your applications using Spring Cloud.

With Spring Cloud Alibaba, you only need to add some annotations and a small amount of configurations to connect Spring Cloud applications to the distributed solutions of Alibaba, and build a distributed application system with Alibaba middleware.

Features

For more features, please refer to Roadmap.

In addition to the above-mentioned features, for the needs of enterprise users' scenarios, Microservices Engine (MSE) of Spring Cloud Alibaba's enterprise version provides an enterprise-level microservices governance center, which includes more powerful governance capabilities such as Grayscale Release, Service Warm-up, Lossless Online and Offline and Outlier Ejection. At the same time, it also provides a variety of products and solutions such as enterprise-level Nacos registration / configuration center, enterprise-level cloud native gateway.

Components

Sentinel: Sentinel takes "traffic flow" as the breakthrough point, and provides solutions in areas such as flow control, concurrency, circuit breaking, and load protection to protect service stability.

Nacos: An easy-to-use dynamic service discovery, configuration and service management platform for building cloud native applications.

RocketMQ: A distributed messaging and streaming platform with low latency, high performance and reliability, trillion-level capacity and flexible scalability.

Seata: A distributed transaction solution with high performance and ease of use for microservices architecture.

Alibaba Cloud OSS: An encrypted and secure cloud storage service which stores, processes and accesses massive amounts of data from anywhere in the world.

Alibaba Cloud SMS: A messaging service that covers the globe, Alibaba SMS provides convenient, efficient, and intelligent communication capabilities that help businesses quickly contact their customers.

Alibaba Cloud SchedulerX: Accurate, highly reliable, and highly available scheduled job scheduling services with response time within seconds.

For more features please refer to Roadmap.

How to build

Spring Cloud uses Maven for most build-related activities, and you should be able to get off the ground quite quickly by cloning the project you are interested in and typing:

./mvnw install

How to Use

Add maven dependency

Release Version

These artifacts are available from Maven Central and Spring Release repository via BOM:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.alibaba.cloud</groupId>
            <artifactId>spring-cloud-alibaba-dependencies</artifactId>
            <version>2025.1.0.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

add the module in dependencies. If you want to choose an older version, you can refer to the Release Notes.

Snapshot

If you need to use the already published Snapshot Version, add the following configuration in the dependencyManagement.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.alibaba.cloud</groupId>
            <artifactId>spring-cloud-alibaba-dependencies</artifactId>
            <version>2025.1.0.1-SNAPSHOT</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Add the following configuration in repositories. If users in China have difficulty accessing the maven.pkg.github.com domain, consider using Alibaba Cloud Effect Artifact Repository as a proxy for GitHub Packages.

<repositories>
    <repository>
        <id>github</id>
        <url>https://maven.pkg.github.com/alibaba/spring-cloud-alibaba</url>
        <releases>
            <enabled>false</enabled>
        </releases>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </repository>
</repositories>

Add the following configuration in settings.xml.

<servers>
    <server>
        <id>github</id>
        <username>Your GitHub Username</username>
        <password>Your GitHub Token (requires read:packages permission)</password>
    </server>
</servers>

Add Gradle dependency

Release Version

Use Maven Central BOM in your build.gradle (or build.gradle.kts) via platform:

dependencies {
    implementation platform("com.alibaba.cloud:spring-cloud-alibaba-dependencies:2025.1.0.0")

    // choose starter(s) as needed
    implementation "com.alibaba.cloud:spring-cloud-starter-alibaba-nacos-config"
}

Snapshot

If you need the published Snapshot Version, use snapshot BOM and add GitHub Packages repository:

repositories {
    mavenCentral()
    maven {
        url = uri("https://maven.pkg.github.com/alibaba/spring-cloud-alibaba")
        credentials {
            username = findProperty("gpr.user") ?: System.getenv("GITHUB_USERNAME")
            password = findProperty("gpr.key") ?: System.getenv("GITHUB_TOKEN")
        }
    }
}

dependencies {
    implementation platform("com.alibaba.cloud:spring-cloud-alibaba-dependencies:2025.1.0.0-SNAPSHOT")

    // choose starter(s) as needed
    implementation "com.alibaba.cloud:spring-cloud-starter-alibaba-nacos-config"
}

You can put credentials in ~/.gradle/gradle.properties:

gpr.user=Your GitHub Username
gpr.key=Your GitHub Token (requires read:packages permission)

Examples

A spring-cloud-alibaba-examples module is included in our project for you to get started with Spring Cloud Alibaba quickly. It contains an example, and you can refer to the readme file in the example project for a quick walkthrough.

Examples：

Sentinel Example

Nacos Example

RocketMQ Example

Alibaba Cloud OSS Example

Version control guidelines

The version number of the project is in the form of x.x.x, where x is a number, starting from 0, and is not limited to the range 0~9. When the project is in the incubator phase, the version number is 0.x.x.

As the interfaces and annotations of Spring Boot 1 and Spring Boot 2 have been changed significantly in the Actuator module, and spring-cloud-commons is also changed quite a lot from 1.x.x to 2.0.0, we take the same version rule as SpringBoot version number.

Code of Conduct

This project is a sub-project of Spring Cloud, it adheres to the Contributor Covenant code of conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to [email protected].

Code Conventions and Housekeeping

None of these is essential for a pull request, but they will all help. They can also be added after the original pull request but before a merge.

Use the Spring Framework code format conventions. If you use Eclipse you can import formatter settings using the eclipse-code-formatter.xml file from the Spring Cloud Build project. If using IntelliJ, you can use the Eclipse Code Formatter Plugin to import the same file.

Make sure all new .java files to have a simple Javadoc class comment with at least an @author tag identifying you, and preferably at least a paragraph on what the class is for.

Add the ASF license header comment to all new .java files (copy from existing files in the project)

Add yourself as an @author to the .java files that you modify substantially (more than cosmetic changes).

Add some Javadocs and, if you change the namespace, some XSD doc elements.

A few unit tests would help a lot as well —— someone has to do it.

If no-one else is using your branch, please rebase it against the current 2023.x (or other target branch in the main project).

When writing a commit message please follow these conventions, if you are fixing an existing issue please add Fixes gh-XXXX at the end of the commit message (where XXXX is the issue number).

Contact Us

Mailing list is recommended for discussing almost anything related to spring-cloud-alibaba.

[email protected]: You can ask questions here if you encounter any problem when using or developing spring-cloud-alibaba.

spring-cloud-alibaba (alibaba/spring-cloud-alibaba)

Searching Database…

29.2K ·GitHub
Spring-cloud-alibaba
这是什么东西？阿里巴巴出品的 Spring Cloud 工具包：一套一站式组件，用于在 Nacos、Sentinel、RocketMQ、Seata 等阿里中间件之上构建分布式 Java 应用。
那它是接入我应用的框架，还是我需要部署的平台？它是一个框架，不是独立产品：你把它的 Spring Cloud 模块作为依赖加进来，你的代码仍然是一个普通的 Spring Boot 服务，它所连接的中间件则单独运行。
我怎么把它加到项目里？在 Maven 的 dependencyManagement 中引入 Maven Central 上的 BOM（Gradle 也可以通过 platform() 使用），然后把需要的模块作为依赖添加。仓库里还包含一个 spring-cloud-alibaba-examples 模块，里面有可以直接运行的示例。
它需要哪些 Java 和 Spring Boot 版本？它跟随 Spring 的发布线：2023.x 分支面向 Spring Cloud 2023 和 Boot 3.2.x，需要 JDK 17 及以上；而 2021.x 等较老的分支仍可在 JDK 8 及以上运行。请选择与你的 Spring Boot 版本匹配的分支。
好几个功能听起来像阿里云的产品——我需要阿里云账号吗？OSS、短信和 SchedulerX 需要——它们是阿里云的托管服务。核心集成（Sentinel、Nacos、RocketMQ、Seata）都是开源中间件，你可以自己部署运行。
开箱即用，它能为我的服务提供什么？可动态修改规则的流量控制和服务降级、带负载均衡的服务注册与发现、自动刷新的外部化配置、基于共享消息的事件驱动微服务，以及分布式事务。
它实际集成了哪些组件？Sentinel 用于流控、并发控制和熔断；Nacos 用于服务发现和配置；RocketMQ 用于消息；Seata 用于分布式事务；另外还有阿里云的 OSS、短信和 SchedulerX。
有企业版吗？有——企业版基于阿里云的微服务引擎（MSE），增加了带灰度发布、服务预热、无损上下线、离群实例摘除等能力的治理中心，还提供企业版 Nacos 和云原生网关。
在决定用之前，我在哪里能看到实际效果？仓库自带一个 spring-cloud-alibaba-examples 模块，里面有 Sentinel、Nacos、RocketMQ 和阿里云 OSS 的示例，每个示例都配有自己的 readme 演练文档。
What are similar projects?SpringBoot-Labs, nacos, yudao-cloud, go-zero, SpringCloudLearning, SpringAll, Sentinel, newbee-mall
Which topics is it in?rocketmq, circuit-breaker, service-discovery, dubbo, springboot, object-storage, spring-cloud, alibaba, message-queue, gateway, config, spring
Creator
alibaba
Size
55.1 MB
Stars
29.2K
Updated
CommitSep 27Release2025.1.0.0Feb 06
Age
8y
Commits · 90 Days