基于 Spring Boot 4.x + Spring Cloud Alibaba 2025.1.x，从服务注册到分布式事务，从 AI Agent 到一键演示，打造最完整的 Spring Cloud 示例项目。

为什么要做这个项目？

Spring Cloud 生态组件繁多，官方示例往往只覆盖单一功能点，缺乏一个端到端、可直接运行、面向生产环境的整合项目。开发者在学习时经常遇到这些问题：

  • 看了一堆文档，不知道怎么串起来
  • 示例代码太简单，无法参考到生产级实践
  • 环境搭建复杂，跑通一个 Demo 要花半天

这个项目试图解决这些问题：16 个模块、覆盖 10+ 核心组件、提供一键演示脚本，从 clone 到跑通，最快 30 秒。

技术全景

领域组件模块
注册中心 & 配置中心Nacos 3.xnacos-discovery / nacos-config
API 网关Spring Cloud Gatewaygateway
服务调用（Web）OpenFeign + LoadBalancerconsumer / provider
服务调用（Reactive）WebFlux + Reactive LoadBalancerconsumer-reactive / provider-reactive
RPC 通信Apache Dubbo 3.3 Triple 协议provider-dubbo / consumer-dubbo
RPC 通信gRPC + 服务发现桥接grpc-server / grpc-client
流量防护Sentinel（Gateway + Feign + Dubbo）gateway / consumer
消息驱动Spring Cloud Stream + RocketMQstream
分布式事务Apache Seata（AT 模式）seata（4 个业务服务）
AI 集成Spring AI 2.0（DashScope + DeepSeek）ai
可观测性Micrometer Tracing（采样率 100%）全模块
AI 辅助运维Qoder Agent Skill 一键演示SKILL.md

亮点一：gRPC 服务发现——桥接 Spring Cloud 与 gRPC 两套体系

gRPC 有自己原生的服务发现机制（DNS / 静态地址列表），而 Spring Cloud 生态使用 Nacos / Eureka 等注册中心。两者天然不兼容。

本项目在 cloud-commons 中实现了一个 gRPC NameResolver SPI 扩展，通过 discovery:// scheme 将 gRPC 客户端的服务发现请求桥接到 Spring Cloud DiscoveryClient：

// gRPC 客户端 target 配置
spring:
  grpc:
    client:
      channel:
        default:
          target: discovery:///grpc-server-sample  // 逻辑服务名

DiscoveryClientNameResolverProvider（priority=6，高于 DNS 的 5）拦截 discovery:// scheme，创建 DiscoveryClientNameResolver，从 Nacos 获取实例列表并转换为 gRPC 的 EquivalentAddressGroup，支持实例变更检测与自动刷新。

这意味着：gRPC 服务可以像 Feign 调用一样，通过注册中心自动发现后端实例，无需额外部署 Consul DNS 或修改 gRPC 源码。

亮点二：Dubbo Triple 协议 + REST 双栈

provider-dubbo 模块同时暴露 Dubbo Triple（基于 HTTP/2 + Protobuf）和 Dubbo REST 接口，展示 Dubbo 3.3 的全能力：

  • Triple 协议：高性能 RPC，Consumer 通过 Nacos 自动发现
  • Dubbo REST：标准 HTTP 接口，可直接 curl 访问，也可通过 Gateway 路由
  • Tracing 集成：dubbo.tracing.enabled=true，Dubbo 调用链路自动纳入全链路追踪
# Dubbo REST 接口直接访问
curl http://localhost:50051/api/hello/lily
# 通过 Gateway 路由访问
curl http://localhost:8764/provider-dubbo-sample/api/hello/lily

亮点三：Nacos 动态配置——三种绑定方式全覆盖

nacos-config 模块完整演示了 Nacos 配置中心的三种使用方式：

1. @NacosConfig 注解注入——最简洁

@NacosConfig(dataId = "github.username", group = "DEFAULT_GROUP")
private String name;

@NacosConfigListener(dataId = "github.username", group = "DEFAULT_GROUP")
public void updated(String name) {
    log.info("配置已更新: {}", name);
}

2. @ConfigurationProperties Bean 绑定——类型安全，适合复杂配置

@ConfigurationProperties(prefix = "cloud.agent")
@Component
public class AgentProperties {
    private String name;
    private String version;
    private Provider provider = new Provider();
    // ...
}

3. @Value + @RefreshScope——单属性注入，动态刷新

三种方式均支持配置修改后无需重启服务即可生效，通过验证脚本可一键演示发布→读取→修改→刷新的完整流程。

亮点四：Sentinel 网关限流——Nacos 动态规则

Gateway 模块集成 Sentinel，限流规则存储在 Nacos 中，支持动态修改实时生效：

  • API 分组：按路径前缀定义 API 组（如 /consumer-sample/**）
  • 流控规则：对 API 组或后端服务设置 QPS 阈值
  • 降级规则：Consumer 模块同时演示了熔断降级

规则通过 Nacos 数据源（SENTINEL_GROUP）推送，修改后秒级生效，无需重启 Gateway。

亮点五：Spring AI 2.0——从对话到 Agent 到多模态

ai 模块基于 Spring AI 2.0 构建了一个完整的 AI 应用，覆盖当前最热门的 AI 工程化能力：

基础能力

  • 简单聊天、流式输出（SSE）、结构化输出（Bean 提取）

高级对话

  • System Message：设定 AI 角色（如"你是一个微服务架构师"）
  • Few-shot Prompting：提供示例引导 AI 输出格式
  • 多轮对话：连续发送，AI 记住上下文
  • 温度参数：控制创意性输出

Tool Calling & ReAct Agent

AI 可以自主决定调用哪些工具：

chatClient.prompt()
    .system("你是一个智能助手...")
    .user(message)
    .tools(weatherTools, timeTools, searchTools)
    .call()
    .content();

支持天气查询、时间查询、知识搜索等工具，Agent 会根据问题自动选择合适的工具组合。

MCP Server

通过 SSE 端点暴露工具能力，支持跨进程 Agent 通信（Model Context Protocol）。

多模态视觉识别

6 个视觉接口：URL 图片分析、图片上传分析、OCR 文字识别、图表分析、代码截图转代码、多图片对比。

多提供商集成

同一模块内集成 DashScope（通义千问）+ DeepSeek 两个提供商，演示 Spring AI 的多模型管理能力。

亮点六：Seata 分布式事务——4 服务完整链路

seata-sample 包含 4 个微服务（business → order → storage + account），演示 AT 模式下的分布式事务：

  • 全局事务回滚：库存不足时，订单和账户操作全部回滚
  • 全局事务提交：所有操作成功，数据一致
  • Xid 传递：通过 Feign Header 传递分布式事务 ID
  • 数据一致性验证：验证前后各服务数据余额不变

所有配置通过 Nacos 管理（SEATA_GROUP），Seata Server 注册到 Nacos 实现高可用。

亮点七：全链路可观测性

所有模块统一配置 Micrometer Tracing：

management:
  tracing:
    sampling:
      probability: 1.0  # 100% 采样
  endpoints:
    web:
      exposure:
        include: health,info

覆盖 Web、Reactive、Dubbo、gRPC、Gateway 所有调用链路，任何一次请求的完整 Trace 都可追踪。

亮点八：AI Skill 一键演示——告诉 AI “演示项目”

这是本项目最独特的设计：内置 Qoder Agent Skill，AI 助手可以自动完成环境检查、服务启动、接口验证全流程。

30 秒快速体验

告诉 AI: "演示本项目"

AI 自动执行：检查 Nacos → 安装依赖 → 打包模块 → 启动 16 个服务 → 执行验证 → 汇总结果。

深度验证

告诉 AI: "验证 Seata 分布式事务"
告诉 AI: "演示 Nacos 动态配置"
告诉 AI: "演示 Spring AI"

AI 会执行对应的深度验证脚本（verify-nacos-config.sh / verify-sentinel-gateway.sh / verify-stream.sh / verify-seata.sh），覆盖配置动态刷新、限流效果、消息收发、事务回滚等场景。

三种演示方式

方式说明适用场景
AI Skill告诉 AI “演示项目”，全自动快速体验、集成测试
一键脚本sh start-all.sh，命令行自动化CI/CD、批量验证
手动启动逐个模块 mvnw spring-boot:run学习调试

项目架构

                          ┌─────────────┐
                          │   Nacos     │
                          │  注册/配置   │
                          └──────┬──────┘
                                 │
    ┌────────────────────────────┼────────────────────────────┐
    │                            │                            │
    │    ┌───────────┐    ┌──────┴──────┐    ┌───────────┐   │
    │    │  Gateway   │    │  Sentinel   │    │   Seata   │   │
    │    │   (8764)   │    │   限流规则   │    │  Server   │   │
    │    └─────┬─────┘    └─────────────┘    └─────┬─────┘   │
    │          │                                     │         │
    │    ┌─────┴──────────────────┐                  │         │
    │    │                        │                  │         │
┌───┴───┴────┐  ┌────────┐  ┌────┴─────┐  ┌───────┴──────┐  │
│ Consumer   │  │Consumer│  │ Provider │  │   Seata 4    │  │
│ (8766)     │  │Reactive│  │  (8765)  │  │  微服务集群   │  │
│ Web/Dubbo  │  │ (8763) │  │  Web     │  │ 18081-18084  │  │
│ /gRPC      │  │        │  │          │  │              │  │
└─────┬──────┘  └───┬────┘  └──────────┘  └──────────────┘  │
      │              │                                        │
      │         ┌────┴─────┐  ┌──────────┐  ┌──────────┐    │
      │         │ Provider │  │  Dubbo   │  │  gRPC    │    │
      │         │ Reactive │  │ Provider │  │  Server  │    │
      │         │  (8762)  │  │ (50051)  │  │  (9090)  │    │
      │         └──────────┘  └──────────┘  └──────────┘    │
      │                                                       │
  ┌───┴────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐      │
  │  AI    │  │  Stream  │  │  Nacos   │  │  gRPC    │      │
  │ (8888) │  │  (8767)  │  │  Config  │  │  Client  │      │
  │SpringAI│  │ RocketMQ │  │  (8761)  │  │          │      │
  └────────┘  └──────────┘  └──────────┘  └──────────┘      │
                                                              │
                                              ┌──────────┐   │
                                              │ Commons  │   │
                                              │ gRPC发现 │   │
                                              └──────────┘   │

模块速查表

模块端口一句话说明
cloud-nacos-discovery-sample8760服务注册与发现
cloud-gateway-sample8764API 网关 + Sentinel 限流
cloud-provider-sample8765Web 服务提供者
cloud-provider-reactive-sample8762Reactive Web 提供者
cloud-provider-dubbo-sample50051Dubbo Triple + REST
cloud-consumer-sample8766Web 消费者（Feign/Dubbo/gRPC）
cloud-consumer-reactive-sample8763Reactive 消费者
cloud-consumer-dubbo-sample-纯 Dubbo 消费者
cloud-grpc-server-sample9090gRPC 服务端
cloud-grpc-client-sample-gRPC 客户端（服务发现桥接）
cloud-nacos-config-sample8761Nacos 动态配置
cloud-stream-sample8767Spring Cloud Stream + RocketMQ
cloud-ai-sample8888Spring AI（对话/Agent/视觉/MCP）
cloud-seata-sample18081-18084Seata 分布式事务（4 服务）
cloud-sample-api-公共接口 & Proto 定义
cloud-commons-gRPC 服务发现桥接

快速开始

# 1. Clone 项目
git clone https://github.com/javahongxi/spring-cloud-samples.git
cd spring-cloud-samples

# 2. 确保 Nacos 已运行（没有？告诉 AI "安装 Nacos"）

# 3. 告诉 AI "演示本项目"
# 或者手动启动：
sh start-all.sh

版本信息

组件版本
Spring Boot4.1.0
Spring Cloud2025.1.2
Spring Cloud Alibaba2025.1.0.0
Spring AI2.0.0
Nacos Client3.2.2
Apache Dubbo3.3.6

总结

这不是一个简单的 Demo 集合，而是一个面向生产环境的微服务参考架构：

  • 全：16 个模块覆盖 Spring Cloud 生态所有核心组件
  • 深：不止于 Hello World，每个模块都有深度验证（动态配置刷新、限流效果、事务回滚、AI Agent 多步推理）
  • 新：Spring Boot 4.x + Spring AI 2.0 + Dubbo 3.3 Triple + gRPC 服务发现桥接
  • 快：AI Skill 一键演示，30 秒跑通全流程
  • 实：以生产环境可参考为目标，配置规范、端口统一、日志可追踪

项目地址：https://github.com/javahongxi/spring-cloud-samples

© hongxi.org

# 微服务 # 架构 # spring cloud
Logo
亚马逊云科技技术品牌专区

更多推荐

open-code-review Codex 插件教程：对话式调用评审技能指南

本文是一份面向新手的 **open-code-review Codex 插件教程**，教你在 Codex 中通过对话式方式调用 open-code-review 的 AI 代码评审技能。open-code-review 是阿里巴巴开源的 AI 代码评审工具，采用"确定性流水线 + LLM Agent"混合架构，内置多语言评审规则（NPE、线程安全、XSS、SQL 注入等），可在 Codex 里用一

avatar 亚马逊云科技技术品牌专区

OBS Studio 完整指南：免费开源录屏与直播软件从零上手

想做一场像模像样的直播，或者把屏幕内容录成教程视频，但一想到商用软件的订阅费就有些犹豫？其实你不需要花一分钱。OBS Studio 是一款免费开源的直播与录屏软件，支持 Windows、macOS 和 Linux，采集、混音、编码、推流、录制，一条流水线全包了。## 先搞清楚 OBS Studio 是什么OBS Studio 是一个"场景化"的采集合成工具：你把摄像头、窗口、浏览器、图片、

avatar 亚马逊云科技技术品牌专区

如何用MediaCrawler爬取小红书抖音数据？7大平台爬虫从安装到实战完整指南

MediaCrawler 是一个支持小红书、抖音、快手、B站、微博、百度贴吧、知乎的开源自媒体数据采集工具。它能按关键词、按帖子、按创作者主页三种方式抓取笔记/视频内容、评论甚至二级评论，并把结果存成 JSON、CSV、Excel 或数据库。适合做市场调研、竞品监控、内容选题的运营人员，以及想要现成爬虫框架而不想从零写 JS 逆向的开发者。## 从一次"手动抄数据"说起想象这个场景：你负责

avatar 亚马逊云科技技术品牌专区