生产环境可参考 | Spring Boot 4.0 | Spring Cloud Alibaba 2025.1.x | Dubbo 3.3.6
在微服务架构日益普及的今天，如何快速上手 Spring Cloud Alibaba 生态？如何确保你的技术选型与最新框架版本兼容？本文将为你介绍一个精心打造的 Spring Cloud Alibaba 示例项目 —— spring-cloud-samples，它不仅覆盖了主流微服务场景，更紧跟技术前沿，基于最新的 Spring Boot 4.0 和 Spring Cloud Alibaba 2025.1.x 构建。
🎯 为什么需要这个项目？
痛点一：官方文档分散，集成难度大
Spring Cloud Alibaba 包含众多组件（Nacos、Sentinel、Dubbo、Stream 等），官方文档虽然详尽，但缺乏完整的端到端示例。开发者在实际集成时常常遇到：
- 依赖版本冲突
- 配置项不明确
- 组件间协作问题
- 链路追踪、负载均衡等高级功能难以落地
痛点二：技术更新快，旧示例无法参考
随着 Spring Boot 4.0 的发布，大量 API 和配置方式发生变化：
ObservationRegistry替代旧的 Micrometer API- Tracing 模块重新拆分
- WebFlux 链路追踪上下文传播机制调整
- GlobalFilter 包名变更
很多基于 Spring Boot 2.x/3.x 的示例已不再适用。
痛点三：生产环境最佳实践缺失
大多数示例项目仅展示"能跑通"的基础功能，缺少：
- 链路追踪（OpenTelemetry）集成
- 网关限流熔断（Sentinel Gateway）
- 响应式编程（WebFlux）支持
- 消息驱动（Spring Cloud Stream）
- 一键启动脚本和自动化测试
🚀 项目亮点
✨ 1. 紧跟技术前沿
本项目基于最新稳定版本构建：
- Spring Boot 4.0.7 - 体验最新特性
- Spring Cloud 2025.1.2 - 云原生能力增强
- Spring Cloud Alibaba 2025.1.0.0 - 阿里中间件深度集成
- Dubbo 3.3.6 - 高性能 RPC 框架
- Protobuf 4.34.1 - 高效序列化
🏗️ 2. 完整的微服务架构
项目包含 10 个模块，覆盖典型微服务场景：
| 模块 | 端口 | 说明 |
|---|---|---|
| cloud-gateway-sample | 8764 | Spring Cloud Gateway + Sentinel 限流 |
| cloud-provider-sample | 8765 | 传统 Web 服务提供者 |
| cloud-consumer-sample | 8766 | 传统 Web 服务消费者（OpenFeign） |
| cloud-provider-reactive-sample | 8762 | 响应式 Web 服务提供者（WebFlux） |
| cloud-consumer-reactive-sample | 8763 | 响应式 Web 服务消费者 |
| cloud-provider-dubbo-sample | 50051 | Dubbo RPC 服务提供者 |
| cloud-consumer-dubbo-sample | - | Dubbo RPC 服务消费者 |
| cloud-nacos-config-sample | 8761 | Nacos 动态配置演示 |
| cloud-stream-sample | - | Spring Cloud Stream + RocketMQ |
| cloud-sample-api | - | 公共接口定义 |
🔍 3. 多协议服务调用演示
HTTP REST 调用
# 直接访问（consumer → provider）
curl 'http://localhost:8766/hi?name=hongxi'# 通过网关访问（gateway → consumer → provider）
curl 'http://localhost:8764/consumer-sample/hi?name=hongxi'
Dubbo RPC 调用
# consumer 调用 Dubbo 服务
curl 'http://localhost:8766/dubbo?name=hongxi'# 通过网关调用 Dubbo REST 接口
curl http://localhost:8764/provider-dubbo-sample/api/hello/lily
curl 'http://localhost:8764/provider-dubbo-sample/api/add?a=1&b=2'
响应式 WebFlux 调用
# Reactive Consumer → Reactive Provider
curl 'http://localhost:8763/hi?name=hongxi'# 通过网关访问响应式服务
curl 'http://localhost:8764/consumer-reactive-sample/hi?name=hongxi'
🛡️ 4. Sentinel 网关限流实战
Gateway 集成 Sentinel，通过 Nacos 动态配置限流规则：
API 分组配置（SENTINEL_GROUP/gw-api-group）：
[{"apiName": "consumer_api","predicateItems": [{"pattern": "/consumer-sample/**","matchStrategy": 1}]}
]
流量控制规则（SENTINEL_GROUP/gw-flow）：
[{"resource": "consumer_api","resourceMode": 1,"count": 5}
]
快速刷新访问触发限流时返回：
{"code":444,"msg":"Sentinel gateway block"}
📊 5. 链路追踪（Tracing）集成
项目解决了 Spring Boot 4.0 下链路追踪的关键问题：
- OpenTelemetry 自动配置
- Dubbo RPC 上下文传播（通过 Filter SPI）
- WebFlux 链路追踪桥接
- Gateway 全局采样配置
- OTLP Metrics 导出
所有请求自动生成 traceId，可在 Jaeger/Zipkin 中查看完整调用链。
💬 6. Spring Cloud Stream 消息驱动
集成 RocketMQ，演示消息发送与消费：
# 启动 RocketMQ
bin/mqnamesrv
bin/mqbroker -n localhost:9876 --enable-proxy# 创建 Topic 和消费组
bin/mqadmin updateTopic -n localhost:9876 -c DefaultCluster -t stream-demo-topic
bin/mqadmin updateSubGroup -n localhost:9876 -c DefaultCluster -g stream-demo-consumer-group# 启动 stream 模块观察日志
🎨 7. Nacos 动态配置演示
展示多种配置读取方式：
@Value注解注入@ConfigurationProperties绑定NacosConfigManagerAPI 操作- 配置热更新监听
⚙️ 8. 一键启动脚本
提供完善的运维脚本 start-all.sh：
# 启动所有服务（自动检查 Nacos、安装依赖、健康检测）
sh start-all.sh# 停止所有服务（清理 PID 和日志）
sh start-all.sh stop# 重启所有服务
sh start-all.sh restart# 查看服务状态
sh start-all.sh status
脚本特性：
- ✅ 防重复启动检查
- ✅ Nacos 就绪检测
- ✅ 端口占用检测
- ✅ 进程健康监控
- ✅ 自动执行 curl 测试并输出结果
🏛️ 架构设计
┌─────────────────┐│ Nacos Server ││ (注册+配置中心) │└────────┬────────┘│┌────────────────────┼────────────────────┐│ │ │▼ ▼ ▼
┌───────────────┐ ┌───────────────┐ ┌──────────────────┐
│ Gateway │ │ Consumer │ │ Consumer-Reactive│
│ (8764) │──▶│ (8766) │ │ (8763) │
│ + Sentinel │ │ + OpenFeign │ │ + WebClient │
└───────────────┘ └───────┬───────┘ └────────┬─────────┘│ │▼ ▼┌──────────────────────────────────────┐│ Provider (8765) ││ Provider-Reactive (8762) ││ Provider-Dubbo (50051) │└──────────────────────────────────────┘│▼┌──────────────────────┐│ RocketMQ Broker ││ (Stream 消息中间件) │└──────────────────────┘
核心设计理念：
- 统一服务发现：所有服务（Web + Dubbo）使用
DEFAULT_GROUP，Gateway 可直接发现 Dubbo 服务 - 分层解耦：API 接口独立模块，提供者与消费者通过接口契约通信
- 协议无关：Consumer 可同时调用 REST 和 Dubbo 服务
- 响应式优先：提供 WebFlux 示例，适配高并发场景
🎓 学习价值
对于初学者
- ✅ 从零搭建完整的微服务项目
- ✅ 理解服务注册发现、配置中心、网关、RPC 等核心概念
- ✅ 掌握 Spring Cloud Alibaba 各组件协作方式
对于进阶开发者
- ✅ Spring Boot 4.0 新特性实践（Tracing、Observation API）
- ✅ Dubbo 3.x 与 Spring Cloud 集成最佳实践
- ✅ WebFlux 响应式编程模型
- ✅ OpenTelemetry 链路追踪上下文传播
- ✅ Sentinel 网关限流动态配置
对于架构师
- ✅ 多协议服务治理方案（HTTP + Dubbo）
- ✅ 微服务可观测性建设（Tracing + Metrics）
- ✅ 生产环境部署脚本设计
- ✅ 依赖版本管理与冲突解决
🚦 快速开始
前置要求
- Java 17+
- Maven 3.8+
- Nacos Server 3.2.x（下载地址）
- RocketMQ 5.x（可选，用于 Stream 演示）
三步启动
1. 启动 Nacos
# 下载并启动 Nacos
sh nacos/bin/startup.sh -m standalone
2. 启动所有服务
git clone https://github.com/javahongxi/spring-cloud-samples.git
cd spring-cloud-samples
sh start-all.sh
3. 访问演示接口
脚本会自动执行测试并输出结果：
========== 访问演示 URL ==========[直接访问 consumer-reactive]URL: http://localhost:8763/hi?name=hongxi响应: Hi, hongxi! I am from provider-reactive.HTTP Status: 200[通过网关访问 consumer]URL: http://localhost:8764/consumer-sample/hi?name=hongxi响应: Hi, hongxi! I am from provider.HTTP Status: 200
==================================
💡 最佳实践总结
1. 依赖管理
使用 BOM 统一管理版本，避免冲突：
<dependencyManagement><dependencies><dependency><groupId>org.springframework.cloud</groupId><artifactId>spring-cloud-dependencies</artifactId><version>${spring-cloud.version}</version><type>pom</type><scope>import</scope></dependency><dependency><groupId>com.alibaba.cloud</groupId><artifactId>spring-cloud-alibaba-dependencies</artifactId><version>${spring-cloud-alibaba.version}</version><type>pom</type><scope>import</scope></dependency></dependencies>
</dependencyManagement>
2. Gateway 直接访问 Dubbo Triple 服务
Triple协议会同时暴露http接口（基于Netty http），因此Gateway可以直接访问Dubbo服务。
无需同时引入 dubbo-registry-nacos 和 spring-cloud-starter-alibaba-nacos-discovery，统一使用 DEFAULT_GROUP 即可让 Gateway 发现 Dubbo 服务。
3. 链路追踪配置
Spring Boot 4.0 需注意：
- 使用
management.tracing.sampling.probability控制采样率 - Dubbo 需自定义 Filter 传播 trace context
- WebFlux 需启用 Reactor Hooks 桥接 MDC
4. 脚本防重复启动
通过 PID 文件 + 端口检测双重保障，避免重复启动导致资源浪费。
🔗 相关链接
- 📦 项目地址: https://github.com/javahongxi/spring-cloud-samples
- 📖 Spring Boot 4.0: https://spring.io/projects/spring-boot
- 🌐 Spring Cloud Alibaba: https://spring-cloud-alibaba.io
- 🔧 Apache Dubbo: https://dubbo.apache.org
- 📊 Nacos: https://nacos.io
- 🛡️ Sentinel: https://sentinelguard.io
🤝 贡献指南
欢迎提交 Issue 和 PR！如果你发现：
- 配置项过时或错误
- 有更好的实践方案
- 想添加新的组件示例（如 Seata、SkyWalking）
请随时参与贡献，让这个项目成为 Spring Cloud Alibaba 学习的最佳参考！
© hongxi.org | 以生产环境可参考为目标，打造完整的 Spring Cloud 示例项目
📝 结语
这个项目的核心价值在于：它不是简单的"Hello World"，而是真正考虑了生产环境的复杂性。从链路追踪到限流熔断，从响应式编程到消息驱动，每一个模块都经过精心设计，每一行配置都有实际意义。
如果你正在：
- 🎯 学习 Spring Cloud Alibaba
- 🚀 准备升级 Spring Boot 4.0
- 🏗️ 设计微服务架构
- 🔍 寻找生产级参考示例
那么这个项目绝对值得你 Star ⭐ 和深入研究！
立即体验：
git clone https://github.com/javahongxi/spring-cloud-samples.git
cd spring-cloud-samples
sh start-all.sh
让我们一起探索 Spring Cloud Alibaba 的无限可能！🚀