Spring AI 2.0.0 新特性详解：Java AI 工程化的关键一步，以及 MateCloud 如何落地

项目地址：GitHub ｜ Gitee ｜ 官网

一、为什么 Spring AI 2.0.0 值得 Java 开发者重点关注

过去一年，AI 应用开发经历了一个很明显的变化：从“调用一个大模型接口”，走向“让模型能够操作业务系统”。

早期 AI 应用通常停留在这几类能力：

• 调用 Chat Completion，返回一段文本；
• 接一个向量库，做一个知识库问答；
• 写几个 prompt 模板，完成摘要、翻译、分类；
• 在页面上加一个聊天窗口。

这些当然有价值，但它们还不能真正改变企业应用的工程结构。原因很简单：企业系统的核心不是聊天，而是权限、数据、流程、审计、治理、观测、部署和演进。AI 如果只能回答问题，却不能以受控方式调用业务能力，它就仍然是一个外部助手，而不是系统的一部分。

Spring AI 2.0.0 的重要性就在这里。它把 AI 能力纳入 Spring 开发者熟悉的工程范式：

• 模型调用变成 ChatClient、ChatModel 等统一抽象；
• 业务方法可以通过 @Tool 暴露给模型调用；
• 会话上下文可以通过 ChatMemory 和 Advisor 管理；
• 安全、日志、记忆、拦截、观测可以作为链路能力组合；
• MCP 让 Spring 应用既可以消费外部工具，也可以把自己的能力暴露给外部 Agent；
• 结构化输出让模型结果可以回到 Java 类型系统；
• 可观测性让 token、调用耗时、工具执行、模型交互进入企业监控体系。

换句话说，Spring AI 2.0.0 的关键词不是“更方便调模型”，而是：把 AI 应用变成可工程化、可组合、可治理的 Spring 应用。

上图是 Spring 官方博客在 2026 年 6 月 12 日发布的 Spring AI 2.0.0 GA 页面截图。官方发布说明里强调了新的基础能力，包括 Spring Boot 4 / 4.1 与 Spring Framework 7 基线、Jackson 3、空安全标注、工具调用增强、MCP 和可观测性等方向。

微信公众号中文标注建议：

• 标题 Spring AI 2.0.0 GA Available Now：表示 Spring AI 2.0.0 已正式发布，不再只是里程碑或预览版本。
• Improved foundations：这次重点不是单点功能堆叠，而是重做基础能力，让后续 AI 应用更稳定、更一致。
• Spring Boot 4 baseline：Spring AI 2.0 面向 Spring Boot 4 / Spring Framework 7 新基线，适合 Java 21 与新一代 Spring 项目。
• Jackson 3 / Null-safety：底层序列化和空安全能力升级，对工具调用参数、结构化输出和复杂对象映射都有影响。

为了把这件事讲清楚，可以先看一张能力地图。

二、Spring AI 2.0.0 的核心变化：从模型 API 到 AI 工程抽象

1. Spring Boot 4 与 Spring Framework 7 基线

Spring AI 2.0.0 面向 Spring Boot 4 / 4.1 与 Spring Framework 7 设计。这意味着它不只是跟随 Spring 生态升级版本号，而是进入了新的 Spring 应用基线：

• Java 21 更适合作为企业后端长期运行时；
• Spring Boot 4 带来新的自动配置、依赖管理和生态基线；
• Spring Framework 7 强化空安全、AOT、现代 Java 语言特性的支持；
• Jackson 3 成为新一代 JSON 序列化基础；
• 企业系统可以把 AI 能力和主业务应用放在同一个技术栈上演进。

对于 Java 团队来说，这一点非常关键。AI 不是一个“旁路 Python 服务”就能解决全部问题的场景。企业系统里的数据、权限、流程、审计、服务治理，大量都已经沉淀在 Java / Spring 体系里。如果 AI 要进入生产系统，最自然的方式不是绕开这些能力，而是把 AI 能力纳入原有工程体系。

2. ChatClient：把模型调用收敛为 Spring 风格客户端

Spring AI 的 ChatClient 类似 AI 应用里的核心入口。开发者不用在业务代码里直接拼 HTTP 请求，也不用把不同模型厂商的 SDK 细节泄漏到业务层。

在 MateCloud 5.0.8 中，mate-ai-starter 基于 ChatClient.Builder 统一构建对话客户端：

public class AiChatService {

    private final ChatClient chatClient;
    private final AiProperties properties;

    public AiChatService(ChatClient.Builder chatClientBuilder,
                         AiToolRegistry toolRegistry,
                         ChatMemory chatMemory,
                         AiProperties properties) {
        this.properties = properties;

        List<Advisor> advisors = new ArrayList<>();
        advisors.add(MessageChatMemoryAdvisor.builder(chatMemory).build());

        if (properties.isAdvisorLoggingEnabled()) {
            advisors.add(new SimpleLoggerAdvisor());
        }

        if (properties.getSafeGuardWords() != null
                && !properties.getSafeGuardWords().isEmpty()) {
            advisors.add(SafeGuardAdvisor.builder()
                    .sensitiveWords(properties.getSafeGuardWords())
                    .build());
        }

        this.chatClient = chatClientBuilder
                .defaultSystem(properties.getSystemPrompt())
                .defaultAdvisors(advisors.toArray(new Advisor[0]))
                .defaultToolCallbacks(toolRegistry)
                .build();
    }
}

这段代码背后有几个工程含义：

• 模型提供商由 Spring AI 自动配置，不进入业务控制器；
• 系统提示词、记忆、日志、安全拦截、工具列表都在 ChatClient 构建阶段统一挂载；
• 业务侧只需要调用 chat()、stream()、entity() 这类高层方法；
• 后续更换模型、增加 Advisor、扩展工具注册，不需要重写每个业务接口。

这就是 Spring 风格的价值：把变化收敛在配置、Starter 和 Bean 生命周期里，而不是散落在业务代码中。

3. 同步对话、流式对话与结构化输出

AI 应用一般至少需要三类调用方式：

• 普通阻塞式问答：适合后台任务、分类、摘要、提取；
• 流式输出：适合聊天界面、长文本生成、代码生成；
• 结构化输出：适合把模型结果变成 Java 对象，进入业务流程。

MateCloud 的 AiChatService 对这三类调用做了简单封装：

public String chat(String conversationId, String systemPrompt, String userMessage) {
    ChatClient.ChatClientRequestSpec spec = chatClient.prompt()
            .advisors(a -> a.param(
                    ChatMemory.CONVERSATION_ID,
                    resolveConversationId(conversationId)
            ));

    if (systemPrompt != null && !systemPrompt.isBlank()) {
        spec = spec.system(systemPrompt);
    }

    return spec.user(userMessage).call().content();
}

public Flux<String> stream(String conversationId, String systemPrompt, String userMessage) {
    ChatClient.ChatClientRequestSpec spec = chatClient.prompt()
            .advisors(a -> a.param(
                    ChatMemory.CONVERSATION_ID,
                    resolveConversationId(conversationId)
            ));

    if (systemPrompt != null && !systemPrompt.isBlank()) {
        spec = spec.system(systemPrompt);
    }

    return spec.user(userMessage).stream().content();
}

public <T> T entity(String conversationId,
                    String systemPrompt,
                    String userMessage,
                    Class<T> type) {
    ChatClient.ChatClientRequestSpec spec = chatClient.prompt()
            .advisors(a -> a.param(
                    ChatMemory.CONVERSATION_ID,
                    resolveConversationId(conversationId)
            ));

    if (systemPrompt != null && !systemPrompt.isBlank()) {
        spec = spec.system(systemPrompt);
    }

    return spec.user(userMessage).call().entity(type);
}

如果要把模型输出变成一个风控判断对象，可以这样写：

public record RiskLevel(
        String level,
        String reason,
        List<String> actions
) {}

RiskLevel risk = aiChatService.entity(
        "risk-001",
        "你是企业风控助手，请给出结构化判断。",
        "分析这条订单是否异常：用户 10 分钟内连续下单 25 次，收货地址分散。",
        RiskLevel.class
);

这类结构化输出非常适合企业系统，因为业务流程不能长期依赖一段自然语言。系统需要的是明确字段：

• 风险等级是什么；
• 判断依据是什么；
• 后续动作是什么；
• 是否需要人工审核；
• 是否可以自动触发流程。

4. REST 与 SSE：让 AI 能力成为普通业务接口

MateCloud 没有把 AI 能力做成孤立 demo，而是通过标准 REST/SSE 接口暴露：

@RestController
@RequestMapping("/api/v1/ai/chat")
@RequiredArgsConstructor
public class AiChatController {

    private final AiChatService aiChatService;
    private final AiProperties properties;

    @PostMapping
    public Result<String> chat(@RequestBody ChatRequest request) {
        String sys = resolveSystem(request.getSystem());
        String reply = aiChatService.chat(
                request.getConversationId(),
                sys,
                request.getMessage()
        );
        return Result.ok(reply);
    }

    @PostMapping(value = "/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
    public Flux<String> stream(@RequestBody ChatRequest request) {
        String sys = resolveSystem(request.getSystem());
        return aiChatService.stream(
                request.getConversationId(),
                sys,
                request.getMessage()
        );
    }
}

这看起来很朴素，但对工程落地很重要：

• 前端可以像调用普通业务接口一样调用 AI；
• 网关、鉴权、限流、日志、审计可以沿用原有体系；
• 流式接口可以直接用于聊天界面；
• 阻塞接口可以用于后台任务和业务编排；
• conversationId 可以把会话上下文和用户、租户、业务单据绑定起来。

三、Tool Calling：AI 不只回答问题，还能调用业务能力

Spring AI 2.0.0 里最值得关注的能力之一是 Tool Calling。

Tool Calling 的本质是：模型不直接访问数据库、不直接修改系统，而是由应用把一组可控的函数暴露给模型。模型在需要时发起工具调用请求，应用负责参数校验、权限控制、函数执行和结果返回。

微信公众号中文标注建议：

• Tool Calling：也叫 Function Calling，是让模型按规则调用外部 API 或业务方法的机制。
• Information Retrieval：信息检索型工具，例如查数据库、查文档、查天气、查业务记录。
• Taking Action：执行动作型工具，例如创建记录、提交表单、触发工作流、发起审批。
• Tool Specification / Tool Execution：工具不仅要有描述，还要有入参 schema、结果转换、执行策略和上下文治理。

可以把 Tool Calling 理解为 AI 与业务系统之间的一层受控边界：

1. 用 @Tool 暴露业务方法

在 Spring AI 中，一个普通 Spring Bean 方法可以通过 @Tool 暴露给模型：

@Component
@RequiredArgsConstructor
public class DictAiTools {

    private final IDictQueryService dictQueryService;

    @Tool(description = "List all dict entries for a given dictType.")
    public List<DictData> listDictByType(
            @ToolParam(description = "Dict type code, e.g. 'user_status'")
            String dictType) {
        return dictQueryService.findByType(dictType);
    }
}

这段代码的意义不是“让 AI 查字典”这么简单，而是展示了一种模式：

• 原有业务服务仍然由 Java 代码实现；
• AI 通过工具描述理解这个方法能做什么；
• 入参通过 schema 约束；
• 执行仍然发生在 Spring 应用内部；
• 权限、事务、日志、审计可以继续由原有工程体系承接。

2. MateCloud 的工具自动注册机制

如果每个工具都要手工注册，很快就会变成样板代码。MateCloud 的 AiToolRegistry 通过 Spring BeanPostProcessor 扫描所有 Bean，自动发现 @Tool 方法并注册为 Spring AI 的 ToolCallback：

@Slf4j
public class AiToolRegistry implements BeanPostProcessor, ToolCallbackProvider {

    private final Map<String, ToolCallback> callbacks = new ConcurrentHashMap<>();

    @Override
    public Object postProcessAfterInitialization(
            @NonNull Object bean,
            @NonNull String beanName) throws BeansException {

        Class<?> targetClass = ClassUtils.getUserClass(bean);

        ReflectionUtils.doWithMethods(targetClass, method -> {
            Tool toolAnnotation = AnnotationUtils.findAnnotation(method, Tool.class);
            if (toolAnnotation == null) {
                return;
            }
            register(bean, method);
        });

        return bean;
    }

    private void register(Object bean, Method method) {
        String toolName = ToolUtils.getToolName(method);
        if (callbacks.containsKey(toolName)) {
            log.warn("[mate-ai] Duplicate tool name ignored: {}", toolName);
            return;
        }

        method.setAccessible(true);

        ToolCallback callback = MethodToolCallback.builder()
                .toolDefinition(ToolDefinitions.from(method))
                .toolMethod(method)
                .toolObject(bean)
                .build();

        callbacks.put(toolName, callback);
        log.info("[mate-ai] Registered tool: {}", toolName);
    }

    @Override
    @NonNull
    public ToolCallback[] getToolCallbacks() {
        return callbacks.values().toArray(new ToolCallback[0]);
    }
}

这段实现有几个值得借鉴的点：

• 用 Spring Bean 生命周期自动完成工具注册；
• 用 ToolDefinitions.from(method) 从方法签名生成工具定义；
• 通过 ToolCallbackProvider 直接交给 ChatClient 使用；
• 避免每个业务模块都重复编写工具注册代码；
• 后续可以把工具清单暴露给管理端、CLI 或 MCP。

在 AI 原生应用里，工具注册表会变得越来越重要。它类似一个“AI 可调用能力目录”，记录系统有哪些动作可以被模型使用，以及每个动作的输入、输出、说明和治理规则。

四、Advisor：把记忆、安全、日志、治理放进同一条调用链

如果说 Tool Calling 解决的是“模型如何调用业务能力”，那么 Advisor 解决的是“模型调用前后如何被治理”。

企业 AI 应用通常需要在一次模型调用周围做很多事情：

• 注入系统提示词；
• 注入会话记忆；
• 增加用户、租户、业务上下文；
• 检查敏感词；
• 记录 prompt 与响应；
• 统计 token 和耗时；
• 在工具调用前做权限判断；
• 在输出后做内容检查。

Spring AI 的 Advisor 把这些能力组织成调用链。

MateCloud 中的默认 Advisor 链包括三类：

List<Advisor> advisors = new ArrayList<>();

advisors.add(MessageChatMemoryAdvisor.builder(chatMemory).build());

if (properties.isAdvisorLoggingEnabled()) {
    advisors.add(new SimpleLoggerAdvisor());
}

if (properties.getSafeGuardWords() != null
        && !properties.getSafeGuardWords().isEmpty()) {
    advisors.add(SafeGuardAdvisor.builder()
            .sensitiveWords(properties.getSafeGuardWords())
            .build());
}

this.chatClient = chatClientBuilder
        .defaultSystem(properties.getSystemPrompt())
        .defaultAdvisors(advisors.toArray(new Advisor[0]))
        .defaultToolCallbacks(toolRegistry)
        .build();

这条链路对应三类基础治理能力：

这也说明 AI 工程不是只关注 prompt。真正进入生产后，prompt 只是链路中的一环，前后还需要上下文、权限、工具、安全、日志和可观测性。

五、ChatMemory：从“单次问答”走向“业务上下文”

很多 AI demo 都是无状态的：用户问一句，模型答一句。企业系统不可能长期这样工作。

实际业务中，AI 需要知道：

• 当前用户是谁；
• 当前租户是谁；
• 当前业务单据是什么；
• 之前问过什么；
• 已经调用过哪些工具；
• 哪些信息已经确认；
• 哪些动作还需要人工审批。

MateCloud 在每次调用时传入 ChatMemory.CONVERSATION_ID：

ChatClient.ChatClientRequestSpec spec = chatClient.prompt()
        .advisors(a -> a.param(
                ChatMemory.CONVERSATION_ID,
                resolveConversationId(conversationId)
        ));

这个设计让会话记忆不只是聊天上下文，也可以变成业务上下文。例如：

conversationId = tenantId + ":" + userId + ":order:" + orderId

这样，一个订单处理助手可以围绕同一个订单持续工作，而不是每轮都重新解释背景。

在更完整的企业系统中，记忆还可以继续分层：

六、MCP：让 Spring 应用进入 Agent 工具生态

MCP，全称 Model Context Protocol，正在成为 Agent 与外部工具、资源、系统之间的重要连接方式。

Spring AI 2.0.0 对 MCP 的支持，让 Java 应用可以更自然地进入 Agent 生态：

• 作为 MCP Client，消费外部 MCP Server 暴露的能力；
• 作为 MCP Server，把 Spring 应用中的工具暴露给 Claude Code、Claude Desktop、Codex 或其他 Agent；
• 把原有 Java 微服务能力变成 AI Agent 可发现、可调用、可治理的工具。

中文标注建议：

• Model Context Protocol (MCP)：可以理解为 Agent 连接外部工具、资源和业务系统的一套标准协议。
• MCP Client：调用工具的一侧，例如 Claude Code、Claude Desktop、Codex 或企业内部 Agent。
• MCP Server：暴露工具的一侧，例如 MateCloud 的 mate-cli --mcp 或启用 Spring AI MCP Server 的业务服务。
• Transport：通信方式，例如 stdio、SSE、HTTP 等。企业内部常用 stdio 接本地工具，服务化场景更适合 HTTP/SSE。

MateCloud 对 MCP 的落地分两层。

第一层是 Spring AI MCP Server 方式，单个服务可以直接通过配置暴露工具：

spring:
  ai:
    mcp:
      server:
        enabled: true
        name: ${spring.application.name}

第二层是 MateCloud 自己的 mate-cli --mcp，它把 CLI 能力、服务发现能力和业务工具聚合成一个 stdio MCP Server：

java -jar mate-cli/target/mate-cli.jar --mcp

在 Claude Desktop 或 Claude Code 类工具中，可以配置为：

{
  "mcpServers": {
    "matecloud": {
      "command": "java",
      "args": [
        "-jar",
        "./mate-cli/target/mate-cli.jar",
        "--mcp"
      ],
      "env": {
        "NACOS_SERVER_ADDR": "127.0.0.1:8848",
        "NACOS_NAMESPACE": "dev"
      }
    }
  }
}

对应关系如下：

MateCloud 的 McpServerMode 当前支持 JSON-RPC 2.0 风格的 MCP 基础方法：

• initialize
• notifications/initialized
• tools/list
• tools/call
• ping

并提供了面向工程场景的工具，例如：

• db_describe：查看数据库表结构；
• db_query：执行只读 SQL 查询；
• service_list：查看 Nacos 中的服务列表。

这里有一个很重要的工程取舍：AI 不应该裸连数据库或集群。它应该通过 MCP Server 暴露的一组受控工具访问系统。这样才可以做权限、审计、限流和安全策略。

七、Observability：AI 调用必须进入监控体系

AI 应用进入生产后，最容易被低估的是可观测性。

传统接口主要关注：

• QPS；
• 延迟；
• 错误率；
• 日志；
• 链路追踪。

AI 调用还需要额外关注：

Spring AI 已经把 ChatClient、ChatModel、EmbeddingModel、VectorStore 等能力纳入可观测性设计。对企业项目来说，这意味着 AI 调用不应该游离在监控系统之外，而应该进入 Micrometer、OpenTelemetry、日志平台和审计系统。

更现实一点讲：当用户说“AI 昨天自动审批错了一笔订单”时，系统需要回答这些问题：

• 当时使用的是哪个模型；
• 输入 prompt 是什么；
• 注入了哪些上下文；
• 调用了哪些工具；
• 工具返回了什么；
• 是否经过安全或审批 Advisor；
• 最终输出是什么；
• 有没有人工确认；
• 这次调用成本是多少。

没有这些数据，AI 系统就很难进入生产闭环。

八、MateCloud：把 Spring AI 2.0.0 落到 Java 微服务底座

Spring AI 2.0.0 提供的是框架抽象。要真正落地，还需要一个完整工程底座。

MateCloud 5.0.8 的定位是 AI 原生、云原生的 DDD 微服务脚手架，基于：

它不是只提供一个 AI chat demo，而是把传统 Java 企业系统和 AI 原生能力放进同一套工程结构。

1. mate-ai-starter：把 AI 能力封装成 Starter

MateCloud 的 mate-ai-starter 做了几件事：

• 自动创建 AiToolRegistry；
• 自动创建 ChatMemory；
• 自动创建 AiChatService；
• 自动暴露 AI 对话接口；
• 支持 @Tool 自动发现；
• 支持多模型提供商；
• 支持 Spring AI MCP Server 桥接；
• 支持 Advisor 链路治理。

这符合 Spring Boot Starter 的设计习惯：业务模块只需要引入依赖并配置参数，就可以获得一组基础能力。

典型配置可以是：

spring:
  ai:
    model:
      chat: anthropic
    anthropic:
      api-key: ${ANTHROPIC_API_KEY}
      chat:
        options:
          model: claude-sonnet-4-20250514

mate:
  ai:
    enabled: true
    default-conversation-id: default
    advisor-logging-enabled: true
    max-memory-messages: 20
    system-prompt: >
      回答以中文为主，技术问题保持简洁准确；
      需要查询真实数据时优先调用可用的 @Tool。

如果换成 OpenAI、DeepSeek、Ollama 等模型，业务代码不应该感知太多变化。模型切换应主要发生在配置层和依赖层。

2. 单体与微服务双形态

AI 原生不意味着所有系统一开始就必须微服务化。很多团队更现实的路径是：

1. 本地或小团队先用单体方式跑通业务；
2. 当模块边界稳定后，再拆成微服务；
3. 需要服务治理时接入 Nacos、Dubbo、Gateway、Sentinel 等能力；
4. AI 工具调用和 MCP 能力在两种形态下都能延续。

MateCloud 5.0.8 提供 mate-monolith 单体组合根，同时保留微服务形态：

这对 AI 应用尤其重要。AI 能力引入后，系统复杂度会上升。如果项目一开始就同时处理模型、工具、微服务、网关、注册中心、权限、租户和前端，很容易失控。双形态架构让团队可以先在单体里验证 AI 业务闭环，再按需切换到微服务治理。

3. AI 工程闭环

MateCloud 对 AI 的定位不是“后台管理系统加一个聊天框”，而是把 AI 放进工程闭环：

这个闭环包括：

• 观察：通过 CLI、服务注册中心、数据库只读工具、业务接口获取系统状态；
• 推理：通过 Spring AI ChatClient 调用模型；
• 执行：通过 @Tool、MCP、REST、RPC 调用业务能力；
• 反馈：把工具结果、执行日志、审计数据返回给模型和系统；
• 治理：通过权限、安全、审批、日志、指标约束每次操作。

AI 真正进入企业系统，不是让模型“自由发挥”，而是让模型在工程约束内调用系统能力。

九、从 Java 微服务到 AI 原生系统：推荐落地路径

结合 Spring AI 2.0.0 和 MateCloud 的实现，一个 Java 团队可以按下面路径演进。

第一步：先统一模型调用入口

不要在各个业务模块里直接写模型厂商 SDK。建议先封装一层统一入口：

public interface EnterpriseAiClient {

    String chat(String conversationId, String message);

    Flux<String> stream(String conversationId, String message);

    <T> T extract(String conversationId, String message, Class<T> type);
}

底层可以用 Spring AI ChatClient 实现。这样业务代码依赖的是企业自己的 AI 能力接口，而不是具体模型厂商。

第二步：把只读查询先做成工具

Tool Calling 最好从低风险工具开始，例如：

• 查询用户信息；
• 查询订单状态；
• 查询字典配置；
• 查询库存；
• 查询服务列表；
• 查询数据库表结构。

示例：

@Component
@RequiredArgsConstructor
public class OrderAiTools {

    private final OrderQueryService orderQueryService;

    @Tool(description = "Query order summary by order number.")
    public OrderSummary queryOrder(
            @ToolParam(description = "Order number, e.g. SO202607020001")
            String orderNo) {
        return orderQueryService.findSummary(orderNo);
    }
}

先做只读工具有两个好处：

• 安全风险小；
• 可以快速验证模型是否能正确理解工具描述和参数。

第三步：再引入需要审批的写操作工具

写操作不能一开始就完全自动化。建议增加审批层：

@Tool(description = "Create a refund request. This tool only creates a pending approval record.")
public RefundRequest createRefundRequest(
        @ToolParam(description = "Order number") String orderNo,
        @ToolParam(description = "Refund amount") BigDecimal amount,
        @ToolParam(description = "Refund reason") String reason) {

    return refundService.createPendingRequest(orderNo, amount, reason);
}

注意这里工具不是直接退款，而是创建一个待审批请求。AI 负责整理信息和发起流程，人或规则引擎负责最终确认。

第四步：把 MCP 作为外部 Agent 的统一入口

如果团队已经使用 Claude Code、Codex、Cursor、内部 Agent 平台，就可以通过 MCP 暴露工程能力：

{
  "name": "service_list",
  "description": "List registered services from Nacos",
  "inputSchema": {
    "type": "object",
    "properties": {
      "namespace": {
        "type": "string",
        "description": "Nacos namespace"
      }
    }
  }
}

这类工具适合给研发 Agent 使用，例如：

• 查看当前有哪些服务；
• 查询服务实例；
• 读取数据库结构；
• 生成模块代码；
• 检查配置；
• 辅助排查环境问题。

但仍然要强调：MCP 工具必须受控，尤其是数据库、文件系统、部署、配置变更类工具。生产环境建议默认只读，写操作需要审批。

第五步：把 AI 调用纳入日志、指标和审计

建议至少记录这些字段：

public record AiAuditEvent(
        String traceId,
        String tenantId,
        String userId,
        String conversationId,
        String provider,
        String model,
        String toolName,
        Integer promptTokens,
        Integer completionTokens,
        Long latencyMs,
        String resultType,
        Boolean approved
) {}

这类数据后续可以进入：

• 日志平台；
• 链路追踪；
• 指标看板；
• 成本分析；
• 安全审计；
• 用户行为分析。

没有可观测性，AI 系统很难从 demo 进入生产。

十、MateCloud 后台截图：AI 原生仍然需要完整企业后台能力

AI 原生不是只做模型调用。一个完整企业系统仍然需要工作台、权限、灰度、租户、服务治理、身份接入等基础能力。

MateCloud 当前版本提供了可运行后台界面，下面几张截图来自项目运行素材。

这些能力和 AI 的关系并不割裂。恰恰相反，AI 要进入企业系统，必须和这些能力结合：

• 权限系统决定 AI 能不能调用某个工具；
• 租户系统决定 AI 能访问哪些数据；
• 灰度系统决定 AI 功能如何分批开放；
• 审计系统记录 AI 做过什么；
• 服务治理系统保证 AI 调用业务服务时可观测、可限流、可熔断。

十一、对 Java 团队的几个实践建议

1. 不要把 AI 模块做成孤岛

很多项目会新建一个 ai-service，然后所有能力都堆在里面。这在早期能快速试验，但长期容易形成孤岛。

更好的方式是：

• AI 通用能力放在 Starter；
• 业务工具定义在各自业务模块；
• 统一工具注册表负责发现；
• MCP 或 REST 负责对外暴露；
• 审计、权限、观测作为横切能力。

MateCloud 的 mate-ai-starter 就是这个思路。

2. 工具描述要面向模型，而不是面向人

工具描述不是普通注释。它会影响模型是否正确选择工具。

不推荐：

@Tool(description = "query")
public Order query(String id) {
    return orderService.get(id);
}

推荐：

@Tool(description = "Query order summary by order number. Use this when the user asks about order status, payment status, delivery status, or refund state.")
public OrderSummary queryOrder(
        @ToolParam(description = "Order number, usually starts with SO, for example SO202607020001")
        String orderNo) {
    return orderService.findSummary(orderNo);
}

好的工具描述应该说明：

• 这个工具做什么；
• 什么时候使用；
• 什么时候不要使用；
• 参数格式是什么；
• 返回结果代表什么。

3. 写操作先进入审批流

AI 可以辅助执行，但不应该默认拥有无限写权限。

建议按风险分级：

4. 把 conversationId 设计成业务键

不要简单使用随机 UUID。更好的方式是让 conversationId 和业务上下文绑定：

String conversationId = String.join(":",
        tenantId,
        userId,
        "ticket",
        ticketId
);

这样后续审计、复盘、记忆清理、上下文恢复都会更容易。

5. 先让 AI “看懂系统”，再让 AI “操作系统”

AI 工程落地可以分阶段：

1. AI 能回答系统文档、接口文档、业务规则；
2. AI 能查询只读业务数据；
3. AI 能生成草稿和建议；
4. AI 能创建待审批任务；
5. AI 能在低风险场景自动执行；
6. AI 能在完整审计和回滚机制下参与复杂流程。

不要一开始就追求全自动。企业 AI 更应该强调可控演进。

十二、总结：Spring AI 2.0.0 让 Java AI 应用进入工程化阶段

Spring AI 2.0.0 的意义，不在于它让 Java 也能调用大模型。这件事任何 HTTP Client 都能做到。

它真正重要的地方在于：把 AI 能力纳入 Spring 应用的工程模型。

通过 ChatClient，模型调用有了统一入口；通过 Tool Calling，业务方法可以被模型受控调用；通过 Advisor，记忆、安全、日志、治理可以组成链路；通过 MCP，Java 系统可以进入外部 Agent 工具生态；通过结构化输出，模型结果可以回到 Java 类型系统；通过可观测性，AI 调用可以进入企业监控和审计体系。

MateCloud 5.0.8 则提供了一个可以参考的落地样本：它基于 Spring Boot 4、Spring Cloud 2025、Dubbo 3、Spring AI 2.0 和 Java 21，把 AI Starter、@Tool 自动发现、ChatClient、MCP、CLI、单体/微服务双形态、DDD 和后台治理能力放到同一套开源工程中。

对于正在从 Java 微服务走向 AI 原生应用的团队来说，下一阶段的重点不是“再加一个聊天窗口”，而是把自己的业务系统整理成：

可被模型理解的上下文
+ 可被模型调用的工具
+ 可被工程治理的执行链路
+ 可被审计和观测的生产系统

这才是 Spring AI 2.0.0 和 MateCloud 共同指向的方向。

参考资料

• Spring AI 2.0.0 GA 发布：https://spring.io/blog/2026/06/12/spring-ai-2-0-0-GA-available-now
• Spring AI Tool Calling 文档：https://docs.spring.io/spring-ai/reference/api/tools.html
• Spring AI MCP 文档：https://docs.spring.io/spring-ai/reference/api/mcp/mcp-overview.html
• Spring AI Observability 文档：https://docs.spring.io/spring-ai/reference/observability/index.html
• MateCloud GitHub：https://github.com/mateaix/matecloud
• MateCloud Gitee：https://gitee.com/matevip/matecloud
• MateCloud 官网：https://mate.vip