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 替代 @AiFunctionChatClient.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 getWeathergetWeatherForecast
TimeTools getCurrentTimegetCurrentDatedaysUntil
SearchTools searchgetLatestNews
SystemTools addmultiplytoUpperCasereverseString
ConversionTools urlEncodebase64EncodestringLength
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:/// scheme
  • DiscoveryClientNameResolver — 调用 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 Cloud DiscoveryClient,可无缝切换 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

业务流程

  1. 用户访问 business-service,发起下单请求
  2. business-service 调用 storage-service 扣减库存
  3. business-service 调用 order-service 创建订单
  4. order-service 调用 account-service 扣减用户余额
  5. 任意环节随机抛出异常,验证 Seata 是否能正确回滚所有操作

快速体验

第一步:初始化数据库

在 MySQL 中创建 seata 数据库,执行项目中的 all.sql 脚本,自动创建:

  • Seata 基础表:undo_logglobal_tablebranch_tablelock_tabledistributed_lock
  • 业务表:storage_tblorder_tblaccount_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.Builder
  • base-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

🔗 相关链接


📝 结语

从最初的 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 示例项目

Logo

这里是“一人公司”的成长家园。我们提供从产品曝光、技术变现到法律财税的全栈内容,并连接云服务、办公空间等稀缺资源,助你专注创造,无忧运营。

更多推荐