Spring Cloud Samples 大升级:AI 智能体 + gRPC + Seata 分布式事务,三大重磅模块来袭
Spring Boot 4.1 | Spring AI 2.0 | Spring gRPC | Seata 分布式事务 | MCP 协议
上一篇博文中,我们介绍了基于 Spring Boot 4.0 的 spring-cloud-samples 微服务示例项目,覆盖了 Gateway、Dubbo、Sentinel、Stream 等核心场景。
时隔数月,项目迎来了 三大重磅升级:
- 🤖 cloud-ai-sample —— 基于 Spring AI 2.0 的全功能 AI 示例,从聊天对话到 Tool Calling、ReAct Agent、MCP Server,一站打通
- 🔌 cloud-grpc-server/client-sample + cloud-commons —— 基于 Spring Boot 原生 gRPC 支持,实现高性能 RPC 通信 + Nacos 服务发现(NameResolver SPI 桥接 DiscoveryClient)
- 🔄 cloud-seata-sample —— 完整的 Seata AT 模式分布式事务示例,四服务联动,随机故障模拟验证数据一致性
下面逐一详解。
🤖 模块一:cloud-ai-sample —— Spring AI 2.0 全场景实战
为什么要加 AI 模块?
2025 年,AI 能力已成为应用开发的标配。Spring AI 2.0 的发布,让 Java 开发者终于有了原生的、类型安全的 AI 集成方案。但现实是:
- 官方文档以单点示例为主,缺乏完整的端到端项目
- Spring AI 2.0 相比 1.x 有大量 API 变更(
@Tool替代@AiFunction,ChatClient.Builder模式重构) - Tool Calling、ReAct Agent、MCP Server 等高级特性几乎没有中文实战参考
cloud-ai-sample 正是为解决这些问题而设计。
技术栈
| 组件 | 版本 |
|---|---|
| Spring Boot | 4.1.0 |
| Spring AI | 2.0.0 |
| 模型提供商 | 千问(兼容 OpenAI API) |
| 默认模型 | qwen-plus |
功能全景
1️⃣ 基础聊天 —— 三种模式一步到位
# 简单对话
curl "http://localhost:8080/ai/chat?message=你好"
# 流式输出(SSE)
curl "http://localhost:8080/ai/chat/stream?message=讲一个故事"
# 结构化输出 —— AI 自动提取为 Java 对象
curl "http://localhost:8080/ai/extract?text=张三今年25岁,是一名软件工程师,邮箱zhangsan@example.com"
结构化输出直接返回 JSON:
{
"name": "张三",
"age": 25,
"email": "zhangsan@example.com",
"occupation": "软件工程师"
}
核心代码仅一行 —— 通过 entity() 方法将 AI 响应直接映射为 Java record:
return chatClient.prompt(new Prompt(prompt))
.call()
.entity(PersonInfo.class);
2️⃣ 高级对话 —— System Message、Few-shot、多轮对话
# System Message:让 AI 扮演资深架构师
curl -X POST "http://localhost:8080/ai/advanced/system-message?message=如何设计高并发秒杀系统?"
# Few-shot:给 AI 示例引导输出格式
curl -X POST "http://localhost:8080/ai/advanced/few-shot?message=创建一个Map"
# 多轮对话:传入历史消息维护上下文
curl -X POST "http://localhost:8080/ai/advanced/conversation?currentMessage=你还记得我说了什么吗?"
3️⃣ 多模态图像处理 —— 6 大场景
⚠️ 需将 model 改为支持多模态的模型(如
qwen3.7-plus)
# 图片 URL 分析
curl -X POST "http://localhost:8080/ai/vision/analyze-url" -d "imageUrl=https://..."
# 上传图片分析
curl -X POST -F "file=@/path/to/image.jpg" "http://localhost:8080/ai/vision/analyze-upload"
# OCR 文字识别
curl -X POST "http://localhost:8080/ai/vision/ocr" -d "imageUrl=https://..."
# 图表分析、代码截图转代码、多图对比...
4️⃣ Tool Calling —— AI 自动调用 Java 方法
这是 Spring AI 2.0 最核心的特性之一。通过 @Tool 注解定义工具,AI 会自动决定是否调用、传什么参数:
@Component
public class WeatherTools {
@Tool(description = "获取指定城市的当前天气信息")
public String getWeather(@ToolParam(description = "城市名称") String city) {
return switch (city) {
case "北京" -> "晴天,温度 25°C,空气质量良好,AQI 65";
case "上海" -> "多云,温度 28°C,湿度 65%,微风";
// ...
};
}
}
调用方式:
# AI 自动调用 WeatherTools
curl "http://localhost:8080/ai/tool/weather?question=北京今天的天气怎么样?"
# AI 自动调用 TimeTools
curl "http://localhost:8080/ai/tool/time?question=距离2027年春节还有多少天?"
# 智能助手 —— AI 自动选择合适的工具
curl "http://localhost:8080/ai/tool/ask?question=什么是Spring AI?"
项目内置 5 个工具类,覆盖天气、时间、搜索、数学运算、数据转换等场景:
| 工具类 | 工具方法 |
|---|---|
WeatherTools |
getWeather、getWeatherForecast |
TimeTools |
getCurrentTime、getCurrentDate、daysUntil |
SearchTools |
search、getLatestNews |
SystemTools |
add、multiply、toUpperCase、reverseString |
ConversionTools |
urlEncode、base64Encode、stringLength 等 |
5️⃣ ReAct Agent —— 推理 + 行动的智能体
ReAct(Reasoning + Acting)是当前最热门的 Agent 模式。AI 不只是回答问题,而是自主拆解任务、多步推理、组合调用多个工具:
# Agent 自主判断需要调用哪些工具
curl "http://localhost:8080/ai/agent/chat?question=北京今天天气怎么样?适合出门吗?"
# 复杂任务 —— Agent 拆解为多步子任务
curl "http://localhost:8080/ai/agent/complex-task?task=我想去杭州旅游,帮我查天气和著名景点"
核心代码展示了 Spring AI 2.0 的 .tools() API —— 将多个工具一次性注入,Agent 自行决定调用策略:
String response = chatClient.prompt()
.system("你是一个智能助手...")
.user(question)
.tools(weatherTools, timeTools, searchTools)
.call()
.content();
6️⃣ MCP Server —— AI Agent 互联的标准协议
如果说 Tool Calling 是「AI 调本地方法」,那么 MCP(Model Context Protocol) 就是「AI 调远程服务」。
本模块内置了 MCP Server,启动后通过 /sse 端点对外暴露所有 Tool 服务。任何 MCP Client(AI 助手、IDE 插件)都可以直接连接:
{
"mcpServers": {
"cloud-ai-mcp-server": {
"url": "http://localhost:8080/sse"
}
}
}
MCP Server 的配置极其简洁 —— 通过 MethodToolCallbackProvider 将 @Tool 标注的方法统一注册:
@Bean
public ToolCallbackProvider mcpToolProvider(
WeatherTools weatherTools, TimeTools timeTools,
SearchTools searchTools, SystemTools systemTools,
ConversionTools conversionTools) {
return MethodToolCallbackProvider.builder()
.toolObjects(weatherTools, timeTools, searchTools, systemTools, conversionTools)
.build();
}
一份工具代码,同时服务于内部 AI 调用和外部 MCP 暴露 —— 这就是 Spring AI 2.0 的优雅设计。
🔌 模块二:cloud-grpc-server/client-sample —— Spring 原生 gRPC + Nacos 服务发现
为什么用 gRPC?
在微服务架构中,HTTP REST 虽然通用,但在以下场景存在明显短板:
- 高性能:gRPC 基于 HTTP/2 + Protobuf,序列化效率和传输速度远超 JSON
- 强类型:通过
.proto文件定义接口,编译时生成代码,避免运行时错误 - 流式支持:原生支持双向流,适合实时推送、大文件传输等场景
Spring Boot 4.1 引入了 原生 gRPC 支持(spring-boot-starter-grpc-server / spring-boot-starter-grpc-client),不再需要第三方 starter,与 Spring Cloud 生态无缝集成。
架构设计
cloud-sample-api (proto 定义)
└── greeter.proto ──▶ GreeterGrpc / GreeterRequest / GreeterReply
cloud-commons (公共库)
└── DiscoveryClientNameResolverProvider ← 识别 discovery:/// scheme
└── DiscoveryClientNameResolver ← 调用 DiscoveryClient 解析实例
cloud-grpc-server-sample (:9090)
├── GreeterImpl (@GrpcService)
└── Nacos 注册为 grpc-server-sample(端口 9090)
cloud-grpc-client-sample (:8081)
├── @ImportGrpcClients 自动导入 Stub
├── nameResolverProvider Bean 注册到 gRPC 全局 NameResolverRegistry
└── discovery:///grpc-server-sample ──▶ Nacos 服务发现
Proto 定义
在 cloud-sample-api 模块中定义 gRPC 接口:
syntax = "proto3";
option java_multiple_files = true;
package org.hongxi.cloud.sample.idl.unary;
message GreeterRequest {
string name = 1;
}
message GreeterReply {
string message = 1;
}
service Greeter {
rpc greet(GreeterRequest) returns (GreeterReply);
}
Server 端 —— 一行注解搞定
@GrpcService
public class GreeterImpl extends GreeterGrpc.GreeterImplBase {
@Override
public void greet(GreeterRequest request, StreamObserver<GreeterReply> responseObserver) {
log.info("Received request: {}", request.getName());
responseObserver.onNext(
GreeterReply.newBuilder().setMessage("Hello, " + request.getName()).build());
responseObserver.onCompleted();
}
}
配置文件中指定 gRPC 端口和服务名,并通过 discovery.port 让 Nacos 注册 gRPC 端口而非 HTTP 端口:
server:
port: 8090
spring:
application:
name: grpc-server-sample
grpc:
server:
port: 9090
cloud:
nacos:
discovery:
server-addr: 127.0.0.1:8848
port: ${spring.grpc.server.port} # Nacos 注册 gRPC 端口
Client 端 —— 服务发现 + NameResolver 桥接
gRPC 原生通过 NameResolver SPI 解析服务地址,Spring Cloud 通过 DiscoveryClient 抽象注册中心。两者的桥接需要两个组件:
DiscoveryClientNameResolverProvider— 识别discovery:///schemeDiscoveryClientNameResolver— 调用DiscoveryClient.getInstances()获取实例
这两个类位于 cloud-commons 模块,Client 端只需注册 provider 并使用 stub:
/**
* gRPC 在 Spring Cloud 体系中的服务发现:
* discovery:///grpc-server-sample
* → NameResolverRegistry 查找 scheme="discovery" 的 Provider
* → DiscoveryClientNameResolver 调用 DiscoveryClient 获取实例
* → 构建 EquivalentAddressGroup 供 gRPC Channel 使用
*/
@SpringBootApplication
@ImportGrpcClients(basePackages = "org.hongxi.cloud.sample.idl.unary")
public class GrpcClientApplication {
/**
* 将 NameResolverProvider 注册到 gRPC 全局注册表。
* 必须确保 nameResolverProvider 先于 stub bean 实例化,
* 以保证 provider 在 stub 实例化前注册到 gRPC 全局 NameResolverRegistry。
*/
@Bean
DiscoveryClientNameResolverProvider nameResolverProvider(DiscoveryClient discoveryClient) {
var provider = new DiscoveryClientNameResolverProvider(discoveryClient);
NameResolverRegistry.getDefaultRegistry().register(provider);
return provider;
}
@Bean
public CommandLineRunner runner(GreeterGrpc.GreeterBlockingStub stub) {
return args -> {
log.info("{}", stub.greet(
GreeterRequest.newBuilder().setName("lily").build()));
};
}
}
时序说明:
nameResolverProvider必须先于 stub bean 实例化,以保证 provider 在 stub 实例化前注册到 gRPC 全局 NameResolverRegistry。
关键配置 —— 使用 discovery:/// 协议实现 Nacos 服务发现:
spring:
grpc:
client:
channel:
default:
target: discovery:///grpc-server-sample
核心亮点
- Spring Boot 原生支持:无需第三方
grpc-spring-boot-starter,官方 starter 更稳定 - Nacos 服务发现:gRPC Client 通过
discovery:///协议自动发现 Server,支持负载均衡 - NameResolver SPI 桥接:通过
DiscoveryClientNameResolver将 gRPC 的地址解析委托给 Spring CloudDiscoveryClient,可无缝切换 Eureka、Consul 等注册中心 - Proto 共享:接口定义放在
cloud-sample-api模块,Server 和 Client 共用同一份契约
🔄 模块三:cloud-seata-sample —— Seata AT 模式分布式事务
分布式事务的痛点
微服务架构下,一个业务操作可能跨越多个服务和数据库。当某个环节失败时,如何保证数据一致性?
Seata 提供了开箱即用的解决方案:
- AT 模式:无侵入的自动补偿,业务代码零改动
- TCC 模式:手动编写 Try/Confirm/Cancel,适合高一致性场景
- SAGA 模式:长事务编排,适合跨组织流程
本模块演示的是最常用的 AT 模式。
四服务联动架构
┌──────────────────┐
│ business-service │
│ (:18081) │
│ 业务入口(下单) │
└───────┬──────────┘
│
┌─────────────┼─────────────┐
▼ ▼
┌──────────────────┐ ┌──────────────────┐
│ storage-service │ │ order-service │
│ (:18082) │ │ (:18083) │
│ 扣减商品库存 │ │ 创建订单+调账户 │
└──────────────────┘ └────────┬─────────┘
│
▼
┌──────────────────┐
│ account-service │
│ (:18084) │
│ 扣减用户余额 │
└──────────────────┘
所有服务共享 Seata Server + Nacos + MySQL
业务流程
- 用户访问
business-service,发起下单请求 business-service调用storage-service扣减库存business-service调用order-service创建订单order-service调用account-service扣减用户余额- 任意环节随机抛出异常,验证 Seata 是否能正确回滚所有操作
快速体验
第一步:初始化数据库
在 MySQL 中创建 seata 数据库,执行项目中的 all.sql 脚本,自动创建:
- Seata 基础表:
undo_log、global_table、branch_table、lock_table、distributed_lock - 业务表:
storage_tbl、order_tbl、account_tbl
第二步:Nacos 配置
在 Nacos 中创建 seata.properties(Group: SEATA_GROUP):
service.vgroupMapping.default_tx_group=default
service.vgroupMapping.order-service-tx-group=default
service.vgroupMapping.account-service-tx-group=default
service.vgroupMapping.business-service-tx-group=default
service.vgroupMapping.storage-service-tx-group=default
第三步:启动四个服务,访问接口
# 通过 FeignClient 调用(触发分布式事务)
curl http://127.0.0.1:18081/seata/feign
# 通过 RestTemplate 调用
curl http://127.0.0.1:18081/seata/rest
验证数据一致性
核心看点:随机异常触发时,Seata 自动回滚所有已执行的操作。
1. Xid 传递 —— 各服务日志中输出的 Xid 应一致:
Storage Service Begin ... xid: 192.168.x.x:8091:xxxx
Order Service Begin ... xid: 192.168.x.x:8091:xxxx
Account Service ... xid: 192.168.x.x:8091:xxxx
2. 数据守恒 —— 无论执行多少次成功/失败,以下等式始终成立:
-- 用户余额:初始 10000 = 当前余额 + 已消费总额
SELECT * FROM account_tbl;
-- 库存数量:初始 100 = 当前库存 + 已扣减总额
SELECT * FROM storage_tbl;
-- 订单数量应与成功的消费次数匹配
SELECT * FROM order_tbl;
配置示例
每个服务的 application.yml 中只需添加 Seata 配置:
seata:
enabled: true
application-id: ${spring.application.name}
tx-service-group: ${spring.application.name}-tx-group
config:
type: nacos
nacos:
serverAddr: 127.0.0.1:8848
dataId: "seata.properties"
group: SEATA_GROUP
registry:
type: nacos
nacos:
cluster: default
group: SEATA_GROUP
application: seata-server
server-addr: 127.0.0.1:8848
📊 模块总览:14 个模块的全景图
升级后,项目模块从 10 个扩展到 14 个:
| 模块 | 端口 | 说明 | 状态 |
|---|---|---|---|
| cloud-gateway-sample | 8764 | Gateway + Sentinel 限流 | 原有 |
| cloud-provider-sample | 8765 | 传统 Web 服务提供者 | 原有 |
| cloud-consumer-sample | 8766 | 传统 Web 服务消费者 | 原有 |
| cloud-provider-reactive-sample | 8762 | 响应式 Web 服务提供者 | 原有 |
| 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 | - | 公共接口定义 + Proto 文件 | 原有 |
| cloud-ai-sample | 8080 | Spring AI 2.0 全场景示例 | 🆕 新增 |
| cloud-grpc-server-sample | 9090 | gRPC Server + Nacos 注册 | 🆕 新增 |
| cloud-grpc-client-sample | - | gRPC Client + 服务发现 | 🆕 新增 |
| cloud-seata-sample | 18081-84 | Seata 分布式事务(4 服务) | 🆕 新增 |
🎓 新增模块的学习价值
cloud-ai-sample
- ✅ Spring AI 2.0 ChatClient API 完整用法
- ✅
@Tool注解定义工具函数(替代旧版@AiFunction) - ✅ ReAct Agent 多步推理实战
- ✅ MCP Server 搭建与 Agent 互联
- ✅ 多模态图像处理 6 大场景
- ✅ 千问大模型接入(兼容 OpenAI API)
cloud-grpc-server/client-sample
- ✅ Spring Boot 4.1 原生 gRPC 支持
- ✅ Protobuf 接口定义与代码生成
- ✅
@GrpcService+@ImportGrpcClients极简配置 - ✅ gRPC + Nacos 服务发现集成
- ✅
discovery:///协议实现客户端负载均衡
cloud-seata-sample
- ✅ Seata AT 模式分布式事务完整链路
- ✅ 四服务联动:业务 → 库存 → 订单 → 账户
- ✅ 随机故障模拟验证回滚机制
- ✅ Seata + Nacos 配置中心集成
- ✅ Xid 跨服务传递验证
- ✅ FeignClient 和 RestTemplate 双调用方式
🚦 快速体验新模块
前置要求(新增)
- 千问 API Key(获取地址)—— AI 模块
- MySQL 5.7+ —— Seata 模块
- Seata Server —— Seata 模块
体验 AI 模块
# 设置 API Key
export OPENAI_API_KEY=your-api-key-here
# 启动
cd cloud-ai-sample
mvn spring-boot:run
# 测试聊天
curl "http://localhost:8080/ai/chat?message=你好"
# 测试 Tool Calling
curl "http://localhost:8080/ai/tool/weather?question=北京天气怎么样"
# 测试 ReAct Agent
curl "http://localhost:8080/ai/agent/chat?question=北京今天适合出门吗"
体验 gRPC 模块
# 先启动 Server
cd cloud-grpc-server-sample
mvn spring-boot:run
# 再启动 Client(自动调用并打印结果)
cd cloud-grpc-client-sample
mvn spring-boot:run
# 日志输出:message: "Hello, lily"
体验 Seata 模块
# 1. 初始化 MySQL 数据库(执行 all.sql)
# 2. 配置 Nacos(seata.properties)
# 3. 启动 Seata Server
# 4. 依次启动四个服务
# 5. 访问测试
curl http://127.0.0.1:18081/seata/feign
curl http://127.0.0.1:18081/seata/rest
💡 最佳实践总结
1. Spring AI 2.0 的关键变更
从 1.x 升级到 2.0 需注意:
@AiFunction→@Tool(注解更名)ChatClient构建方式统一为ChatClient.Builderbase-url需带/v1后缀- MCP Server 配置通过
spring.ai.mcp.server完成
2. gRPC 与 Spring Cloud 共存
gRPC Server 同时暴露 HTTP(用于 Nacos 健康检查)和 gRPC 端口:
server:
port: 8090 # HTTP 端口(Nacos 注册用)
spring:
grpc:
server:
port: 9090 # gRPC 端口(业务通信用)
3. Seata 的版本兼容
当前 Seata Server 二进制包自带的 nacos-client 版本较低(1.4.6),建议使用源码构建方式启动 Seata Server,确保 Nacos Client 版本与服务端一致。
4. 工具类复用设计
AI 模块中的 Tool 类(如 WeatherTools)采用一份代码、双重用途的设计:
- 内部:通过
@Tool注解被 AI ChatClient 调用 - 外部:通过
MethodToolCallbackProvider注册到 MCP Server 暴露给外部 Client
🔗 相关链接
- 📦 项目地址: https://github.com/javahongxi/spring-cloud-samples
- 🤖 Spring AI: https://spring.io/projects/spring-ai
- 🔌 Spring gRPC: https://spring.io/projects/spring-grpc
- 🔄 Apache Seata: https://seata.apache.org
- 🌐 MCP 协议: https://modelcontextprotocol.io
- 🧠 千问 DashScope: https://dashscope.console.aliyun.com
📝 结语
从最初的 10 个模块到如今的 14 个,spring-cloud-samples 始终围绕一个目标:提供生产环境可参考的微服务全栈示例。
本次新增的三大模块,分别对应了当前微服务领域最热门的三个方向:
- AI 集成 —— 不是 Demo 级别的"Hello World",而是覆盖 Tool Calling、ReAct Agent、MCP Server 的完整方案
- gRPC 通信 —— Spring Boot 原生支持,告别第三方 starter 的兼容性焦虑
- 分布式事务 —— 四服务联动 + 随机故障注入,真正验证 Seata 的数据一致性能力
如果你正在:
- 🤖 探索 Spring AI 2.0 的最佳实践
- 🔌 评估 gRPC 替代 REST 的可行性
- 🔄 解决微服务间的数据一致性问题
- 📚 寻找一站式 Spring Cloud 学习项目
Star ⭐ 这个项目,三大模块即刻上手!
git clone https://github.com/javahongxi/spring-cloud-samples.git
cd spring-cloud-samples
© hongxi.org | 以生产环境可参考为目标,持续打造最完整的 Spring Cloud 示例项目
更多推荐


所有评论(0)