Java on 吾爱主机

AgentScope Java 2.0 实战：构建带权限审批与可恢复执行的生产级 Agent

Thu, 23 Jul 2026 00:00:00 +0800

能调用 Shell、修改文件和派发子任务的 Agent，比普通聊天机器人更有价值，也更危险。Prompt 中一句“执行危险操作前请确认”不是安全边界：模型可能误判上下文、被工具输出诱导，或者在重试中重复执行副作用。

AgentScope Java 2.0 把这类生产问题放进框架核心：每次工具调用都经过权限系统，结果是 ALLOW、DENY 或 ASK；ASK 会暂停 Agent，等待用户确认后再恢复。同时，Harness、Workspace、Sandbox 和分布式状态后端用来承载长时间任务。

本文基于 AgentScope Java 2.0.0 GA 和 JDK 17，先搭建一个 HarnessAgent，再实现“读操作自动放行、写操作必须审批、生产资源不可绕过”的权限策略，最后说明 session 恢复与沙箱的边界。

一、ReActAgent 与 HarnessAgent 的分工

AgentScope Java 2.0 提供两层抽象：

抽象	适合场景	核心关注点
`ReActAgent`	轻量聊天、受限 Tool Calling	推理—行动循环、模型、工具
`HarnessAgent`	长任务、文件/代码 Agent、企业部署	Workspace、Memory、Skills、Subagent、Sandbox、恢复

如果只需调用一个天气 API，ReActAgent 已经足够。若 Agent 要在目录里读写文件、执行命令、跨会话继续任务，应该从 Harness 开始，因为这些能力需要共享一致的运行上下文。

官方 2.0 的设计还强调 Agent 本身无状态：运行状态通过 (userId, sessionId) 和后端管理。这比把可变消息列表放进单例 Agent 更适合多实例部署。

二、依赖和模型配置

AgentScope Java 2.0 要求 JDK 17+。Harness 与模型提供商从 2.0 起拆分为独立模块：

<properties>
 <maven.compiler.release>17</maven.compiler.release>
 <agentscope.version>2.0.0</agentscope.version>
</properties>

<dependencies>
 <dependency>
 <groupId>io.agentscope</groupId>
 <artifactId>agentscope-harness</artifactId>
 <version>${agentscope.version}</version>
 </dependency>

 <dependency>
 <groupId>io.agentscope</groupId>
 <artifactId>agentscope-extensions-model-dashscope</artifactId>
 <version>${agentscope.version}</version>
 </dependency>
</dependencies>

其他官方可选模型模块包括 OpenAI、Anthropic、Gemini 和 Ollama。使用 DashScope 时，把密钥放进环境变量而不是源码：

export DASHSCOPE_API_KEY="你的密钥"

然后创建最小 HarnessAgent：

import io.agentscope.core.agent.RuntimeContext;
import io.agentscope.core.message.UserMessage;
import io.agentscope.harness.agent.HarnessAgent;
import java.nio.file.Paths;

public class OpsAgentApp {
 public static void main(String[] args) {
 HarnessAgent agent = HarnessAgent.builder()
 .name("ops_assistant")
 .sysPrompt("""
 你是运维分析助手。先读后写，输出每一步依据；
 未获得权限系统批准时，不得声称已经修改任何资源。
 """)
 .model("dashscope:qwen-plus")
 .workspace(Paths.get(".agentscope/workspace"))
 .build();

 RuntimeContext ctx = RuntimeContext.builder()
 .userId("alice")
 .sessionId("incident-20260724-001")
 .build();

 var result = agent.call(
 new UserMessage("检查工作区里的故障日志并给出处理建议"), ctx)
 .block();
 if (result != null) {
 System.out.println(result.getTextContent());
 }
 }
}

模型字符串由 ModelRegistry 解析。workspace 不是随便给 Agent 一个宿主机根目录，而应该是专门分配、权限收敛的工作目录。

三、权限系统如何做决策

权限系统位于 io.agentscope.core.permission，拦截每次工具调用。它综合三类信息：

Rules：针对工具和调用模式的显式 ALLOW、ASK、DENY；
Mode：未命中规则时的默认策略；
Built-in Checks：工具根据真实入参执行的不可绕过检查。

决策顺序中，DENY 规则和危险路径检查优先。即使启用 BYPASS，这类保护仍然生效。

官方提供五种常用模式：

模式	未命中规则时的行为	适用情况
`DEFAULT`	要求显式规则或用户确认	推荐默认值
`ACCEPT_EDITS`	放行工作目录内安全文件操作	用户在场的开发任务
`EXPLORE`	只读，拒绝写与命令	代码探索、规划
`BYPASS`	通常放行，但不可绕过的检查仍有效	完全可信且隔离的 Sandbox
`DONT_ASK`	将 ASK 变为 DENY	无人值守任务

DONT_ASK 尤其重要：定时任务没有用户在线，不能让 Agent 永久等待审批，也不应默认放行。

四、配置 ALLOW、ASK 与 DENY 规则

下面的策略允许安全读取，删除操作必须询问，删表始终拒绝：

import io.agentscope.core.permission.PermissionBehavior;
import io.agentscope.core.permission.PermissionContextState;
import io.agentscope.core.permission.PermissionMode;
import io.agentscope.core.permission.PermissionRule;

PermissionContextState permissions = PermissionContextState.builder()
 .mode(PermissionMode.DEFAULT)
 .addAllowRule(
 "safe_read",
 new PermissionRule(
 "safe_read", null,
 PermissionBehavior.ALLOW, "projectSettings"))
 .addAskRule(
 "dangerous_delete",
 new PermissionRule(
 "dangerous_delete", null,
 PermissionBehavior.ASK, "projectSettings"))
 .addDenyRule(
 "drop_table",
 new PermissionRule(
 "drop_table", null,
 PermissionBehavior.DENY, "projectSettings"))
 .build();

可以把权限上下文交给底层 ReActAgent：

ReActAgent agent = ReActAgent.builder()
 .name("controlled_agent")
 .sysPrompt("先检查，再操作")
 .model(model)
 .permissionContext(permissions)
 .build();

若使用 Harness，应在构建 Harness 的 delegate/permission 配置位置应用同一上下文；具体 Builder 入口以 2.0.0 文档和当前模块为准，不要从 RC 版博客复制包名。

规则来源 projectSettings、userSettings、session 或 suggested 应进入审计日志。由用户在一次 ASK 中接受的 suggested rule，可能影响后续相同调用，UI 必须明确告诉用户这是“一次允许”还是“以后允许”。

五、自定义不可绕过的工具检查

静态规则不一定能识别业务语义。比如同一个 restart_service 工具，测试环境可以自动执行，生产环境必须审批。自定义 Tool 可覆盖 checkPermissions：

import io.agentscope.core.permission.PermissionDecision;
import io.agentscope.core.tool.ToolBase;
import io.agentscope.core.tool.ToolExecutionContext;
import java.util.Map;
import reactor.core.publisher.Mono;

public final class RestartServiceTool extends ToolBase {

 public RestartServiceTool() {
 super(ToolBase.builder()
 .name("restart_service")
 .description("重启指定环境中的服务")
 .readOnly(false));
 }

 @Override
 public Mono<PermissionDecision> checkPermissions(
 Map<String, Object> input,
 ToolExecutionContext context) {

 String environment = String.valueOf(input.get("environment"));
 if (environment.startsWith("prod")) {
 return Mono.just(PermissionDecision.ask(
 "目标是生产环境，需要人工批准：" + environment));
 }

 return Mono.just(PermissionDecision.passthrough(
 "非生产环境，继续按 rules/mode 判断"));
 }
}

PASSTHROUGH 不是 ALLOW，它表示把决定权交回规则和模式。对明确禁止的目标可直接返回 deny(...)。

框架还内置危险路径保护，例如 .ssh/、.git/、.aws/、.kube/、.env 和凭据文件。命中危险路径时会强制 ASK；自定义 Tool 也可以增加危险文件和目录。

六、ASK 后怎样暂停与恢复

权限结果为 ASK 时，Agent 不执行工具，而是以 GenerateReason.PERMISSION_ASKING 暂停。返回消息中包含状态为 ASKING 的 ToolUseBlock，调用方应：

把工具名和脱敏后的参数展示给用户；
让用户选择拒绝、仅本次允许或接受建议规则；
构造 ConfirmResult；
使用相同 (userId, sessionId) 恢复 Agent。

核心确认对象如下：

ConfirmResult confirm = new ConfirmResult(
 true, // confirmed
 toolCall, // 本次待确认调用
 toolCall.getSuggestedRules() // 仅在用户明确接受时传入
);

生产 UI 不应只放一个模糊的“确认”按钮。至少显示：

工具名称与风险级别；
目标环境、资源 ID、路径；
是否产生副作用；
建议规则会影响一次还是后续调用；
session、用户和过期时间。

确认结果必须由服务端绑定当前用户和待审批记录，不能接受客户端随意提交另一个 toolCall。

七、流式事件让执行过程可观察

Harness 可以输出统一事件流：

agent.streamEvents(
 new UserMessage("分析日志；如果需要修改配置先请求批准"), ctx)
 .doOnNext(event -> {
 switch (event.getType()) {
 case TEXT_BLOCK_DELTA ->
 System.out.print(((TextBlockDeltaEvent) event).getDelta());
 case TOOL_CALL_START ->
 System.out.println("[tool] "
 + ((ToolCallStartEvent) event).getToolCallName());
 default -> { }
 }
 })
 .blockLast();

事件流可驱动 Web UI、飞书/钉钉 Channel 或审计平台。注意不要把所有原始参数直接写日志；命令、Prompt 和工具结果可能包含 Token、路径或客户数据。

八、Workspace、Sandbox 和权限各管一层

三者不能互相替代：

Workspace 组织文件、Memory、Skills 和子 Agent 工作上下文；
Permission 决定某次工具调用是否允许、拒绝或询问；
Sandbox 限制已经获准的代码实际能访问哪些系统资源。

即使权限系统批准 rm temp.txt，Sandbox 仍应阻止进程读取宿主机 SSH 密钥。反过来，Docker 隔离也不能代替业务审批：容器里的工具可能仍持有生产 API 凭据。

可按风险逐级部署：

开发：专用本地目录 + DEFAULT
测试：Docker Sandbox + ACCEPT_EDITS
生产交互：Kubernetes Sandbox + DEFAULT + HITL
生产无人值守：最小工具集 + DONT_ASK + 服务端白名单

每个 Sandbox 还应配置 CPU、内存、进程数、超时、只读根文件系统和网络出口策略。

九、可恢复执行的正确边界

AgentScope Java 2.0 支持 Redis、MySQL、PostgreSQL、OSS/COS 等分布式 session 和 memory 后端，并面向跨副本 session 恢复。但“恢复 Agent 状态”仍不等于“业务操作恰好一次”。

经典故障窗口：

工具成功重启服务
 -> 进程在保存工具结果前崩溃
 -> 恢复后模型再次请求重启

解决方案在工具层：

record OperationRequest(String operationId, String service, String environment) {}

operationId 由可信服务端生成；
业务库对它建立唯一约束；
重复请求返回第一次结果，而不是再次执行；
checkpoint 记录 operationId 与状态；
外部系统也尽可能使用幂等键。

userId + sessionId 用于隔离会话，operationId 用于隔离副作用，二者不要混为一谈。

十、生产部署清单

默认使用 DEFAULT 或 EXPLORE，不把 BYPASS 当省事开关；
无人值守任务使用 DONT_ASK，未明确允许的调用直接拒绝；
生产、凭据和危险路径在 Tool 内做不可绕过检查；
ASK 绑定用户、session、调用参数摘要和过期时间；
Suggested Rule 的持久化范围对用户透明；
Sandbox 有资源限制、网络出口策略和短期凭据；
所有写工具都有幂等键与审计记录；
使用共享状态后端，并测试滚动发布和跨副本恢复；
对每种工具做 ALLOW、ASK、DENY 和恢复故障测试；
日志和事件流经过脱敏。

十一、常见问题

Agent 一直要求确认

检查规则的 toolName 和 ruleContent 是否真的匹配调用；若默认 DEFAULT 且没有 ALLOW 规则，询问是预期行为。不要直接切到 BYPASS，先补齐最小权限规则。

定时任务卡在 ASK

无人值守场景改用 DONT_ASK，并显式允许安全工具。ASK 会转成 DENY，从而让任务失败得可观察，而不是永久等待不存在的用户。

工作区恢复后找不到文件

本地 Workspace 不适合多副本。使用共享存储或远程文件系统，并保证所有副本使用一致的路径映射、租户隔离和版本策略。

已有 Sandbox，为什么还要权限系统

Sandbox 限制“能破坏多大范围”，权限系统限制“此刻是否应该执行”。前者是隔离，后者是意图授权，必须叠加。

总结

AgentScope Java 2.0 的核心价值不是又实现了一次 ReAct，而是把 Agent 当成一个需要治理的长期运行系统：

权限系统在每次工具调用前作出 ALLOW、ASK 或 DENY；
Tool 的 Built-in Check 能根据真实参数建立不可绕过的业务安全线；
HITL 用同一 session 暂停和恢复，而不是只在 Prompt 里“请求确认”；
Workspace 管上下文，Sandbox 管隔离，分布式后端管恢复；
幂等和业务事实仍由工具与数据库负责。

如果你的 Agent 会改文件、执行命令或触碰生产资源，先设计权限、审批、隔离和恢复，再讨论模型是否更聪明。生产 Agent 最重要的能力，不是永远做对，而是做错时被阻止、失败后可恢复、重试时不重复造成损失。

参考资料

Google ADK Java 实战：用 Code-first 方式编排多 Agent 工作流

Thu, 23 Jul 2026 00:00:00 +0800

Google Agent Development Kit（ADK）Java 是一个代码优先的 Agent 工具包：Agent 的角色、工具和编排直接写在 Java 中，可以进入版本控制、单元测试和部署流程。它不是只能调用 Gemini 的聊天 SDK，而是提供 LlmAgent、Sequential/Parallel/Loop Agent、Session/State、Dev UI 和 A2A 集成。

本文基于 Google ADK Java 1.7.0，实现一个“研究—审查—成稿”的顺序多 Agent 工作流，并说明工具、Session State、Dev UI 以及 A2A 与 MCP 的分工。

截至 2026-07-23，官方 README 仍将 ADK Java 标记为 Preview / Pre-GA，并说明相关能力按 “as is” 提供、支持可能有限。它适合学习、PoC 和可控试点；关键生产系统上线前必须锁版本、做回归测试并准备替代路径。

一、ADK 的 Code-first 是什么

代码优先不只是“不写 YAML”，而是把 Agent 系统的重要结构放进类型化代码：

BaseAgent
├── LlmAgent 模型驱动，能调用工具或委派
├── SequentialAgent 按顺序执行子 Agent
├── ParallelAgent 并行执行独立子 Agent
└── LoopAgent 在条件下重复执行

LLM 适合处理语义判断和非结构化内容；Sequential/Parallel/Loop 则提供确定性控制。一个可靠系统往往混用二者，而不是让一个大模型临场规划全部步骤。

本文流程是：

用户主题
 -> researcher：形成事实清单，写入 research_notes
 -> reviewer：检查证据与风险，写入 review_notes
 -> writer：读取前两步结果，形成文章提纲

三个专业 Agent 可以使用不同 Prompt，输出通过 Session State 传递。

二、依赖、凭据与版本状态

Maven 依赖：

<properties>
 <maven.compiler.release>17</maven.compiler.release>
 <adk.version>1.7.0</adk.version>
</properties>

<dependencies>
 <dependency>
 <groupId>com.google.adk</groupId>
 <artifactId>google-adk</artifactId>
 <version>${adk.version}</version>
 </dependency>

 <dependency>
 <groupId>com.google.adk</groupId>
 <artifactId>google-adk-dev</artifactId>
 <version>${adk.version}</version>
 </dependency>
</dependencies>

google-adk-dev 用于本地开发 UI，不建议不加区分地打进生产镜像。

使用 Google AI Studio / Gemini API 时，凭据名称和认证方式应以当前 ADK 官方文档为准，常见本地配置是：

export GOOGLE_API_KEY="你的密钥"

如果使用 Vertex AI，还需要 Google Cloud Project、区域和 ADC 等配置。不要把服务账号 JSON 放进源码或容器镜像。

三、先实现一个可验证的 FunctionTool

ADK 可以把静态 Java 方法包装成工具。下面的工具只返回受控的本地资料，便于无外部搜索依赖地验证调用链：

import com.google.adk.tools.Annotations.Schema;
import java.util.Map;

public final class ResearchTools {

 public static Map<String, String> lookupFrameworkFact(
 @Schema(
 name = "framework",
 description = "框架名称，例如 Spring AI Alibaba 或 AgentScope Java")
 String framework) {

 return switch (framework.toLowerCase()) {
 case "spring ai alibaba" -> Map.of(
 "status", "success",
 "fact", "面向 Java 的 Agent、Workflow 与 Multi-Agent 框架");
 case "agentscope java" -> Map.of(
 "status", "success",
 "fact", "面向分布式、生产级、长时间运行 Agent 的 Java 框架");
 default -> Map.of(
 "status", "not_found",
 "fact", "本地资料中没有该框架");
 };
 }
}

包装为 FunctionTool：

import com.google.adk.tools.FunctionTool;

var factTool = FunctionTool.create(
 ResearchTools.class,
 "lookupFrameworkFact");

工具参数用 @Schema 写清名称和描述，返回值使用结构化 Map 或 POJO。模型可以决定是否调用，但 Java 方法必须独立完成参数校验、鉴权、超时和幂等。

四、定义三个专业 LlmAgent

1. Researcher

import com.google.adk.agents.LlmAgent;

LlmAgent researcher = LlmAgent.builder()
 .name("researcher")
 .description("查找并整理主题相关事实")
 .model("gemini-2.0-flash")
 .instruction("""
 根据用户主题整理事实清单。
 可调用 lookupFrameworkFact；找不到的内容明确标为待核验，禁止编造。
 输出简洁 Markdown 要点。
 """)
 .tools(factTool)
 .outputKey("research_notes")
 .build();

outputKey 会把 Agent 最终输出写入 Session State，供后续 Agent 使用。

2. Reviewer

LlmAgent reviewer = LlmAgent.builder()
 .name("reviewer")
 .description("审查研究事实、缺口与风险")
 .model("gemini-2.0-flash")
 .instruction("""
 阅读 session state 中的 research_notes。
 分成：已确认、证据不足、可能过时三类；
 不得把推测升级成事实，给出下一步核验建议。
 """)
 .outputKey("review_notes")
 .build();

3. Writer

LlmAgent writer = LlmAgent.builder()
 .name("writer")
 .description("把研究和审查结果组织成文章提纲")
 .model("gemini-2.0-flash")
 .instruction("""
 使用 research_notes 和 review_notes 生成中文技术文章提纲。
 对证据不足的结论保留警示；不输出版本发布稿，强调可复用原理与实践。
 """)
 .outputKey("article_outline")
 .build();

Prompt 应告诉 Agent 从 State 读取哪些键、输出写到哪里。否则三个 Agent 虽然按顺序运行，却不一定有效协作。

五、用 SequentialAgent 显式编排

import com.google.adk.agents.BaseAgent;
import com.google.adk.agents.SequentialAgent;
import java.util.List;

public final class ArticleWorkflow {

 public static final BaseAgent ROOT_AGENT = SequentialAgent.builder()
 .name("article_workflow")
 .description("研究、审查并生成文章提纲")
 .subAgents(List.of(researcher, reviewer, writer))
 .build();
}

顺序编排的价值是依赖关系明确：Reviewer 不会在 Researcher 之前运行，Writer 也不会绕过审查。它比让一个“主管 Agent”自行决定顺序更容易测试。

何时用其他类型：

ParallelAgent：两个子任务互不依赖，例如同时查官方文档和运行基准；
LoopAgent：审查不通过就重写，但必须设置退出条件和最大轮数；
LlmAgent + subAgents：让模型按语义把任务委派给专业 Agent。

不要把有先后依赖的任务硬塞进 Parallel，也不要创建没有最大次数的 Loop。

六、启动 Dev UI

ADK Java 自带开发 UI，可用于交互、查看事件和调试 Agent。最简单入口：

import com.google.adk.web.AdkWebServer;

public class Main {
 public static void main(String[] args) {
 AdkWebServer.start(ArticleWorkflow.ROOT_AGENT);
 }
}

启动后在本地页面输入：

比较 Java Agent 框架在工具权限和恢复方面的差异

开发 UI 适合：

看模型是否调用了工具；
检查专业 Agent 的执行顺序；
观察 State 中输出键；
保存用于演示和人工回归的会话。

它不是生产认证网关。上线时仍需自己的 API 层、身份系统、限流、审计和 Secret 管理。

七、Session、State 与 Artifact

ADK 中要区分：

概念	用途
Session	某用户/某次连续交互的容器
State	小型结构化状态，如研究摘要、审核结论
Event	用户、模型、工具与 Agent 运行过程
Artifact	文件、报告、图片等较大对象

outputKey 写入的是 State，不应把大文件或整份日志塞进去。大对象应使用 Artifact 服务，并在 State 中只保存引用和摘要。

生产环境还要决定 Session Service 的持久化实现。进程内 Session 适合 Demo；多实例部署需要共享后端，并测试并发更新、过期、迁移和恢复。

即使 Session 能恢复，工具副作用仍要幂等。流程崩溃可能发生在外部 API 已成功、结果尚未写回 Event/State 的窗口。

八、确定性 Workflow 与 LLM 路由怎样选择

优先确定性编排的情况：

合规审批顺序固定；
后一步依赖前一步产物；
需要精确控制成本和最大循环；
每个阶段都要测试和审计。

适合 LLM 路由的情况：

用户意图类别多，规则难以穷举；
多个专业 Agent 能力边界清楚；
选错路由的损失低，且可以回退；
工具和 Agent 都没有越权能力。

常用组合是：顶层确定性 Workflow 控制阶段，某个阶段内部用 LlmAgent 选择工具或子 Agent。

九、A2A 与 MCP 的分工

ADK 官方重点支持 A2A，用于远程 Agent 之间的能力发现和通信。MCP 则主要面向工具、资源和 Prompt 的互操作。

文章 Agent
 --A2A--> 独立部署的法务审查 Agent
 --MCP--> 搜索、数据库、文件等工具服务器

二者不是替代关系：

协议	对端	典型能力
A2A	另一个自治 Agent	委派任务、跟踪远程任务、交换结果
MCP	工具/资源服务器	调函数、读资源、获取 Prompt

跨进程后要验证认证、超时、取消、流式、重试和版本协商。协议兼容不代表安全策略自动兼容。

十、Preview 阶段怎样控制风险

官方 1.7.0 已发布到 Maven Central，但 README 仍标记 Preview / Pre-GA，且部分评测能力仍在演进。工程上应：

锁定 1.7.0，不使用动态版本；
用自己的 AgentWorkflow 接口包住 ADK 类型；
保存固定输入、工具调用和状态输出作为回归集；
将模型与工具封装在可替换适配层；
不把 Dev UI 暴露到公网生产环境；
对每次升级验证 Session schema、事件格式和工具调用；
为迁移到其他工作流引擎保留业务层边界。

“1.x”不自动等于 GA，官方发布阶段声明比版本号更重要。

十一、常见问题

后续 Agent 读不到前一步输出

确认前一步设置 outputKey，后续 Prompt 使用同一个 State 键；还要确认 Workflow 使用同一 Session，而不是为每步创建新会话。

模型不调用 FunctionTool

检查方法是否为可反射调用的静态方法、名称是否传给 FunctionTool.create、参数 Schema 是否明确，以及具体模型是否支持工具调用。

ParallelAgent 结果互相覆盖

每个并行 Agent 使用唯一 outputKey，汇总 Agent 再读取多个键。不要让并行分支写同一个 State 字段。

LoopAgent 不停运行

增加确定性退出条件和最大迭代数，同时记录每轮结果。不要只靠 Prompt 中“完成后停止”。

本地成功，上云后丢 Session

本地 Dev UI 常使用进程内服务。生产要配置共享 Session/Artifact 后端，并验证多副本路由、过期和并发更新。

十二、生产清单

明确标记 ADK Java 为 Preview / Pre-GA，并锁定精确版本；
工作流顺序由代码控制，LLM 只处理需要语义判断的节点；
每个 State Key 有唯一写入者或明确合并规则；
Artifact 与 State 分开保存；
工具有鉴权、幂等、超时和结构化错误；
Loop 有最大次数，Parallel 分支避免写冲突；
Dev UI 只用于受控开发环境；
A2A 和 MCP 分别设计认证与审计；
升级前运行固定 Agent/Tool/State 回归集；
多实例环境使用共享 Session 服务。

总结

Google ADK Java 最有价值的地方，是让 Java 开发者在同一套代码中组合两类控制：

LlmAgent 处理语义、工具选择和非结构化内容；
Sequential、Parallel、Loop 等 Workflow Agent 提供确定性控制；
outputKey、Session State 和 Artifact 负责阶段间传递；
Dev UI 降低本地调试成本；
A2A 连接独立 Agent，MCP 连接工具和资源。

在 Preview 阶段，建议从边界明确的内部工作流开始，而不是立刻替换关键核心系统。Code-first 的真正收益不只是代码看起来清晰，而是工作流能进入代码审查、测试、版本管理和故障演练。

参考资料

Java AI Agent 四框架对比：Spring AI Alibaba、AgentScope Java、LangChain4j 与 Google ADK Java

Thu, 23 Jul 2026 00:00:00 +0800

Java AI Agent 生态已经不再只有“给大模型套一个 HTTP 客户端”。Spring AI Alibaba、AgentScope Java、LangChain4j、Google ADK Java 都能连接模型和工具，但它们解决的问题并不相同：有的强调 Spring 工作流，有的把权限、沙箱和分布式恢复放在核心位置，有的是通用 JVM AI 工具箱，有的则围绕代码优先的多 Agent 编排设计。

本文不按 GitHub Star 简单排名，而是从 编程模型、执行控制、状态恢复、安全、协议、可观测性和生态锁定 等方面比较四个框架，并给出面向真实项目的选型路径。

版本快照：Spring AI Alibaba 稳定线 1.1.2.2，AgentScope Java 2.0.0 GA，LangChain4j 1.18.0，Google ADK Java 1.7.0。版本状态截至 2026-07-23。Google ADK Java 官方仍标记 Preview / Pre-GA；LangChain4j 核心库与其高层 Agentic 模块的成熟度也不能混为一谈。

一、先给结论

如果你的核心问题是	优先考虑
Spring Boot 项目要做 Graph、Supervisor、国内模型和多 Agent	Spring AI Alibaba
Agent 要安全执行 Shell/文件工具，并支持审批、沙箱和跨实例恢复	AgentScope Java
先统一模型、RAG、Tool Calling、MCP，再逐步加入 Agent	LangChain4j
需要代码优先的 Sequential/Parallel/Loop 多 Agent，并深度使用 Gemini/Google Cloud	Google ADK Java
只是一个模型调用 2～3 个只读工具	先用 LangChain4j AI Services 或 Spring AI，未必需要多 Agent

没有“全维度最强”的框架。正确问题不是“哪个框架功能最多”，而是：你的不确定性主要来自模型决策、工作流状态、工具副作用，还是部署运行时？

二、四种不同的设计中心

1. Spring AI Alibaba：Spring + Agent Workflow

Spring AI Alibaba 在 Spring AI 的模型、工具、消息等抽象上，增加 ReactAgent、Graph Runtime、SequentialAgent、ParallelAgent、RoutingAgent、Supervisor 等高层能力。

它的设计中心是 用 Java 和 Spring 管理可组合的 Agent 工作流。适合将 Agent 作为现有 Spring 企业应用的一部分，而不是另起一套运行平台。

典型结构：

Spring Boot
 -> Supervisor / Routing / Graph
 -> ReactAgent A -> Spring Bean Tools
 -> ReactAgent B -> MCP / Service
 -> Saver / Observability / Nacos

2. AgentScope Java：生产运行时与 Harness

AgentScope Java 2.0 不只关心模型如何选择工具，还把生产运行问题提升为一等能力：强类型事件、工具权限、人工审批、Workspace、Sandbox、Middleware、分布式 session 和 memory、跨副本恢复。

它的设计中心是 让长时间运行、会执行真实操作的 Agent 安全稳定地活下去。

HarnessAgent
 -> Workspace / Skills / Memory
 -> Permission Decision
 -> Local / Docker / Kubernetes Sandbox
 -> Distributed Backend + Session Recovery

3. LangChain4j：Java 原生 AI 应用工具箱

LangChain4j 首先是通用 Java LLM 应用库。AI Services 允许开发者用 Java 接口定义模型服务，周围组合 Memory、RAG、@Tool 和 MCP；它同时兼容 Spring Boot、Quarkus、Helidon、Micronaut。

它的设计中心是 用符合 Java 习惯的接口、POJO 和注解连接不同模型与 AI 能力。这使它适合作为长期底座，但不要因为核心库成熟，就默认高层 langchain4j-agentic 模块也达到相同稳定程度；官方仍将该模块标为实验性能力。

4. Google ADK Java：Code-first Agent Development Kit

Google ADK Java 从一开始就围绕 Agent 构建，提供 LlmAgent、Sequential/Parallel/Loop 工作流、Session/State、工具和开发 UI，并支持 A2A。

它的设计中心是 用代码显式定义 Agent、工具和编排，并贯通开发、调试与 Google Cloud 部署。优势是 Agent-first 和 Google 生态，代价是项目仍处于 Preview / Pre-GA 阶段。

三、核心能力横向比较

维度	Spring AI Alibaba	AgentScope Java 2.0	LangChain4j	Google ADK Java
主要定位	Agent 工作流与多智能体	生产级 Agent Harness	JVM AI 应用工具箱	Code-first Agent SDK
主要语言	Java	Java	Java	Java
基础要求	JDK 17、Spring Boot	JDK 17+	依模块而定	Java + Maven/Gradle
单 Agent	`ReactAgent`	`ReActAgent` / `HarnessAgent`	AI Services + Tools；Agentic 模块	`LlmAgent`
工作流	Graph、顺序、并行、路由、循环	Harness、Subagent、事件驱动	高层 Agentic 模块仍需谨慎	Sequential、Parallel、Loop
状态恢复	Saver / Graph checkpoint	分布式 session、memory、跨副本恢复	Chat Memory 为主，复杂恢复自行设计	Session / State / Artifact
HITL	Graph 中断等方式组织	原生权限：允许/审批/拒绝	通常由应用层实现	可通过流程/工具层实现
Sandbox	有独立 Sandbox 生态	本地、Docker、K8s、云 Sandbox	非核心能力	非核心能力
MCP	支持	支持	支持	工具生态可扩展，MCP 与 A2A 应分工看待
A2A	支持，并可结合 Nacos	支持	需看具体集成	官方重点能力
国内模型	很强	DashScope、DeepSeek 等扩展	提供多厂商集成	Gemini 最自然，其他模型需验证
Spring 集成	原生核心	可集成，但不是唯一运行方式	成熟	不是核心设计中心
当前主要风险	版本线迭代快	2.0 GA 较新，工程复杂度高	Agentic 高层 API 实验性	Preview / Pre-GA、平台偏向

这张表不能代替 PoC。尤其是“支持”两个字，可能只代表存在适配器，并不代表拥有相同的错误语义、流式事件、结构化输出和生产经验。

四、编程模型：接口、图、Harness 与 Agent 树

Spring AI Alibaba：把 Agent 当成图中的节点

开发者可以先构建专业 ReactAgent，再将它们包装成 Supervisor 的工具，或放进 Graph 里增加条件边、重试和 checkpoint。它适合“业务流程大体确定，但部分节点需要 LLM 决策”的系统。

优势：

确定性工作流与 Agent 节点可以混合；
Spring Bean、配置、监控和业务服务复用自然；
对复杂流程的控制力强于单纯 ReAct 循环。

代价：Graph、Agent Framework、Spring AI 与 Alibaba 版本线需要一起管理，升级时应做依赖树和回归测试。

AgentScope Java：把 Agent 当成长期运行的受控进程

HarnessAgent 组合 Workspace、Memory、Skills、Subagent、权限和沙箱。这里的关键不只是“下一步调哪个函数”，还包括：调用是否需要用户批准、工具在哪个隔离环境运行、崩溃后从哪里恢复、事件如何实时推给前端。

优势：生产问题覆盖最完整。

代价：如果业务只需简单问答和只读工具，Harness 的概念和部署组件可能过重。

LangChain4j：把 AI 能力当成 Java Service

典型写法是定义接口：

interface Assistant {
 String chat(@MemoryId String userId, @UserMessage String message);
}

再通过 AiServices.builder(...) 绑定模型、Memory Provider 和工具对象。这种方式对传统 Java 团队非常自然，单元测试和依赖注入也容易组织。

优势：模型、RAG、工具与框架集成广，渐进式采用成本低。

代价：复杂多 Agent 的暂停、恢复、HITL 和图执行不应仅靠 Chat Memory 拼装；高层 Agentic 模块仍需要固定版本和充分验证。

Google ADK Java：把 Agent 组合成代码结构

开发者定义多个 LlmAgent，再通过 Sequential、Parallel 或 Loop Agent 显式组合。Session 保存对话和状态，Dev UI 用于本地调试。

优势：多 Agent 编排概念清晰，A2A 与 Google Cloud 路线完整。

代价：官方 README 仍声明 Preview / Pre-GA，且部分评测能力仍在演进。关键生产系统应先做版本冻结、回归集和退出预案。

五、状态与恢复：最容易比较错的维度

“支持 Memory”不等于“支持崩溃恢复”。至少要区分：

对话记忆：模型下一轮能看到什么；
工作流 checkpoint：程序执行到哪个节点；
业务事实：邮件是否真的发送、订单是否真的创建；
Artifact：文件、报告、图片等大对象；
分布式路由状态：哪个副本继续哪个 session。

需求	更适合的起点
多轮问答记住用户上下文	LangChain4j Chat Memory
Graph 节点暂停后继续	Spring AI Alibaba Saver / checkpoint
跨副本恢复长任务和子 Agent	AgentScope Java Distributed Backend
Agent Session、State 与 Artifact 一体组织	Google ADK Java

无论框架多强，都不能替业务工具完成 exactly-once。崩溃可能发生在“下游已经写成功，但 Agent 还没保存结果”的窗口。邮件、支付、工单等工具必须使用幂等键和唯一约束。

六、安全：不要把 Prompt 当权限系统

四个框架都可以在 Prompt 中写“删除前请确认”，但这不是安全边界。

AgentScope Java 的差异最明显：权限系统原生表达 允许、要求用户审批、拒绝，并能把工具放入沙箱。若业务是运维、代码执行或文件操作，它通常更贴近需求。

其他框架也能实现安全控制，但需要在应用层构建：

Agent 只能调用 prepare_operation
 -> 服务端创建 WAITING_APPROVAL 记录
 -> 人类在可信 UI 审批
 -> 后端用 approvalId 执行
 -> 工具返回真实 operationId

所有框架都应遵守：

身份和租户信息来自服务端上下文，不让模型填写；
写工具与读工具分离；
工具参数使用结构化类型和白名单；
高风险工具默认拒绝或必须审批；
沙箱之外还要有操作系统、网络和云 IAM 限制；
日志脱敏，Prompt 与工具结果不能泄露凭据。

七、MCP 与 A2A 不是竞争关系

MCP 主要解决 Agent/模型如何发现并调用工具、资源和提示模板；
A2A 主要解决相互独立的 Agent 如何描述能力、通信和协作。

例如，采购 Agent 可以通过 MCP 调 ERP 查询工具，同时通过 A2A 把合同审查任务交给远程法务 Agent。不要因为框架同时写着 MCP 和 A2A，就把二者当成同一层协议。

选型时应验证的不只是协议名称，还包括：认证、超时、流式、取消、错误码、版本协商、审计和跨租户隔离。

八、用同一个 PoC 做公平测试

建议不要分别跑四个官方 Hello World，而是实现同一个“采购审批 Agent”：

读取采购申请
 -> 并行查询预算与供应商风险
 -> 生成建议
 -> 金额超过阈值则等待人工批准
 -> 创建订单
 -> 模拟进程崩溃并恢复

统一测量：

指标	观察方法
实现复杂度	业务代码量、配置量、概念数量
工具正确率	固定 100 条用例，统计选错/漏调/参数错
副作用安全	重试和恢复后是否重复创建订单
恢复能力	在每个节点前后故障注入
可观测性	能否关联模型、工具、session、审批和错误
成本	模型调用次数、token、延迟
可测试性	不调用真实模型时能否测试控制流
生态约束	替换模型、存储、云环境的改动范围

真正的选型结论通常不是“框架 A 功能比 B 多”，而是“框架 A 让我们的关键失败模式更容易被测试和控制”。

九、按团队和场景选型

场景 1：现有 Spring Boot 企业系统

优先评估 Spring AI Alibaba。它能直接复用 Spring Service、配置、Actuator 和依赖注入，也更容易把确定性 Graph 与 Agent 节点结合。

若当前阶段只做模型、RAG 和少量工具，也可以从 LangChain4j 或 Spring AI 底层能力开始，不必一开始引入多 Agent。

场景 2：运维 Agent、代码 Agent、长任务 Agent

优先评估 AgentScope Java。权限决策、Workspace、Sandbox、事件系统和跨副本恢复与该类风险高度匹配。

不过，选它不等于自动安全：Docker/Kubernetes 隔离、网络出口、凭据代理、资源配额和人工审批后端仍需自行配置。

场景 3：希望模型和应用框架保持中立

优先评估 LangChain4j。它的提供商和向量库集成广，也能运行在 Spring Boot、Quarkus、Micronaut 等环境中。

复杂 Agentic 编排要单独做成熟度评估；必要时可把 LangChain4j 作为模型/工具层，配合其他工作流引擎。

场景 4：Gemini、Google Search、Vertex AI 和 A2A

优先评估 Google ADK Java。其代码优先的 Agent 树、Dev UI 和 Google 生态协同清晰。

但 Preview / Pre-GA 是实际风险，不应藏在脚注里。上线前要锁版本、保留回滚路径，并验证非 Google 模型或未来迁移的成本。

场景 5：框架混用

混用可以成立，但只在边界明确时：

Spring AI Alibaba Graph 负责确定性业务流程；
AgentScope Harness 负责需要沙箱的远程专业 Agent；
LangChain4j 提供某些模型或 RAG 能力；
A2A 连接独立 Agent 服务。

不要在同一进程同时引入四套消息、Memory、Tool 和 tracing 抽象。每多一层适配，都要明确谁负责重试、取消、状态和错误翻译。

十、决策清单

在确定框架前，逐项回答：

我们需要的是聊天记忆，还是工作流崩溃恢复？
工具是否有副作用，是否必须人工审批？
是否会执行 Shell、代码或文件操作，需要哪一级沙箱？
工作流是确定性图，还是高度自治的 ReAct？
是否需要多实例、跨副本恢复和后台长任务？
MCP、A2A 分别解决哪个边界？
是否必须使用 Spring、Google Cloud 或国内模型生态？
当前所用模块是 GA、稳定版、experimental，还是 Pre-GA？
能否在不调用真实模型的情况下测试控制流？
工具是否具备幂等、鉴权、审计和超时？

总结

四个项目代表四条不同路线：

Spring AI Alibaba：用 Spring 和 Graph 构建可控的 Agent 工作流；
AgentScope Java：为安全、长任务和分布式恢复提供生产 Harness；
LangChain4j：用 Java 原生接口组织模型、RAG、工具与 MCP；
Google ADK Java：用代码优先方式组合多 Agent，并连接 Google/A2A 生态。

对于多数团队，最稳妥的方法是先选一个有真实副作用、需要审批和恢复的业务任务，用同一组测试用例做 PoC。Agent 框架的价值，不在于让 Demo 调用更多工具，而在于当模型选错、工具超时、进程崩溃或用户拒绝审批时，系统仍然可解释、可恢复、不会重复造成损失。

参考资料

LangChain4j 实战：用 AI Services 与 Tool Calling 构建可控 Java Agent

Thu, 23 Jul 2026 00:00:00 +0800

LangChain4j 最容易被误解成“Python LangChain 的 Java 移植版”。实际上，它更强调 Java 接口、POJO、注解、类型安全和依赖注入。开发者可以把大模型能力定义成一个普通 Java Service，再组合 Chat Memory、RAG、@Tool 和 MCP。

本文使用 LangChain4j 1.18.0 和 JDK 17，实现一个订单查询与退款申请助手。模型可以读取订单，但退款属于副作用操作，必须先创建待审批申请，不能让模型直接完成退款。这个案例能说明：Tool Calling Agent 的重点不在“模型会调用函数”，而在于怎样让工具接口、状态和权限保持可控。

LangChain4j 的核心 AI Services、Tool Calling 与模型集成已经广泛使用；但官方明确说明整个 langchain4j-agentic 高层模块仍属于 experimental。本文先使用稳定的 AI Services + Tools 路线，不把实验性多 Agent API 当作生产前提。

一、Agent 的最小闭环

一个最小 Tool Calling Agent 包含：

用户消息
 -> AI Service 组装系统消息和历史
 -> ChatModel 判断是否调用工具
 -> LangChain4j 执行 @Tool 方法
 -> 工具结果回到模型
 -> 模型生成最终回答

这已经具备“观察—行动—再观察”的基本能力。只有当任务需要多个专业 Agent、共享工作区和复杂编排时，才有必要引入更高层 Agentic 模块。

在工程上，Agent 由三部分构成：

部分	责任
AI Service 接口	定义输入输出、系统约束和会话边界
ChatModel	生成回答与工具调用请求
Tool 对象	在 Java 可信边界内访问业务系统

模型提出调用，Java 工具决定什么能够真正执行。

二、依赖和模型

LangChain4j 1.18.0 的最低 JDK 是 17。使用 OpenAI 兼容模型时可先引入：

<properties>
 <maven.compiler.release>17</maven.compiler.release>
 <langchain4j.version>1.18.0</langchain4j.version>
</properties>

<dependencyManagement>
 <dependencies>
 <dependency>
 <groupId>dev.langchain4j</groupId>
 <artifactId>langchain4j-bom</artifactId>
 <version>${langchain4j.version}</version>
 <type>pom</type>
 <scope>import</scope>
 </dependency>
 </dependencies>
</dependencyManagement>

<dependencies>
 <dependency>
 <groupId>dev.langchain4j</groupId>
 <artifactId>langchain4j</artifactId>
 </dependency>
 <dependency>
 <groupId>dev.langchain4j</groupId>
 <artifactId>langchain4j-open-ai</artifactId>
 </dependency>
</dependencies>

BOM 中部分扩展模块仍可能采用 beta 版本号。生产项目要看实际依赖树，而不能只看到 BOM 是 1.18.0 就认为所有模块都达到相同稳定级别。

模型配置示例：

import dev.langchain4j.model.chat.ChatModel;
import dev.langchain4j.model.openai.OpenAiChatModel;

ChatModel model = OpenAiChatModel.builder()
 .apiKey(System.getenv("OPENAI_API_KEY"))
 .modelName("gpt-4.1-mini")
 .temperature(0.1)
 .build();

具体模型名和 Tool Calling 能力以提供商当前文档为准。若接入 OpenAI-compatible 服务，还需设置 baseUrl，并实测结构化参数、并行工具调用和流式行为，而不能只验证普通聊天。

三、用 Java 接口定义 AI Service

import dev.langchain4j.service.MemoryId;
import dev.langchain4j.service.SystemMessage;
import dev.langchain4j.service.UserMessage;

public interface OrderAssistant {

 @SystemMessage("""
 你是订单售后助手。
 查询订单前必须获得明确订单号；不得猜测订单状态。
 退款只能创建待审批申请，不能声称退款已经到账。
 最终回答要区分：查询结果、待审批、已拒绝和已完成。
 """)
 String chat(
 @MemoryId String userId,
 @UserMessage String message);
}

接口有两个值得注意的边界：

@MemoryId 只是选择会话记忆的键，不应直接作为业务身份凭据；
String 返回值适合聊天，业务系统若需要可靠状态，应从工具/数据库读取，而不是解析模型自然语言。

真实 HTTP 服务应该从认证上下文得到 userId，不能让客户端任意指定其他用户的 Memory ID。

四、设计只读工具与副作用工具

先定义订单对象和仓库：

public record Order(
 String orderId,
 String ownerId,
 String status,
 BigDecimal paidAmount) {}

public interface OrderRepository {
 Optional<Order> findById(String orderId);
}

查询工具只读，但仍要做归属校验：

import dev.langchain4j.agent.tool.P;
import dev.langchain4j.agent.tool.Tool;

public final class OrderTools {
 private final OrderRepository orders;
 private final RefundRequestRepository refunds;
 private final CurrentUser currentUser;

 public OrderTools(OrderRepository orders,
 RefundRequestRepository refunds,
 CurrentUser currentUser) {
 this.orders = orders;
 this.refunds = refunds;
 this.currentUser = currentUser;
 }

 @Tool("查询当前登录用户的订单状态和实付金额")
 public OrderView getOrder(
 @P("订单号，例如 O-20260725-001") String orderId) {
 Order order = orders.findById(orderId)
 .orElseThrow(() -> new IllegalArgumentException("订单不存在"));
 requireOwner(order);
 return new OrderView(order.orderId(), order.status(), order.paidAmount());
 }

 private void requireOwner(Order order) {
 if (!order.ownerId().equals(currentUser.id())) {
 throw new SecurityException("无权访问该订单");
 }
 }
}

副作用工具不要直接叫 refund，而是创建待审批申请：

@Tool("为当前用户的订单创建退款审批申请；不会直接退款")
public RefundRequestView prepareRefund(
 @P("订单号") String orderId,
 @P("退款原因，必须来自用户明确表达") String reason,
 @P("本次操作幂等键") String operationId) {

 Order order = orders.findById(orderId)
 .orElseThrow(() -> new IllegalArgumentException("订单不存在"));
 requireOwner(order);

 if (!order.status().equals("PAID")) {
 throw new IllegalStateException("只有 PAID 订单可申请退款");
 }

 return refunds.findByOperationId(operationId)
 .orElseGet(() -> refunds.createPending(
 operationId, currentUser.id(), orderId, reason));
}

这里有三条硬规则：

身份来自 CurrentUser，不作为 Tool 参数暴露给模型；
Java 代码再次校验订单状态和归属；
operationId 建立唯一约束，使模型重试不会创建重复申请。

真正执行退款的 approveAndExecuteRefund(approvalId) 应放在后台审批服务中，不注册给该 Agent。

五、绑定模型、Memory 和 Tools

import dev.langchain4j.memory.chat.MessageWindowChatMemory;
import dev.langchain4j.service.AiServices;

OrderAssistant assistant = AiServices.builder(OrderAssistant.class)
 .chatModel(model)
 .chatMemoryProvider(memoryId ->
 MessageWindowChatMemory.withMaxMessages(20))
 .tools(orderTools)
 .build();

调用方式和普通 Java Service 相似：

String answer = assistant.chat(
 authenticatedUser.id(),
 "帮我查订单 O-20260725-001；如果已支付，"
 + "以 operationId=refund-7f24 创建退款申请，原因是重复下单");

System.out.println(answer);

模型可能先调用 getOrder，观察状态后再调用 prepareRefund，最后告知用户“已创建待审批申请”。它没有真正退款的工具，因此即使 Prompt 被忽略，也无法跨过审批边界。

六、Chat Memory 不是业务数据库

MessageWindowChatMemory 只保留有限消息窗口，适合控制上下文长度。它不保证：

永久保存历史；
多实例共享；
业务事实可审计；
工具副作用 exactly-once；
用户身份安全。

应区分：

数据	应放在哪里
最近对话与 Tool Result	Chat Memory Store
订单和退款状态	业务数据库
用户身份与租户	认证上下文
幂等键和审批状态	业务数据库唯一约束
长文档知识	向量库/RAG，而不是无限消息窗口

Memory 里即使写着“退款成功”，也不能作为事实。下一轮回答前，应通过只读工具重新查询业务状态。

七、工具描述决定模型能否正确使用

LangChain4j 支持两层工具 API：底层 ChatModel + ToolSpecification，以及高层 AI Services + @Tool。大多数业务从高层开始即可。

工具描述要回答：

什么情况下调用；
每个参数代表什么；
是否有副作用；
返回值是什么状态；
哪些前置条件必须满足。

反例：

@Tool("处理订单")
String process(String input)

模型既不知道是查询、取消还是退款，也无法稳定生成参数。

改进：

@Tool("只查询当前用户订单；无副作用")
OrderView getOrder(@P("完整订单号") String orderId)

返回值优先使用 record/POJO，而不是拼接含糊字符串。工具错误也要映射为有限错误码，避免把数据库堆栈或敏感信息原样送回模型。

八、如何对工具做测试

Agent 测试要分层：

1. 纯 Java 工具测试

@Test
void duplicateOperationReturnsSameRefundRequest() {
 var first = tools.prepareRefund("O-1", "重复下单", "op-123");
 var second = tools.prepareRefund("O-1", "重复下单", "op-123");
 assertEquals(first.requestId(), second.requestId());
}

这层不调用模型，验证鉴权、状态机、幂等和异常。

2. 模型工具选择测试

准备固定请求集，记录模型是否：

缺订单号时先追问；
未查询状态就申请退款；
编造不存在的 Tool；
把“咨询退款政策”误判成创建退款；
在工具失败后声称成功。

3. 端到端故障测试

模拟超时、429、工具异常和进程重启，确认不会重复副作用，最终状态来自数据库。

不要只凭一条成功 Demo 判断 Agent 可用。

九、MCP 什么时候加入

如果工具和 Agent 在同一进程、都是 Java Bean，直接注册 @Tool 最简单。以下情况再考虑 MCP：

工具由独立团队维护，需要跨语言/跨进程提供；
多个 Agent 客户端需要共享同一工具目录；
希望统一发现工具、资源和 Prompt；
工具生命周期与业务应用不同。

引入 MCP 后，仍要保留认证、租户隔离、超时、幂等和审批。MCP 解决互操作，不自动解决工具可信问题。

十、实验性 Agentic 模块应该怎样用

langchain4j-agentic 提供 @Agent、AgenticScope、Sequential、Parallel、Loop、Supervisor 等模式。官方文档明确写着 whole module experimental。

适合：

技术验证；
内部工具；
固定版本的 PoC；
可以承担 API 变化成本的项目。

生产采用前应：

锁定精确依赖版本；
给编排层包一层自己的接口；
用回归集验证共享变量、错误传播和工具副作用；
不让实验 API 渗透整个业务代码；
为升级准备迁移测试。

若需求只是一个 Agent 调用几个工具，不必为了“多智能体”标签提前引入实验模块。

十一、常见问题

模型从不调用工具

确认具体模型支持 Tool Calling；检查工具描述是否清楚、参数是否可生成，并把温度调低。OpenAI-compatible 不代表工具协议完全兼容，要抓取请求响应做实测。

同一用户的对话串到一起

检查 @MemoryId 是否使用稳定、不可伪造且带租户命名空间的键。多实例还需要共享 ChatMemoryStore；进程内 Memory 不会自动同步。

退款工具被重复调用

不要试图只靠 Prompt 阻止。使用服务端生成的 operationId、数据库唯一约束和“重复请求返回原结果”的工具语义。

Tool 抛出异常后模型仍说成功

让工具返回结构化 status/errorCode，在 AI Service 外再查询业务事实。高风险接口不要把最终成功判定交给自然语言。

换模型后效果明显变化

统一 API 只能统一调用方式，不能抹平模型在 Tool Calling、结构化输出、并行调用和上下文窗口上的差异。每个模型都要跑相同回归集。

十二、生产清单

API Key 只从环境变量或 Secret Manager 读取；
@MemoryId 与认证用户绑定并包含租户命名空间；
只读和写工具分离，Agent 默认只获得最小工具集；
身份、金额、角色不允许由模型自由填写；
所有写工具使用幂等键和唯一约束；
高风险动作只生成待审批请求；
工具返回结构化结果与有限错误码；
模型、工具、token、延迟和 operationId 可关联追踪；
使用固定测试集比较模型与版本；
若采用 Agentic 模块，明确标记 experimental 并隔离 API。

总结

使用 LangChain4j 构建可控 Agent 的关键，不是让一个 Java 接口看起来像魔法，而是保持职责边界：

AI Services 负责消息、Memory 和模型交互；
@Tool 负责把有限业务能力暴露给模型；
Java 服务负责身份、权限、状态机和参数校验；
数据库负责事实、审批与幂等；
高层 langchain4j-agentic 只有在确实需要复杂编排、并接受实验性 API 风险时再引入。

从“只读查询 + 创建待审批申请”开始，远比直接把退款、删库或发邮件工具交给模型可靠。Agent 可以拥有选择工具的自由，但不应该拥有绕过业务规则的自由。

参考资料

Spring AI Alibaba 实战：用 Supervisor 构建可持久化的 Java 多智能体助手

Thu, 23 Jul 2026 00:00:00 +0800

很多 Java Agent 示例只演示“模型调用一个工具”，但真实业务通常横跨多个边界：日历 Agent 理解时间并检查冲突，邮件 Agent 负责收件人和正文，协调者还要决定调用顺序、传递结果，并在失败后恢复。

本文基于 Spring AI Alibaba 官方稳定依赖线 1.1.2.2，实现一个 Supervisor + 专业子 Agent 的个人助理。重点不是某个模型的聊天接口，而是四个可复用的工程问题：如何划分 Agent 边界、怎样把子 Agent 暴露成工具、如何保存执行状态，以及如何控制有副作用的操作。

本文代码结构依据官方 examples/multiagent-patterns/supervisor 示例整理。Spring AI Alibaba 同时存在面向 Spring AI 2.0 / Spring Boot 4 的 2.0.0-M1.1 里程碑版本；生产项目不要把 milestone 与本文稳定线混用。

一、为什么需要 Supervisor

多 Agent 并不等于“把四个聊天机器人放进一个群”。一个可控系统至少要区分三层：

层次	职责	本文对应实现
决策层	拆解请求、选择能力、安排调用顺序	`personal_assistant` Supervisor
专业层	在受限领域内推理和调用工具	`schedule_event`、`manage_email`
执行层	访问日历、邮件、数据库等真实系统	Java `@Tool` 方法

用户说“下周二开评审会，并给设计组发提醒”时，Supervisor 先调用日历 Agent；拿到时间和创建结果后，再把必要信息交给邮件 Agent。专业 Agent 看不到无关工具，工具层也不承担自然语言规划。

这种设计的价值是 缩小每次模型决策的工具集合。如果把查日历、建会议、发邮件、查工单、改数据库等几十个工具全部交给一个 Agent，模型更容易选错工具，权限也难以分层。

二、环境与依赖

官方稳定示例使用 JDK 17、Spring Boot 3.5.7、Spring AI 1.1.2 和 Spring AI Alibaba 1.1.2.2：

<parent>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-parent</artifactId>
 <version>3.5.7</version>
</parent>

<properties>
 <java.version>17</java.version>
 <spring-ai.version>1.1.2</spring-ai.version>
 <spring-ai-alibaba.version>1.1.2.2</spring-ai-alibaba.version>
</properties>

<dependencyManagement>
 <dependencies>
 <dependency>
 <groupId>org.springframework.ai</groupId>
 <artifactId>spring-ai-bom</artifactId>
 <version>${spring-ai.version}</version>
 <type>pom</type>
 <scope>import</scope>
 </dependency>
 <dependency>
 <groupId>com.alibaba.cloud.ai</groupId>
 <artifactId>spring-ai-alibaba-bom</artifactId>
 <version>${spring-ai-alibaba.version}</version>
 <type>pom</type>
 <scope>import</scope>
 </dependency>
 </dependencies>
</dependencyManagement>

<dependencies>
 <dependency>
 <groupId>com.alibaba.cloud.ai</groupId>
 <artifactId>spring-ai-alibaba-starter-dashscope</artifactId>
 </dependency>
 <dependency>
 <groupId>com.alibaba.cloud.ai</groupId>
 <artifactId>spring-ai-alibaba-agent-framework</artifactId>
 </dependency>
 <dependency>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter</artifactId>
 </dependency>
</dependencies>

配置密钥时不要写进仓库：

spring:
 ai:
 dashscope:
 api-key: ${AI_DASHSCOPE_API_KEY}

运行前设置环境变量：

export AI_DASHSCOPE_API_KEY="你的密钥"

如果换成其他 Spring AI ChatModel，Agent 编排代码本身可以保持不变，但工具调用、结构化输出和并行调用能力仍取决于具体模型。

三、先写最窄的业务工具

工具的参数和描述会进入模型上下文。名称模糊、参数万能化，会直接降低调用准确率。下面用内存实现代替真实日历系统：

@Component
public class CalendarTools {

 @Tool(description = "检查指定 ISO-8601 起止时间内是否有空闲时段")
 public String getAvailableTimeSlots(
 @ToolParam(description = "开始时间，例如 2026-07-28T14:00:00+08:00") String start,
 @ToolParam(description = "结束时间，例如 2026-07-28T15:00:00+08:00") String end) {
 return "AVAILABLE: " + start + " ~ " + end;
 }

 @Tool(description = "创建日历事件；调用前必须已经确认时间可用")
 public String createCalendarEvent(
 @ToolParam(description = "事件标题") String title,
 @ToolParam(description = "ISO-8601 开始时间") String start,
 @ToolParam(description = "ISO-8601 结束时间") String end) {
 String id = UUID.randomUUID().toString();
 return "CREATED eventId=" + id + ", title=" + title;
 }
}

邮件工具同样保持窄接口：

@Component
public class EmailTools {

 @Tool(description = "发送邮件。仅接受已经确认的收件人、主题和正文")
 public String sendEmail(String recipient, String subject, String body) {
 return "SENT to=" + recipient + ", subject=" + subject;
 }
}

演示可以直接返回字符串，生产环境必须补上：

幂等键：重试不能创建两场相同会议或发送两封邮件；
身份鉴权：工具从服务端上下文读取租户和用户，不能信任模型传入身份；
参数校验：邮箱白名单、时间范围、正文长度均由 Java 代码强制检查；
审计日志：记录调用者、工具名、参数摘要、结果和 trace ID；
超时与熔断：模型重试不应无限放大下游故障。

四、构建两个专业 ReactAgent

ReactAgent 负责“思考—选择工具—观察结果—继续”的循环。每个专业 Agent 只注册本领域工具：

@Configuration
public class AgentConfiguration {

 @Bean
 MemorySaver memorySaver() {
 return new MemorySaver();
 }

 @Bean
 ReactAgent calendarAgent(ChatModel model, CalendarTools tools) {
 return ReactAgent.builder()
 .name("schedule_event")
 .description("检查空闲时间并创建日历事件，输入为自然语言日程请求")
 .systemPrompt("""
 你是日历助理。先把时间转换为带时区的 ISO-8601 格式，
 再检查空闲时段；只有可用时才创建事件。
 最终回答必须包含事件 ID 和确认后的起止时间。
 """)
 .model(model)
 .methodTools(tools)
 .inputType(String.class)
 .build();
 }

 @Bean
 ReactAgent emailAgent(ChatModel model, EmailTools tools) {
 return ReactAgent.builder()
 .name("manage_email")
 .description("根据明确的收件人和上下文撰写并发送邮件")
 .systemPrompt("""
 你是邮件助理。不得猜测收件地址；缺少地址就要求补充。
 发送前检查主题、正文和会议时间是否一致。
 最终回答给出发送状态，不输出敏感凭据。
 """)
 .model(model)
 .methodTools(tools)
 .inputType(String.class)
 .build();
 }
}

这里的 name 和 description 不是装饰字段。Supervisor 会根据它们决定是否调用子 Agent，因此描述要写清楚 何时调用、输入是什么、能产生什么结果。

五、把子 Agent 变成 Supervisor 的工具

Spring AI Alibaba 提供 AgentTool.getFunctionToolCallback(...)，可以把整个专业 Agent 包装成上层 Agent 可调用的工具：

@Bean
ReactAgent supervisorAgent(
 ChatModel model,
 ReactAgent calendarAgent,
 ReactAgent emailAgent,
 MemorySaver memorySaver) {

 return ReactAgent.builder()
 .name("personal_assistant")
 .systemPrompt("""
 你是任务协调者，可以安排日历和发送邮件。
 先拆解请求，再按依赖顺序调用专业工具。
 邮件依赖会议结果时，必须先完成日历操作。
 不要声称执行了未返回成功结果的操作。
 """)
 .model(model)
 .saver(memorySaver)
 .tools(
 AgentTool.getFunctionToolCallback(calendarAgent),
 AgentTool.getFunctionToolCallback(emailAgent))
 .build();
}

调用入口非常直接：

@Component
public class DemoRunner implements ApplicationRunner {
 private final ReactAgent supervisorAgent;

 public DemoRunner(ReactAgent supervisorAgent) {
 this.supervisorAgent = supervisorAgent;
 }

 @Override
 public void run(ApplicationArguments args) throws Exception {
 String request = "下周二 14:00 安排一小时设计评审，"
 + "然后给 design@example.com 发一封提醒邮件";

 AssistantMessage result = supervisorAgent.call(new UserMessage(request));
 System.out.println(result.getText());
 }
}

一次典型执行链是：

User
 -> Supervisor
 -> schedule_event
 -> get_available_time_slots
 -> create_calendar_event
 -> manage_email
 -> send_email
 -> 汇总最终结果

子 Agent 是工具，但它内部仍然可以执行多轮 ReAct。这样既保留自治能力，又把自治限制在专业边界内。

六、状态持久化不等于聊天记忆

示例中的 MemorySaver 适合本地开发和单进程验证。它保存的是图执行所需的 checkpoint，使 Agent 能围绕同一线程继续运行；它不是生产级共享数据库，也不能替代业务幂等。

工程上要区分三类状态：

状态	示例	推荐存储
会话上下文	用户偏好、已确认的时间	Chat Memory / 会话库
Agent checkpoint	当前节点、工具结果、待恢复位置	持久化 Saver
业务事实	已创建会议、邮件发送记录	业务数据库，带唯一约束

即便 checkpoint 恢复成功，若工具在崩溃前已经写入业务系统、但结果还没写回 checkpoint，恢复后仍可能重复调用。因此可靠流程要让工具接受 operationId，并在业务库建立唯一约束。

七、给副作用加一道人工确认

会议和邮件都属于有副作用操作。最稳妥的方式不是只在 Prompt 中写“请先确认”，而是在工具层建立状态机：

DRAFT -> WAITING_APPROVAL -> EXECUTING -> SUCCEEDED / FAILED

Agent 第一次调用只生成草稿并返回 approvalId；API 层收到用户确认后，才调用真正的发送方法。这样即使模型忽略提示，也没有直接执行权限。

还可以进一步拆成两个工具：

prepare_email(...)：任何 Agent 都能调用，只生成草稿；
send_approved_email(approvalId)：不接受正文，只执行服务端已经批准且未过期的草稿。

这比让模型把 approved=true 当参数传进来安全得多。

八、常见问题与排查

1. 子 Agent 从不被调用

检查 name、description 是否明确，并确认模型支持 Tool Calling。描述不要只写“邮件助手”，而要说明输入和使用时机。

2. 依赖冲突或类找不到

不要混用 Spring AI 1.1.x、Spring AI Alibaba 1.1.x 与 2.0 milestone。使用 BOM 统一版本，并执行：

mvn dependency:tree

重点检查 spring-ai-* 是否出现多条不兼容版本线。

3. 时间被理解错

“明天下午”必须结合用户时区和当前日期解析。生产系统应把当前时间、时区作为可信上下文注入，并在工具层拒绝无时区或已经过期的时间。

4. 重启后任务消失

MemorySaver 只在进程内。多实例部署需要共享持久化 Saver，同时工具仍要做幂等；二者缺一不可。

5. 最终回答说成功，业务却没有记录

只信工具返回的结构化结果，不信模型自行生成的成功话术。建议工具返回包含 status、operationId、errorCode 的对象，并在最终输出前增加确定性校验节点。

九、什么时候不用多 Agent

如果任务只有一个模型、三个简单只读工具和一次调用，单个 ReactAgent 往往更便宜、更快，也更容易测试。只有出现以下情况，多 Agent 才真正有价值：

不同领域需要不同 Prompt、工具权限或模型；
任务能拆成可独立测试的专业能力；
子任务需要并行、路由或多阶段交接；
某些 Agent 必须运行在隔离环境或独立服务中；
团队希望分别维护日历、邮件、工单等能力。

不要用 Agent 替代确定性代码。固定审批顺序、金额阈值和权限检查应该写进 Java 与工作流，而不是交给 LLM 临场决定。

总结

Spring AI Alibaba 的 Supervisor 模式可以概括为：上层 Agent 负责选择和协调，下层 Agent 负责专业推理，Java 工具负责可信执行，Saver 负责恢复上下文。

真正决定系统能否进入生产的并不是 Agent 数量，而是边界是否清楚：

每个专业 Agent 只看到必要工具；
有副作用操作经过服务端审批和幂等保护；
checkpoint、会话记忆与业务事实分开保存；
版本通过 BOM 锁定，不混用稳定线和 milestone；
最终成功状态由真实工具结果而不是模型话术决定。

在这个基础上，再引入 ParallelAgent、RoutingAgent、Graph 条件边、A2A 或 Nacos，复杂度才是可控增长，而不是把一个不可预测的大 Agent 拆成一群不可预测的小 Agent。

参考资料

Spring 事务传播机制：REQUIRED、REQUIRES_NEW 与嵌套事务工程实践

Fri, 17 Jul 2026 00:00:00 +0800

业务代码里最容易“看起来对、跑起来却不对”的一类问题，就是 事务边界。方法上贴了 @Transactional，并不等于“想回滚就一定回滚、想独立提交就一定独立提交”。真正决定行为的，是 传播行为（propagation）、物理事务 vs 逻辑事务、以及 Spring 默认的 代理拦截模型。

本文基于 Spring Framework 官方事务文档，把 REQUIRED / REQUIRES_NEW / NESTED 等传播语义、回滚规则与常见工程踩坑讲清楚，并给出可落地的写法与排查清单。

一、先分清：物理事务 vs 逻辑事务

Spring 管理事务时，不能只看“有没有 @Transactional”，而要区分两层：

概念	含义	工程直觉
物理事务（physical）	底层资源上真正开启的事务（如一条 JDBC Connection 上的 `begin/commit/rollback`）	能不能真正提交/回滚、锁何时释放
逻辑事务（logical）	每个被 Spring 事务拦截的方法作用域	该方法能否单独标记 `rollback-only`

传播行为决定的是：外层方法与内层方法之间，逻辑作用域如何映射到物理事务。
这正是很多“内层抛异常后外层还以为自己 commit 成功了”的根源。

二、七种传播行为速查

@Transactional(propagation = …) 对应 TransactionDefinition 中的常量。按“有没有外层事务”理解最稳：

传播行为	无外层事务时	有外层事务时	典型用途
`REQUIRED`（默认）	新建物理事务	加入外层同一物理事务	服务门面 + 多仓储同事务
`SUPPORTS`	非事务执行	加入外层事务	查询既可独立也可参与写事务
`MANDATORY`	抛异常	加入外层事务	强制调用方必须已开事务
`REQUIRES_NEW`	新建物理事务	挂起外层，新建独立物理事务	审计日志、独立提交的状态点
`NOT_SUPPORTED`	非事务执行	挂起外层，非事务执行	长耗时/远程调用不想占连接
`NEVER`	非事务执行	抛异常	明确禁止在事务中调用
`NESTED`	等同 `REQUIRED` 新建	同一物理事务内建 savepoint	内层可局部回滚，外层可继续

日常工程里真正高频的是：REQUIRED、REQUIRES_NEW、NESTED。下面展开它们的语义差异。

三、REQUIRED：默认正确，但要懂 UnexpectedRollbackException

1. 语义

PROPAGATION_REQUIRED 会 强制存在物理事务：

当前没有事务 → 为本方法新建；
已有外层事务 → 参与该外层物理事务（同一连接、同一提交点）。

这很适合：一个 Service 编排多个 Repository，要求“要么一起成功，要么一起失败”。

2. 逻辑作用域仍是独立的

即便映射到同一物理事务，Spring 仍会为每个 REQUIRED 方法创建 逻辑事务作用域。每个作用域可以独立设置 rollback-only。

关键后果（官方明确描述）：

内层逻辑事务标记了 rollback-only；
外层自己没有决定回滚，仍尝试 commit；
物理事务最终回滚，外层会收到 UnexpectedRollbackException。

这不是“Spring 抽风”，而是保护调用方 绝不能误以为已经提交成功。

3. 内层 isolation / timeout / readOnly 默认会被忽略

参与外层事务时，内层声明的隔离级别、超时、只读标志 默认静默忽略，以外层特征为准。
若希望“内层要求与外层不一致时直接失败”，可在事务管理器上打开 validateExistingTransaction=true（非宽松模式也会拒绝只读/读写不匹配）。

// 伪配置示意：开启后，内层 isolation/readOnly 与外层冲突会拒绝加入
// PlatformTransactionManager 具体实现上设置 validateExistingTransaction = true

四、REQUIRES_NEW：真正的“独立事务”

1. 语义

PROPAGATION_REQUIRES_NEW 总是开启独立物理事务：

有外层事务 → 挂起外层，内层用新资源事务；
内层 commit/rollback 不影响外层事务的提交结果；
内层结束后，其持有的锁会尽快释放；
内层可使用自己的 isolation / timeout / readOnly。

2. 适合什么

操作日志 / 审计记录：业务主事务回滚，日志仍要留下；
状态机“已到达某检查点”的独立落库；
需要更短锁持有时间、且允许与外层最终结果不一致的写路径。

3. 连接池风险（必须重视）

官方明确警告：外层事务仍绑定着资源时，内层还要再拿 新的数据库连接。若连接池偏小，可能出现：

连接池耗尽；
多线程都在外层事务中等待内层连接 → 死锁式等待。

实践建议：

连接池最大连接数要 大于并发线程数（官方表述：至少比并发线程数多 1，实际应按峰值嵌套深度留余量）；
不要在循环体里高频 REQUIRES_NEW；
先问自己：真的需要“独立提交”，还是只是想“内层失败不要拖死外层”——后者可能 NESTED 更合适。

@Service
public class OrderService {

 private final AuditService auditService;
 private final OrderRepository orderRepository;

 @Transactional // 默认 REQUIRED
 public void placeOrder(OrderCmd cmd) {
 Order order = orderRepository.save(Order.create(cmd));
 // 审计希望独立提交：业务失败也不丢“尝试下单”痕迹
 auditService.recordAttempt(order.getId(), "PLACE_ORDER");
 // ... 后续业务可能抛异常导致外层回滚
 orderRepository.markPaid(order.getId());
 }
}

@Service
public class AuditService {

 @Transactional(propagation = Propagation.REQUIRES_NEW)
 public void recordAttempt(Long orderId, String action) {
 // 独立物理事务：这里的提交不会被外层回滚“带走”
 }
}

五、NESTED：同一物理事务上的 savepoint

1. 语义

PROPAGATION_NESTED：

一个物理事务；
内层通过 savepoint（保存点） 支持局部回滚；
内层回滚到 savepoint 后，外层仍可继续并最终 commit/rollback。

它通常映射到 JDBC savepoint，因此：

依赖 JDBC 资源事务；
与 DataSourceTransactionManager 一类管理器配合最常见；
不是所有事务管理器/资源都支持嵌套语义。

2. 与 REQUIRES_NEW 的选型

维度	`REQUIRES_NEW`	`NESTED`
物理事务	独立两条	仍是一条
内层回滚	不影响外层提交决策	只回滚到 savepoint，外层可继续
内层提交可见性	内层结束即可对外可见（独立提交）	仍受外层最终 commit 约束
连接占用	可能额外占连接	一般不另开连接
资源支持	广泛	依赖 savepoint 支持

口诀：

要“内层 真正提交，外层怎么回滚都保留” → REQUIRES_NEW；
要“内层失败可局部撤销，但最终仍跟外层同生共死” → NESTED。

六、回滚规则：默认只认 RuntimeException / Error

声明式事务的默认策略（官方 @Transactional 默认值）：

传播：REQUIRED
隔离：ISOLATION_DEFAULT（交给底层数据源默认）
读写：可写
超时：底层默认 / 无
回滚触发：RuntimeException 与 Error
默认不回滚：受检异常（checked Exception）

这解释了一个经典坑：业务方法 throws BusinessException extends Exception，调用方 catch 后发现 数据居然提交了。

可显式配置：

@Transactional(rollbackFor = Exception.class)
public void transfer(Long from, Long to, long amount) throws BusinessException {
 // 受检业务异常也会触发回滚
}

@Transactional(noRollbackFor = InventoryNotEnoughException.class)
public void reserveStock(Long skuId, int n) {
 // 某些“预期内”的运行时异常不希望回滚时使用（务必非常克制）
}

也可在 catch 后程序化标记：

try {
 // ...
} catch (NoProductInStockException ex) {
 TransactionAspectSupport.currentTransactionStatus().setRollbackOnly();
}

官方仍建议优先用声明式 rollbackFor / noRollbackFor，少用手写 setRollbackOnly()。

七、代理模型：自调用为什么“注解失效”

默认 proxy 模式（非 AspectJ 编织）下：

只有 通过代理进来的外部调用 才会被拦截；
同类自调用（this.otherTxMethod()）不会走代理 → 内层 @Transactional 不生效；
初始化阶段（如 @PostConstruct）也不应依赖事务代理；
Spring Framework 6.0 起，基于类的代理默认可对 protected / 包可见方法生效；但 基于接口的 JDK 代理 仍要求方法在接口中且为 public。

@Service
public class PayService {

 @Transactional
 public void pay(Long id) {
 // 错误：自调用，markPaid 上的 REQUIRES_NEW 不会生效
 this.markPaid(id);
 }

 @Transactional(propagation = Propagation.REQUIRES_NEW)
 public void markPaid(Long id) {
 // ...
 }
}

常见修法：

把需要独立传播的方法拆到 另一个 Spring Bean，通过注入调用；
注入自身代理（@Lazy 自注入 / AopContext.currentProxy()，后者需暴露代理）；
切换到 AspectJ 模式（成本更高，团队要统一约定）。

八、可复现的排查清单

当“事务行为不符合预期”时，按下面顺序收敛：

是不是自调用？ 打断点看调用栈是否经过 TransactionInterceptor。
异常类型是否触发默认回滚？ checked vs runtime；是否被上层吞掉。
传播是否是你以为的那个？ REQUIRED 加入外层 ≠ REQUIRES_NEW 独立提交。
是否出现 UnexpectedRollbackException？ 说明内层已 rollback-only，外层还在 commit。
连接池是否在 REQUIRES_NEW 下打满？ 看获取连接耗时与 active connections。
只读事务是否被误用于写？ 以及是否开启了 validateExistingTransaction。
多数据源 / 非 DataSourceTransactionManager 场景 下 NESTED 是否根本不被支持。

最小实验建议（单测或本地）：

场景 A：outer REQUIRED → inner REQUIRED 抛 RuntimeException
 期望：整体回滚；外层若吞异常仍可能 UnexpectedRollbackException

场景 B：outer REQUIRED → inner REQUIRES_NEW 成功后 outer 回滚
 期望：inner 已提交数据仍在；outer 变更回滚

场景 C：同类 this.inner() 且 inner 标 REQUIRES_NEW
 期望（proxy 默认）：inner 注解不生效，与 outer 同一逻辑路径

九、工程建议（可直接落到 Code Review）

默认用 REQUIRED，不要到处 REQUIRES_NEW。
REQUIRES_NEW 只用于“必须独立提交”的窄路径，并评估连接池。
需要局部回滚且最终仍同事务提交 → 优先评估 NESTED，并确认 JDBC savepoint 支持。
业务异常若走 checked，统一 rollbackFor = Exception.class 或统一业务异常基类为 runtime。
事务边界放在 应用服务层，Repository 保持细粒度；避免 Controller 直接开事务导致边界失控。
长耗时远程调用不要包在大事务里；必要时 NOT_SUPPORTED 或先缩短事务再调外部。
Code Review 必问：谁提交？谁回滚？失败时用户看到的状态与 DB 是否一致？

十、总结

Spring 事务传播不是注解装饰，而是 逻辑作用域如何映射到物理资源事务 的规则：

REQUIRED：共享物理事务，内层 rollback-only 会拖垮外层提交预期；
REQUIRES_NEW：独立物理事务，能独立提交，但要付连接与一致性代价；
NESTED：同一物理事务上的 savepoint，适合“局部失败、整体仍可继续”的路径；
回滚默认只盯 RuntimeException/Error；
代理模式下 自调用不走事务拦截。

把这五件事吃透，线上大部分“事务没生效 / 该回没回 / 不该提交却提交”的问题都能快速定位。

参考资料

Spring Framework Reference — Transaction Propagation（REQUIRED / REQUIRES_NEW / NESTED 语义与 UnexpectedRollbackException、连接池警告）
Spring Framework Reference — Rolling Back a Declarative Transaction（默认 RuntimeException/Error 回滚、rollbackFor/setRollbackOnly）
Spring Framework Reference — Using @Transactional（默认传播/隔离/回滚规则、proxy 自调用限制、可见性）
Spring Framework Javadoc — TransactionDefinition（七种 PROPAGATION_* 常量定义）

Spring Framework 7.0.8 紧急安全更新：修复 16 个高危漏洞

Sun, 12 Jul 2026 00:00:00 +0800

背景介绍

Spring 官方在最新发布的 Spring Framework 7.0.8 中，一次性修复了多达 16 个 CVE 安全漏洞。这次更新被称为“AI 时代的 Spring 与安全”系列更新的一部分，修复了包括预测会话 ID、拒绝服务（DoS）、跨站脚本（XSS）、服务器端请求伪造（SSRF）以及不安全的反序列化在内的众多高危问题。

对于所有使用 Spring Framework 的企业和开发者来说，这是一次必须立即跟进的紧急维护版本。

核心漏洞清单与原理

本次 7.0.8 版本修复了大量集中在 Spring MVC、WebFlux 和 SpEL (Spring Expression Language) 模块中的安全问题：

1. Web 模块核心漏洞 (MVC & WebFlux)

CVE-2026-41838：WebSocket 模块中会话 ID 可预测问题。
CVE-2026-41839 / 41840：WebFlux 中的会话固定提权与多部分请求（Multipart）拒绝服务。
CVE-2026-41841 / 41842 / 41843：涉及 Spring MVC 和 WebFlux 的静态资源缓存信息泄露、版本化资源拒绝服务以及路径遍历漏洞。
CVE-2026-41844：Spring MVC 和 WebFlux 开放重定向问题。

2. SpEL 表达式注入与安全限制

CVE-2026-41850 / 41851：通过 SpEL 表达式导致的算法拒绝服务及无界缓存造成的拒绝服务。
CVE-2026-41852：SpEL 表达式中的任意方法调用漏洞，这通常是最高危的远程代码执行（RCE）的前置条件。

3. 其他关键组件

CVE-2026-41854：通过 UriComponentsBuilder 触发的服务器端请求伪造 (SSRF)。
CVE-2026-41855：Jackson JMS Converters 存在的不安全反序列化漏洞。

影响评估

如果你正在使用低于 7.0.8 的 Spring Framework 版本（或对应的 Spring Boot 版本），并启用了上述相关功能（如 WebFlux、WebSocket、SpEL 解析外部输入、静态资源服务），你的应用将面临严重的信息泄露、拒绝服务甚至系统被控风险。

特别是对外暴露 Web 端口、接受 Multipart 文件上传或者使用 SpEL 处理动态规则的业务系统，受影响最为直接。

实践建议与修复指南

1. 立即升级依赖

在你的 pom.xml 或 build.gradle 中，将 Spring Framework 的版本强制指定或升级到 7.0.8：

<properties>
 <spring-framework.version>7.0.8</spring-framework.version>
</properties>

如果使用的是 Spring Boot，请密切关注对应 Spring Boot 的最新补丁版本（如 3.5.x 系列的最新安全补丁），因为 Spring Boot 通常会同步打包最新版本的 Spring Framework。

2. 检查危险 API 的使用

除了升级依赖，团队应排查代码库中对以下 API 的直接调用，确保输入被正确校验：

UriComponentsBuilder 构建外部传入的 URL 时的 SSRF 防护。
业务逻辑中涉及的 SpEL 解析，严禁将未经净化的用户输入作为表达式内容执行。

3. 关闭不必要的静态资源服务

如果你的 Spring 应用只是一个纯后端 API 服务，建议彻底关闭静态资源服务和相关的缓存配置，以减少攻击面。

总结

Spring Framework 7.0.8 的发布不仅是一次常规维护，更是针对 16 项关键 CVE 的集体阻击。在网络安全威胁日益复杂的今天，保持依赖的及时更新是系统最基础的防线。建议所有开发与运维团队尽快排查影响范围并在测试环境中验证升级。

参考资料

Spring Data 2025.0.13 收官发布：3.5.x 项目升级与迁移检查清单

Wed, 01 Jul 2026 01:15:51 +0000

Spring Data 2025.0.13 已经发布。对还在 Spring Boot 3.5.x / Spring Data 3.5.x 线上分支上的团队来说，这不是一个“追新功能”的版本，而更像一次收尾性质的维护窗口：官方发布说明明确提到，2025.0.13 是 Spring Data 3.5.x generation 预期的最后一个开源服务版本，并且只包含回归修复。换句话说，如果你的系统还停留在这一代，短期内应该尽快吸收这个补丁；中期则应该把迁移到 2025.1.x / 4.x 系列纳入排期。

本文用工程实践的角度梳理：这次发布意味着什么、哪些模块值得重点回归、Maven/Gradle 应该怎么升级，以及团队应该怎样规划下一阶段迁移。

这次发布的关键信息

先把核心事实讲清楚：

Spring Data BOM 版本：2025.0.13。
发布时间：GitHub Release 显示为 2026-06-24T07:40:08Z。
发布性质：服务版本，主要面向回归修复。
官方博客说明：它预期是 Spring Data 3.5.x generation 的最后一个开源发布版本。
官方建议：尽早升级到最新的 4.0.x（2025.1.x release train）或 4.1.x release。
Spring 官方博客还说明，Spring Boot 3.5.16 计划在次日拾取这次 Spring Data 发布。

这几个信息放在一起，结论很直接：2025.0.13 适合作为 Spring Boot 3.5.x 项目的稳定补丁基线，但不应该被当作长期停留点。

2025.0.13 包含哪些模块

Spring Data 使用 release train / BOM 管理一组子项目版本。2025.0.13 对应的参与模块包括：

模块	对应版本	常见使用场景
Spring Data Commons	3.5.13	Repository 抽象、分页、排序、映射基础设施
Spring Data JPA	3.5.13	JPA / Hibernate 持久化
Spring Data MongoDB	4.5.13	MongoDB 文档数据库访问
Spring Data Redis	3.5.13	Redis 数据访问与缓存相关集成
Spring Data Cassandra	4.5.13	Cassandra 数据访问
Spring Data Elasticsearch	5.5.13	Elasticsearch 数据访问
Spring Data Couchbase	5.5.13	Couchbase 数据访问
Spring Data Neo4j	7.5.13	图数据库访问
Spring Data REST	4.5.13	Repository REST 暴露
Spring Data Relational	3.5.13	JDBC / R2DBC 等关系型访问基础
Spring Data LDAP	3.5.13	LDAP 数据访问
Spring Data KeyValue	3.5.13	Key-Value 抽象支持

如果你的项目通过 Spring Boot 管理依赖，多数情况下不需要手工声明这些子模块版本；跟随 Spring Boot 3.5.16 或显式导入 spring-data-bom:2025.0.13 即可。

值得关注的修复点

这次发布不是大版本功能升级，重点是降低已知回归风险。官方 Release 中比较值得应用开发团队关注的点包括下面几类。

1. Spring Data Commons：字段解析相关修复

Spring Data Commons 3.5.13 修复了 TypeDiscoverer 在子类字段与父类同名字段场景下的解析问题。Release 描述中提到：

保留子类字段，而不是被父类中被遮蔽的字段覆盖。
修复属性类型从隐藏的父类字段解析，而不是从子类字段解析的问题。

这类问题通常不会影响简单 Entity，但在下面这些场景里更容易踩坑：

领域模型存在继承层次；
子类重新声明了父类中的同名字段；
Repository 查询、投影、映射元数据依赖属性类型推断；
代码生成或历史模型导致字段命名不够干净。

如果你的项目里有复杂继承模型，升级后建议重点跑 Repository 查询、DTO 投影、Example 查询、排序分页与自定义转换器相关测试。

2. Spring Data JPA：JPQL / EQL 单字符字符串解析修复

Spring Data JPA 3.5.13 修复了 JPQL 和 EQL 中集合成员表达式的单字符字符串字面量解析问题。Release 中提到的问题是：单字符字符串字面量作为 MEMBER OF 左操作数时解析失败。

受影响的代码可能长得类似下面这样：

@Query("select u from User u where 'A' member of u.flags")
List<User> findUsersWithFlagA();

实际项目中未必完全使用这个写法，但如果你有：

手写 @Query；
动态拼接 JPQL / HQL；
使用集合属性做成员判断；
查询中存在单字符枚举值或标记值；

就应该把这些查询纳入回归测试。

3. Spring Data JPA：Hibernate 依赖升级

Spring Data JPA 3.5.13 的 Release 还列出了 Hibernate 升级到 6.6.53.Final。这通常是好事，但 ORM 层升级也最容易暴露边界行为差异，例如：

SQL 生成变化；
方言兼容性差异；
延迟加载与关联抓取问题；
Criteria / JPQL 解析差异；
数据库驱动与 Hibernate 方言组合问题。

因此，JPA 项目升级时不要只跑单元测试，最好至少补一轮连接真实数据库的集成测试。

Maven 项目怎么升级

如果你的项目使用 Spring Boot 3.5.x，并通过 spring-boot-starter-parent 管理版本，推荐优先升级 Spring Boot 到包含该 Spring Data 版本的补丁版本，例如 Spring Boot 3.5.16：

<parent>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-parent</artifactId>
 <version>3.5.16</version>
 <relativePath/>
</parent>

如果项目不能立刻升级 Spring Boot，但确实需要单独锁定 Spring Data release train，可以在 dependencyManagement 中导入 BOM：

<dependencyManagement>
 <dependencies>
 <dependency>
 <groupId>org.springframework.data</groupId>
 <artifactId>spring-data-bom</artifactId>
 <version>2025.0.13</version>
 <scope>import</scope>
 <type>pom</type>
 </dependency>
 </dependencies>
</dependencyManagement>

不过要注意：Spring Boot 自身也会管理 Hibernate、数据库驱动、Spring Framework 等版本。单独覆盖 Spring Data BOM 虽然可行，但更容易形成“局部升级、整体依赖矩阵未验证”的状态。生产项目优先选择 Spring Boot 补丁版本，通常更稳。

Gradle 项目怎么升级

使用 Spring Boot Gradle 插件的项目，最简单的方式同样是升级 Boot 版本：

plugins {
 id("org.springframework.boot") version "3.5.16"
 id("io.spring.dependency-management") version "1.1.7"
 java
}

如果需要显式导入 Spring Data BOM，可以这样写：

dependencyManagement {
 imports {
 mavenBom("org.springframework.data:spring-data-bom:2025.0.13")
 }
}

升级后建议运行依赖树检查，确认最终解析出来的版本符合预期：

./gradlew dependencyInsight --dependency spring-data-commons --configuration runtimeClasspath
./gradlew dependencyInsight --dependency spring-data-jpa --configuration runtimeClasspath
./gradlew dependencyInsight --dependency hibernate-core --configuration runtimeClasspath

Maven 项目可以用：

./mvnw dependency:tree -Dincludes=org.springframework.data
./mvnw dependency:tree -Dincludes=org.hibernate.orm:hibernate-core

升级前后的回归检查清单

建议把这次升级当作一次低风险但必须验证的维护发布。可以按下面顺序做。

升级前

记录当前 Spring Boot、Spring Data、Hibernate、数据库驱动版本。
确认项目是否手工覆盖过 spring-data-* 或 Hibernate 版本。
找出所有自定义 Repository、@Query、Specification、Querydsl、Criteria 查询。
标记有继承结构的 Entity / Document / Projection。
准备真实数据库或测试容器环境，而不是只跑 mock 测试。

升级后

运行完整单元测试与集成测试。
对核心 Repository 做 CRUD、分页、排序、复杂条件查询回归。
对 JPA 项目检查启动日志中的 Hibernate 版本与 SQL 方言。
对 MongoDB / Redis / Elasticsearch 项目检查连接、序列化与索引相关逻辑。
使用 dependency:tree 或 dependencyInsight 确认没有混入旧版本 Spring Data 模块。
在预发环境跑一轮真实流量或关键任务。

为什么不要长期停留在 2025.0.x

官方已经把 2025.0.13 定位为 3.5.x generation 预期的最后一个开源服务版本，这意味着后续开源补丁会转向更新的 release train。对企业项目来说，这通常带来三个影响：

安全与兼容性窗口变窄：依赖链上的修复会优先进入新分支。
升级跨度变大：越晚迁移到 2025.1.x / 4.x，累计变化越多，单次升级风险越高。
生态同步成本上升：Spring Boot、Spring Framework、Hibernate、数据库驱动、云原生组件都会继续演进。

因此更合理的策略是：

短期：把 3.5.x 项目升级到 2025.0.13 / Boot 3.5.16，拿到最后一批回归修复。
中期：建立 2025.1.x 或 4.x 的兼容性分支，跑依赖树和自动化测试。
长期：把主要业务线迁移到新的 Spring Boot / Spring Data 主线，减少历史分支维护成本。

团队落地建议

如果你负责一个线上 Spring 项目，可以按下面的节奏推进：

先做补丁升级：在当前主线或维护分支升级到 Spring Boot 3.5.16，或至少导入 Spring Data BOM 2025.0.13。
锁定验证范围：重点测试 Repository、JPA 查询、继承模型、MongoDB/Redis 序列化、Elasticsearch 查询。
保留依赖快照：把升级前后的依赖树保存到 CI 产物或变更单，方便排查回滚。
预留迁移分支：不要等到必须升级时才看 2025.1.x / 4.x，提前建分支验证编译、启动和关键链路。
避免局部硬覆盖：除非有明确原因，否则不要长期手工覆盖 Spring Data 子模块版本，让 Spring Boot BOM 统一管理更安全。

小结

Spring Data 2025.0.13 的价值不在于新特性，而在于给 3.5.x generation 一个相对稳妥的收尾版本。对生产系统来说，这类版本往往比“功能发布”更值得及时处理：它能减少已知回归风险，也给后续迁移到 2025.1.x / 4.x 留出缓冲。

如果你的系统还在 Spring Boot 3.5.x，建议尽快完成补丁升级与回归验证；如果你已经准备进入 Spring Boot 4 / Spring Data 4.x 阶段，则可以把 2025.0.13 当作维护分支的最后稳定基线，同时把主要精力放到下一代 release train 的兼容性验证上。

Spring AI 2.0 结构化输出实战：让大模型返回可验证的 Java 对象

Tue, 30 Jun 2026 01:15:52 +0000

在企业应用里，调用大模型最怕的不是“它会说错话”，而是下游系统把一段不稳定的自然语言当成了稳定数据：少一个字段、数组变成字符串、JSON 外面多一段解释，都可能让订单流转、风控判断、知识库入库或自动化工单发生不可预期的问题。

Spring AI 2.0 围绕结构化输出补上了两个很实用的工程开关：一个是在响应回来后做 schema 校验并自动重试的 validateSchema()，另一个是尽量使用模型供应商原生结构化输出能力的 useProviderStructuredOutput()。这篇文章把官方博客和参考文档整理成一份中文实战指南，重点讲清楚：什么时候用、怎么接入、哪些坑需要提前规避。

一、结构化输出解决的到底是什么问题

普通聊天接口返回的是文本。文本适合展示给人看，却不适合直接交给业务代码做分支判断。例如你希望模型返回演员和电影列表：

record ActorsFilms(String actor, List<String> movies) {}

如果模型严格返回：

{"actor":"Tom Hanks","movies":["Forrest Gump","Cast Away"]}

业务代码就能很自然地反序列化为 ActorsFilms。但真实模型输出经常会变成：

当然可以，下面是结果：
```json
{"actor":"Tom Hanks","movies":["Forrest Gump","Cast Away"]}


或者字段名、类型、嵌套结构发生漂移。Spring AI 的结构化输出能力，就是把“提示模型按格式回答”和“把回答转换成 Java 类型”封装进框架，让应用更接近普通 Java 对象编程，而不是到处写字符串解析逻辑。

## 二、最基础的用法：`.entity(...)`

在 Spring AI 的 `ChatClient` 中，最直接的结构化输出入口是 `.entity(...)`。它只适用于 `.call()` 同步调用链，因为类型转换需要拿到完整响应；流式 `.stream()` 返回的是文本片段，不能直接在流上变成对象。

```java
record ActorsFilms(String actor, List<String> movies) {}

ActorsFilms films = chatClient.prompt()
 .user("Generate the filmography for a random actor.")
 .call()
 .entity(ActorsFilms.class);

System.out.println(films.actor());
System.out.println(films.movies());

背后大致会发生三件事：

Spring AI 根据目标 Java 类型生成 JSON Schema；
框架把格式要求加入提示词，让模型尽量按 schema 返回；
返回文本再交给 converter 转换成目标 Java 对象。

官方参考文档也明确提醒：这种方式本质上是 best effort。模型并不一定总能按要求返回结构化数据，所以生产环境不能只停留在“能跑通一次 demo”。

三、Spring AI 2.0 的第一个关键开关：`validateSchema()`

validateSchema() 解决的是响应侧校验与自修复问题。模型先正常回答，Spring AI 再用 schema 校验结果。如果校验失败，框架会把具体错误追加进下一轮请求，让模型基于错误信息重新生成，默认最多尝试 3 次。

ActorsFilms films = chatClient.prompt()
 .user("Generate the filmography for a random actor.")
 .call()
 .entity(ActorsFilms.class, spec -> spec.validateSchema());

这比简单地“失败后再问一次”更可靠，因为第二次请求不是盲目重试，而是带着类似“缺少 required 字段 actor”“movies 期望 array 但收到 string”这样的校验反馈。

对业务代码来说，它的价值主要体现在三类场景：

返回对象会直接入库；
返回字段会影响自动化流程分支；
错误结构不会立刻报错，但会在后续链路中造成隐性数据污染。

如果默认 3 次不够，也可以显式注册 StructuredOutputValidationAdvisor 调整重试次数：

var validationAdvisor = StructuredOutputValidationAdvisor.builder()
 .outputType(ActorsFilms.class)
 .maxRepeatAttempts(5)
 .build();

ChatClient chatClient = ChatClient.builder(chatModel)
 .defaultAdvisors(validationAdvisor)
 .build();

需要注意：重试会增加延迟和 token 消耗，所以它适合关键链路，而不一定适合所有只用于展示的回答。

四、第二个关键开关：`useProviderStructuredOutput()`

validateSchema() 是“回来以后再检查”，而 useProviderStructuredOutput() 是“请求时就告诉供应商按结构化输出约束执行”。官方博客说明，Spring AI 2.0 支持把结构化输出 schema 通过模型供应商的 API 级能力发送出去，而不是只把格式要求塞进 prompt。

ActorsFilms films = chatClient.prompt()
 .user("Generate the filmography for a random actor.")
 .call()
 .entity(ActorsFilms.class, spec -> spec.useProviderStructuredOutput());

这样做通常有三个好处：

system prompt 不再需要携带冗长 JSON 格式说明；
schema 通过供应商 API 字段传递，约束更靠近模型运行时；
对支持原生结构化输出的模型，格式稳定性通常更好。

截至 Spring AI 2.0 官方说明，支持面包括 OpenAI、Anthropic、Google GenAI、Mistral AI，以及按模型能力区分的 Ollama。Spring AI 会检查当前 chat options 是否实现 StructuredOutputChatOptions；如果不支持，这个开关会回退到基于 prompt 的默认方式，而不是强行让请求失败。

五、生产建议：两个开关一起用

如果你的下游系统不能容忍结构漂移，推荐把两个开关组合起来：

ActorsFilms films = chatClient.prompt()
 .user("Generate the filmography for a random actor.")
 .call()
 .entity(ActorsFilms.class, spec -> spec
 .useProviderStructuredOutput()
 .validateSchema());

可以把它理解成两道防线：

useProviderStructuredOutput() 尽量在模型供应商侧减少非法输出；
validateSchema() 兜住供应商边界、模型差异和偶发异常。

这在“AI 结果要进入真实业务系统”的场景尤其重要，例如：

从客服对话中抽取投诉类型、订单号、处理建议；
从运维日志中归类故障级别和可能根因；
从合同文本中抽取主体、金额、日期、责任条款；
让智能体生成下一步工具调用参数前，先产出稳定中间对象。

如果只是把回答展示给用户阅读，单独使用 .content() 也可以；但只要结果要被程序消费，就应该优先考虑结构化输出。

六、泛型类型：`ParameterizedTypeReference`

.entity(Class) 适合普通类或 record。遇到 List<ActorsFilms>、Map<String, ActorsFilms> 这类泛型结构时，需要使用 ParameterizedTypeReference：

List<ActorsFilms> films = chatClient.prompt()
 .user("Generate filmographies for three random actors.")
 .call()
 .entity(new ParameterizedTypeReference<List<ActorsFilms>>() {});

同样可以追加参数配置：

List<ActorsFilms> films = chatClient.prompt()
 .user("Generate filmographies for three random actors.")
 .call()
 .entity(
 new ParameterizedTypeReference<List<ActorsFilms>>() {},
 spec -> spec.validateSchema()
 );

这里有一个重要兼容性坑：OpenAI 的 Structured Outputs API 不接受顶层数组。如果你在 OpenAI 上把 List<...> 和 useProviderStructuredOutput() 组合使用，可能会失败。更稳妥的方式是包一层 record：

record FilmographyList(List<ActorsFilms> films) {}

FilmographyList result = chatClient.prompt()
 .user("Generate filmographies for three random actors.")
 .call()
 .entity(FilmographyList.class, spec -> spec.useProviderStructuredOutput());

这也是面向多供应商开发时的通用经验：不要只按某一个模型的宽松行为设计数据结构，最好用显式对象包住列表、分页、错误码和元信息。

七、需要原始响应时，用 `.responseEntity(...)`

.entity(...) 只返回转换后的业务对象。如果你还需要 token 用量、模型元数据或原始 ChatResponse，可以使用 .responseEntity(...)：

ResponseEntity<ChatResponse, ActorsFilms> result = chatClient.prompt()
 .user("Generate the filmography for a random actor.")
 .call()
 .responseEntity(ActorsFilms.class);

ActorsFilms films = result.entity();
ChatResponse raw = result.response();
long totalTokens = raw.getMetadata().getUsage().getTotalTokens();

这对可观测性很有帮助。建议在生产系统中至少记录：模型名称、token 用量、重试次数、结构化校验是否失败过，以及最终转换耗时。这样当成本或延迟异常时，才能定位到底是模型调用慢、schema 过复杂，还是自修复重试过多。

八、内置 converter 与自定义 converter

Spring AI 参考文档列出了多个 converter，包括：

BeanOutputConverter<T>：把模型输出转换成指定 Java 类或 ParameterizedTypeReference，并使用符合 JSON Schema DRAFT_2020_12 的 schema；
MapOutputConverter：把 RFC8259 JSON 响应转换成 Map<String, Object>；
ListOutputConverter：面向逗号分隔列表输出转换；
AbstractConversionServiceOutputConverter 与 AbstractMessageOutputConverter：给更底层的转换扩展使用。

最常用的是 BeanOutputConverter。不过它也比较严格：如果模型在 JSON 前后加了解释文字，默认转换可能失败。对于历史模型、非原生结构化输出模型，或者你确实要兼容带代码块的 JSON，可以写一个轻量自定义 converter，先提取 JSON，再交给默认 converter：

public class LenientJsonOutputConverter<T> implements StructuredOutputConverter<T> {

 private static final Pattern FENCE = Pattern.compile("```(?:json)?\\s*([\\s\\S]*?)```");

 private final BeanOutputConverter<T> delegate;

 public LenientJsonOutputConverter(Class<T> targetType) {
 this.delegate = new BeanOutputConverter<>(targetType);
 }

 @Override
 public String getFormat() {
 return delegate.getFormat();
 }

 @Override
 public String getJsonSchema() {
 return delegate.getJsonSchema();
 }

 @Override
 public T convert(String source) {
 var matcher = FENCE.matcher(source);
 String json = matcher.find() ? matcher.group(1).trim() : source.trim();
 return delegate.convert(json);
 }
}

但要谨慎：宽松 converter 适合清理“JSON 外壳”，不应该悄悄吞掉业务字段错误。字段缺失、类型错误、枚举值非法，仍然应该交给 schema 校验或业务校验处理。

九、流式调用怎么处理结构化输出

Spring AI 文档说明，ChatClient 支持同步和流式模型。流式 .stream() 可以拿到 Flux<String> 或 Flux<ChatResponse>，但目前如果想把流式内容转成 Java 对象，需要先聚合完整文本，再显式调用结构化输出 converter。

示意代码如下：

var converter = new BeanOutputConverter<>(
 new ParameterizedTypeReference<List<ActorsFilms>>() {}
);

Flux<String> flux = chatClient.prompt()
 .user(u -> u.text("""
 Generate the filmography for a random actor.
 {format}
 """).param("format", converter.getFormat()))
 .stream()
 .content();

String content = flux.collectList()
 .block()
 .stream()
 .collect(Collectors.joining());

List<ActorsFilms> actorFilms = converter.convert(content);

如果你的业务既要“边生成边展示”，又要“最终写入结构化结果”，建议分成两个阶段：展示阶段走流式文本，落库阶段再触发一次非流式结构化调用，或者在流式完成后对完整文本做显式转换与校验。

十、工程落地清单

把 Spring AI 2.0 结构化输出接入生产系统时，可以按下面这份清单检查：

先定义稳定 DTO/record：字段名、类型、是否可为空要明确，不要把自然语言描述塞进一个大字符串字段里。
关键链路启用 validateSchema()：尤其是结果会入库、调用工具、影响流程分支的场景。
供应商支持时启用 useProviderStructuredOutput()：但要确认当前模型和 options 是否真的支持原生结构化输出。
避免顶层数组作为跨供应商公共协议：用包装 record 承载列表、分页和元信息。
记录观测指标：包括模型、token、耗时、重试次数、转换失败原因。
保留业务校验：schema 只能保证形状，不能保证“金额必须大于 0”“日期不能早于合同签署日”这类业务语义。
对失败路径设计降级策略：可以返回人工审核、重试队列、只展示原文，或者切换到更强模型，但不要静默写入脏数据。

总结

Spring AI 2.0 的结构化输出不是一个“让 JSON 更好看”的小功能，而是把大模型结果接入真实 Java 系统的重要基础设施。

.entity(...) 让模型回答直接进入 Java 类型；
validateSchema() 提供响应侧校验与自修复；
useProviderStructuredOutput() 尽量使用供应商原生结构化约束；
ParameterizedTypeReference、.responseEntity(...) 和自定义 converter 则覆盖了泛型、观测和兼容场景。

如果你正在把 LLM 从聊天窗口接进订单、工单、知识库、运维或智能体系统，建议尽早把“结构化输出 + schema 校验 + 业务校验”作为默认架构，而不是等线上出现一次脏数据事故后再补救。

Spring Boot 3.5.16 发布后，团队现在该怎么做：升级、验证与 3.5 生命周期收尾指南

Mon, 29 Jun 2026 15:21:35 +0000

Spring 团队在 2026-06-25 发布了 Spring Boot 3.5.16。如果你还在 3.5.x 线上维护窗口内，这个版本值得关注，因为它不仅是一个常规补丁版，还带着一个更重要的信号：3.5.x 已经来到开源维护周期的最后阶段。

这篇文章不重复官方公告，而是从工程落地角度整理成一份中文操作指南：这次版本到底变了什么、哪些团队应该马上升、升完要验证什么、以及如果你准备继续停留在 3.5 分支，应该怎样安排后续计划。

一、先说结论：3.5.16 是什么性质的版本

根据 Spring 官方博客，Spring Boot 3.5.16 已于 2026-06-25 发布，本次发布包含 3 项依赖升级。同时，官方明确说明它是 3.5.x 代际的最后一个 OSS 发布版本，后续若需要更长周期支持，需要转向商业支持方案。

结合 Spring Boot GitHub Release 与生命周期数据，可以把这个版本理解成：

它是 3.5.x 的收官补丁版本；
它不是一个新特性大版本，而是维护型版本；
对仍在 3.5.x 的团队来说，它很适合作为该分支的最终稳定落点；
如果你们还没有升级到 4.0/4.1，那么现在至少应先把 3.5.x 升到 3.5.16，再规划后续迁移。

二、这次实际更新了什么

从 Spring Boot 3.5.16 的 GitHub Release 页面可以确认，本次补丁版包含 3 个依赖升级：

Spring AMQP 3.2.12
Spring Data BOM 2025.0.13
Spring Integration 6.5.10

这说明 3.5.16 的核心价值并不是引入新的框架行为，而是：

对 3.5 代际已纳入管理的依赖做最后一轮维护性更新；
尽量把生态内相关模块收敛到更稳定的补丁位；
给仍在 3.5 线上运行的项目提供一个更明确的“最终补丁基线”。

如果你的应用显式或隐式使用了以下能力，建议优先升级并回归：

RabbitMQ / Spring AMQP 消息处理；
Spring Data 相关持久层能力；
Spring Integration 驱动的集成流、适配器或消息编排。

三、为什么这个版本值得今天就处理

很多团队看到“只有 3 个依赖升级”时，容易觉得可以先放一放。但从维护节奏上看，这次比功能变化更重要的是支持窗口变化。

生命周期数据表明：

Spring Boot 3.5 首次发布时间为 2025-05-31；
3.5.x 的 OSS 支持截止日期为 2026-06-30；
商业支持可延长到 2032-06-30；
截至校验时，3.5 分支最新版本就是 3.5.16（2026-06-25）。

这意味着什么？

1）你还在 3.5.x，就应该把 3.5.16 当成收官版看待

后续即便应用继续稳定运行，也不能再默认期待有新的公开补丁不断跟进。对生产团队来说，落在最后一个 OSS 补丁版本上，比停留在更早的 3.5.x 小版本上更稳妥。

2）升级 3.5.16 和规划下一跳，是两件要并行做的事

正确做法不是“反正马上要升 4.x，就不升 3.5.16 了”，而是：

短期：先把生产基线更新到 3.5.16；
中期：评估是升到 4.0 还是直接跟进 4.1；
长期：决定是否需要商业支持兜底。

因为 3.5.16 是补丁升级，风险通常远低于跨代升级。先完成这一步，可以降低你在迁移前的运行风险。

四、哪些项目应该优先升级

下面几类项目，建议你优先安排升级窗口：

1）仍在长期维护的存量业务系统

如果系统没有立刻升级到 4.x 的资源，但还要持续运行几个月甚至更久，那么停在 3.5.16 是更合理的选择。

2）依赖 Spring Data / Spring Integration / AMQP 的集成型系统

这次补丁直接涉及这些依赖线，消息、数据访问、系统集成相关项目更应该完成回归验证。

3）准备做 3.5 → 4.x 升级演练的团队

先把 3.5 基线统一到 3.5.16，再做跨代升级，排障边界会更清晰。否则你很难分辨问题来自：

旧的 3.5.x 补丁差异；
还是 4.x 的行为变化。

五、怎么升级到 3.5.16

大多数项目只需要改版本号，然后走一次标准构建与回归。

Maven

如果你使用 spring-boot-starter-parent：

<parent>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-parent</artifactId>
 <version>3.5.16</version>
 <relativePath/>
</parent>

如果你使用 Spring Boot BOM：

<dependencyManagement>
 <dependencies>
 <dependency>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-dependencies</artifactId>
 <version>3.5.16</version>
 <type>pom</type>
 <scope>import</scope>
 </dependency>
 </dependencies>
</dependencyManagement>

Gradle

如果你通过 Spring Boot Gradle Plugin 管理版本：

plugins {
 id("org.springframework.boot") version "3.5.16"
 id("io.spring.dependency-management") version "1.1.7"
 kotlin("jvm") version "2.2.0"
}

如果你的项目并不使用 Kotlin 或不需要显式声明这些插件版本，请按你们自己的构建脚本风格调整，核心是把 Spring Boot 版本对齐到 3.5.16。

六、升级后重点验证什么

虽然 3.5.16 本身是补丁版，但 3.5 这一代并不是完全没有行为约束变化。Spring Boot 3.5 Release Notes 中有几项很适合作为升级后的重点回归清单。

1）`heapdump` 端点默认访问策略变更

在 3.5 代际中，heapdump Actuator 端点默认变成了 access=NONE。如果你们过去只做了暴露配置，没有显式设置访问策略，那么升级后相关诊断链路可能与旧行为不同。

如果你确实需要启用它，应同时配置暴露与访问权限，例如：

management:
 endpoints:
 web:
 exposure:
 include: heapdump
 endpoint:
 heapdump:
 access: unrestricted

建议你在测试环境确认：

端点是否仍按预期可访问；
安全配置是否仍符合内网/零信任策略；
是否存在把高敏感诊断端点暴露到错误网络边界的风险。

2）布尔型配置值解析更严格

3.5 代际对 .enabled 这类布尔配置的可接受值收紧为更一致的 true / false。如果你的历史配置里混入了不规范值，升级后应检查是否产生行为变化。

建议排查：

application.yml / application.properties；
环境变量注入后的映射值；
Helm Chart / Kustomize / Ansible 模板里的布尔值渲染方式。

3）Profile 命名校验更严格，但 3.5.1 起已部分放宽

Spring Boot 3.5 代际增强了 Profile 命名校验；官方 Release Notes 同时说明：从 3.5.1 开始，这些限制已部分放宽，额外允许 .、+、@ 字符，也可以通过 spring.profiles.validate=false 关闭校验。

如果你们组织里有历史遗留 Profile 命名习惯，比如：

prod-cn
gray@hz
perf.test

建议在升级后跑一次完整启动验证，确认 Profile 解析与加载顺序没有偏差。

4）按名称注入 `taskExecutor` 的代码需要留意

Spring Boot 3.5 Release Notes 明确指出：自动配置的 TaskExecutor 不再同时提供 taskExecutor 和 applicationTaskExecutor 两个 Bean 名称，现在只提供 applicationTaskExecutor。

如果你们代码里存在按名称获取执行器的写法，例如：

@Qualifier("taskExecutor")
手动 getBean("taskExecutor")
XML 或脚本化配置里写死旧名称

那就要重点回归这部分逻辑。更稳妥的做法是改成依赖 applicationTaskExecutor，避免在未来版本继续背兼容包袱。

七、升级前后的实操检查单

为了让这次补丁升级更可控，可以按下面的顺序执行。

升级前

锁定当前生产版本与构建产物；
导出一份依赖树，确认是否显式覆盖了 Spring AMQP、Spring Data、Spring Integration 相关版本；
识别所有依赖 Actuator、TaskExecutor、Profile、布尔配置开关的模块；
准备至少一轮完整的自动化测试与一轮烟雾验证。

升级中

把 Spring Boot 版本提升到 3.5.16；
执行依赖刷新；
运行单元测试、集成测试、启动测试；
对消息链路、数据库访问、接口调用、定时任务做重点验证。

升级后

检查 /actuator/health、/actuator/info 以及你们自定义观测端点；
检查日志里是否出现 Bean 注入名称变化、配置绑定失败、Profile 校验失败；
观察消息积压、线程池使用率、慢 SQL、启动耗时；
将 3.5.16 标记为 3.5 分支最终基线，并启动 4.x 升级计划。

八、现在是继续留在 3.5，还是直接上 4.x？

截至核实时，Spring 官方项目页显示 Spring Boot 当前最新主线版本为 4.1.0。因此从路线选择看，团队通常有三种策略：

策略 A：先稳定到 3.5.16，再规划 4.1

适合：生产系统多、变更窗口谨慎、近期不适合跨代升级的团队。

优点：

风险最低；
便于先完成一次补丁级基线收敛；
给 4.x 迁移预留独立测试周期。

策略 B：在测试环境同时启动 3.5.16 与 4.1 双线验证

适合：平台团队、公共框架团队、拥有较强自动化测试体系的组织。

优点：

能同步评估短期稳定性与中期迁移成本；
更早暴露跨代兼容性问题；
有利于制定统一升级路线。

策略 C：如果必须长期停留 3.5，评估商业支持

适合：合规要求高、升级窗口长、系统耦合深的企业场景。

因为官方已经明确 3.5.x 的 OSS 周期结束在即，所以“长期停留但不做支持兜底”会越来越被动。

九、给团队负责人的建议

如果你是技术负责人、架构师或中台维护者，我更建议把这次发布当成一个版本治理节点，而不是一次普通补丁升级。

你可以在本周内完成三件事：

把所有 3.5.x 服务统一到 3.5.16；
拉出仍按名称依赖 taskExecutor、依赖宽松布尔配置、依赖旧 profile 命名习惯的模块清单；
明确 4.0 / 4.1 的迁移时间表与负责人。

这样做的好处是，你不会在 3.5 OSS 窗口结束后，仍把版本决策停留在“以后再说”。

十、总结

Spring Boot 3.5.16 表面上只是一次小型维护发布，但它的意义并不小：

它是 Spring Boot 3.5.x 的最后一个 OSS 发布版本；
它把 Spring AMQP 3.2.12、Spring Data BOM 2025.0.13、Spring Integration 6.5.10 纳入最终补丁基线；
它适合作为仍在 3.5 分支上的团队的最终稳定落点；
它也在提醒你：该开始准备 4.x 了。

如果你今天只能做一件事，那就先把测试环境升到 3.5.16，跑完关键回归，再安排生产发布窗口。对仍处在 3.5 生命周期尾段的系统来说，这是成本最低、收益最高的一步。

Spring Boot 4.0 正式发布后该怎么升级：核心变化、兼容性影响与实战建议

Mon, 29 Jun 2026 14:40:54 +0000

Spring Boot 4.0 已经正式 GA。对很多 Java 团队来说，这不是一次普通的小版本升级，而是一次带有明显“代际变化”特征的升级：底座切换到 Spring Framework 7，运行基线与依赖兼容性被整体抬高，同时也带来了更现代的工程能力。

如果你关心的问题是“Spring Boot 4.0 到底带来了什么”“现有项目升不升、怎么升、坑在哪”，这篇文章会从已公开的官方信息出发，梳理它的核心变化、升级影响以及更稳妥的落地路径。

Spring Boot 4.0 现在处于什么状态

从 Spring 官方博客可以确认，Spring Boot 4.0.0 已于 2025-11-20 正式发布，并且已经可以从 Maven Central 获取。与此同时，Spring 官方文档站已经提供 4.0.x 文档线，这说明 4.0 不再是预览版，而是进入了正式维护周期。

这意味着对于已经在 3.x 稳定运行的团队来说，现在讨论的重点已经不再是“能不能尝鲜”，而是“是否值得安排升级窗口，以及怎么降低升级风险”。

为什么说 Spring Boot 4.0 是一次代际升级

Spring 官方对 4.0 的定调非常明确：它是构建在 Spring Framework 7 之上的新一代 Spring Boot。

这句话的分量很重。因为这意味着它不只是新增几个 starter 或者小幅改造自动配置，而是整个技术基线都随之上移。很多团队在迁移时遇到的问题，根源并不在 Boot 自身，而是出在与之配套的 Java 版本、Servlet 基线、第三方依赖、容器选择和老旧 API 使用方式上。

换句话说，Spring Boot 4.0 的价值和成本都比常规次版本升级更高：

价值在于它把 Spring 生态带入了新的工程阶段；
成本在于你必须把项目的“底层地基”一起升级。

Spring Boot 4.0 的核心变化有哪些

1. 基于 Spring Framework 7

这是所有变化的起点。Spring Boot 4.0 不是孤立演进，而是直接建立在 Spring Framework 7 之上。

对于开发者来说，这意味着：

Spring 体系下的一些长期演进点会在 4.0 更集中地体现出来；
与 Framework 7 绑定的兼容性要求会直接影响 Boot 项目；
周边生态是否支持 Spring Framework 7，会成为升级前必须核查的事项。

2. Spring Boot 代码库完成模块化重构

官方将其描述为 complete modularization of the Spring Boot codebase。这不是一个面向业务代码直接可见的“语法特性”，但它对框架演进很重要。

模块化重构带来的直接信号是：

Spring Boot 内部的职责边界更加清晰；
产物会朝着更小、更聚焦的 jar 方向演进；
对后续自动配置裁剪、维护成本控制和长期扩展更友好。

如果你所在团队很关注启动体积、依赖治理和框架透明度，这会是一个值得关注的变化。

3. Null Safety 增强，引入 JSpecify 方向的统一改进

官方明确提到，Spring Boot 4.0 在整个产品线范围内加强了 null safety，并采用 JSpecify 相关改进。

这类变化不会像一个新 starter 那样直观，但它会逐步影响：

IDE 的静态提示；
Java / Kotlin 混合工程中的空安全语义；
编译期和分析期对潜在 NPE 风险的暴露。

对老项目来说，这也意味着一些“以前没出事但本来就不安全”的写法，可能会在升级后更容易被工具识别出来。

4. Java 25 一等支持，同时最低仍要求 Java 17

Spring 官方对 Java 支持给出了非常清晰的说法：Spring Boot 4.0 对 Java 25 提供一等支持，同时继续兼容 Java 17。

从官方系统要求页还能进一步确认：

Spring Boot 4.0.x 最低需要 Java 17；
当前文档线显示其兼容范围可覆盖更高版本 Java；
它要求与 Spring Framework 7.0.x 配套使用。

这说明两件事：

如果你的项目还停留在 Java 11 或更低，升级 Boot 4.0 就不是单纯改依赖版本，而是一次 JDK 基线升级项目；
如果你已经在 Java 17 或更高版本上运行，那么迁移门槛会显著降低。

5. HTTP Service Clients 获得自动配置支持

Spring Boot 4.0 Release Notes 提到，它新增了 HTTP Service Clients 的自动配置支持与配置属性支持。

这类能力的价值在于：

可以通过接口式、声明式方式定义 HTTP 调用；
比手写一层层 WebClient / RestTemplate 包装更简洁；
更适合内部服务调用、SDK 化封装和接口契约式开发。

如果你的系统中已经存在大量对外部服务或内部微服务的 HTTP 调用，这部分能力值得重点关注，因为它能让调用层写法更现代、更一致。

6. MVC 与 WebFlux 获得 API Versioning 自动配置

Spring Boot 4.0 还正式引入了 API Versioning 自动配置，并同时支持：

Spring MVC
Spring WebFlux

这意味着 API 版本治理从“每个团队自己约定、自己封装”进一步走向“框架级支持”。

对于存在以下需求的系统，这个改动很有价值：

同时维护多个 API 版本；
对旧客户端进行平滑兼容；
需要在版本治理层面减少重复样板代码。

7. JMS 支持扩展到新的 JmsClient API

对于仍在使用 JMS 的企业应用场景，Spring Boot 4.0 的自动配置现在支持新的 JmsClient API，同时保持对 JmsTemplate 和 JmsMessagingTemplate 的兼容。

这意味着老系统不会被强迫一次性大改，但新接口能力已经被纳入官方支持范围，团队可以根据节奏逐步迁移。

8. TaskDecorator 组合能力增强

在任务执行和任务调度自动配置方面，Spring Boot 4.0 支持多个 TaskDecorator，并会将它们组合成 CompositeTaskDecorator。

这个变化对日常业务代码未必显眼，但对工程化能力很有帮助，尤其在这些场景下：

链路追踪上下文透传；
日志 MDC 传递；
租户上下文封装；
审计信息注入。

对于对异步任务治理比较重视的团队，这属于非常实用的增强。

9. 新增 OpenTelemetry starter

Spring Boot 4.0 新增了 spring-boot-starter-opentelemetry，并会自动带入面向 OTLP 的指标与链路导出依赖，同时自动配置 OpenTelemetry SDK。

这释放出一个非常明确的信号：

Spring Boot 在可观测性方向上，正进一步向 OpenTelemetry 标准体系靠拢。

如果你的系统正在推进云原生可观测性，或者已经使用统一的 metrics / traces 采集链路，那么 4.0 会比过去更顺手。

10. Gradle 9 支持

官方 Release Notes 明确确认：

Spring Boot 4.0 支持 Gradle 9；
同时继续支持 Gradle 8.14+；
Maven 方面要求 3.6.3+。

如果你的项目使用 Gradle，并且一直想与新版本构建链路保持同步，4.0 在这方面给出了比较明确的支持保证。

升级到 Spring Boot 4.0 时真正需要注意什么

对于大多数团队来说，真正决定“能不能顺利升级”的，不是新特性，而是下面这些兼容性影响。

1. 官方建议：先升到最新 3.5.x，再升 4.0

Spring 官方 Release Notes 和 Migration Guide 都明确建议：

如果你当前项目还不在 3.5.x，最好先升级到最新 3.5.x，再迁移到 4.0。

这是一个非常实用的建议。

因为跨越多个大/小版本直接跳到 4.0，意味着你会同时面对：

旧依赖问题；
废弃 API 问题；
配置属性变更问题；
底层基线问题。

而如果先对齐到 3.5.x，再迁移到 4.0，很多问题会更容易分层定位。

2. Java、Kotlin、GraalVM、Servlet 基线整体抬升

官方 Migration Guide 给出的迁移基线包括：

Java 17+
Kotlin 2.2+
GraalVM native-image 25+
Jakarta EE 11
Servlet 6.1 baseline

这意味着，如果你的项目还有这些历史包袱：

老 JDK；
低版本 Kotlin；
旧 native-image 构建链；
旧 servlet 容器；
对 Jakarta 升级准备不足；

那么升级 Boot 4.0 的工作量会比“改 pom 版本号”大得多。

3. Undertow 支持被移除

这是 4.0 升级里最容易被忽略、但实际影响很大的点之一。

官方 Migration Guide 明确指出：由于 Spring Boot 4.0 需要 Servlet 6.1 baseline，而 Undertow 当前不兼容这一基线，因此 Boot 4 移除了 Undertow 支持。

这包括：

Undertow starter
作为嵌入式服务器的 Undertow 能力

如果你的应用当前使用 Undertow，那么升级到 4.0 时必须评估迁移到：

Tomcat 11.0.x
Jetty 12.1.x

这不是一个可忽略的 warning，而是明确的支持移除。

4. Spring Boot 3.x 中已废弃的类、方法、配置，在 4.0 中可能已经删除

官方 Migration Guide 明确说明：Spring Boot 3.x 中标记为 deprecated 的 classes、methods、properties，在 4.0 中已经被删除。

这会带来几类典型问题：

编译失败；
启动失败；
配置项失效但不一定立即显眼；
某些集成测试才暴露行为变化。

所以在升级前，最好先把当前项目里所有 Boot 3.x 已知的 deprecated 用法清理一遍，不要把这些历史债务带进 4.0。

5. 配置属性迁移建议使用 `spring-boot-properties-migrator`

对于配置项重命名或移除问题，官方建议可以在升级阶段临时引入：

<dependency>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-properties-migrator</artifactId>
 <scope>runtime</scope>
</dependency>

这个工具的作用是：

在启动时分析环境配置；
打印属性迁移相关诊断信息；
对部分已改名属性提供运行时迁移帮助。

但要注意两点：

它只是迁移辅助工具，不是长期依赖；
迁移完成后应该移除。

6. 第三方依赖兼容性比 Boot 自身更值得重点检查

官方迁移建议中特别提到，要对比 3.5.x 与 4.0.x 的 dependency management，并重点检查非 Boot 管理的依赖。

这在真实项目里非常关键。因为很多升级失败案例并不是 Spring Boot 本身出问题，而是下面这些组件没有及时跟上：

Spring Cloud 对应版本；
第三方 starter；
安全、监控、消息队列等中间件整合包；
自定义 BOM；
直接锁定版本的 Jakarta / servlet 生态库。

所以在升级方案上，最稳妥的方式是把“依赖兼容性核查”当作单独工作项来做，而不是在 CI 报错后再被动补救。

一条更稳妥的 Spring Boot 4.0 升级路径

如果你准备在生产项目中升级到 Spring Boot 4.0，可以参考下面这条更稳妥的路径：

第一步：先把项目升级到最新 Spring Boot 3.5.x

这样做的目的不是浪费时间，而是先把 3.x 线上的兼容问题清干净，降低跨代升级风险。

第二步：清理所有已知 deprecated API 与配置

重点排查：

启动日志中的 deprecated 提示；
配置文件中的旧属性；
自定义 starter 或公共组件里的旧用法。

第三步：确认技术基线满足 4.0 要求

至少要确认：

JDK 是否已到 17+；
Kotlin / GraalVM 是否需要同步升级；
容器是否使用 Undertow；
是否依赖老 Servlet 规范。

第四步：核查外围依赖与 Spring Framework 7 / Boot 4 的兼容性

这一步尤其适合通过依赖树、BOM 对比、第三方 starter 发布说明来完成。

第五步：必要时临时引入 `spring-boot-properties-migrator`

把它当作迁移辅助，而不是长期依赖。

第六步：做完整的回归验证

需要重点回归的通常包括：

Web 层接口兼容性；
安全配置；
配置绑定；
任务调度 / 异步执行；
消息队列集成；
监控与链路追踪；
原生镜像构建（如果你在用）。

Spring Boot 4.0 值不值得升

如果你的项目还处于以下状态：

仍在 Java 11 或更老版本；
依赖大量历史包袱；
使用 Undertow 且短期不愿迁移；
对升级窗口极度敏感；

那么短期内不一定适合马上升级到 4.0。

但如果你的项目已经：

运行在 Java 17+；
对可观测性、声明式 HTTP 客户端、API 版本治理等能力有明确需求；
希望尽早跟上 Spring Framework 7 的长期演进路线；
愿意安排一次成体系的升级与回归；

那么 Spring Boot 4.0 是值得认真评估并纳入计划的。

它的意义不只是“版本更高了”，而是它开始把 Spring Boot 带到一个更现代的工程基线上：更清晰的模块边界、更明确的技术底座、更统一的可观测性与 API 治理能力，以及对新一代 Java 的更完整支持。

总结

Spring Boot 4.0 的核心价值可以概括为三点：

它是基于 Spring Framework 7 的代际升级；
它在工程能力上继续向现代化靠拢，尤其是 HTTP Service Clients、API Versioning、OpenTelemetry 与任务装饰能力；
它的升级成本主要来自底层基线提升与旧能力移除，尤其是 Undertow 支持下线、Java/Servlet/Jakarta 体系全面抬升。

对团队来说，最好的做法不是盲目追新，也不是长期停留在旧版本，而是根据自己的技术债水平与业务窗口期，选择一个可控的节奏完成升级。

如果你的项目准备迈向 Spring Boot 4.0，最稳妥的关键词只有一个：先把基础清干净，再升级。

24张图带你彻底弄懂Java线程池

Fri, 26 Jun 2026 10:00:00 +0000

什么是线程池

线程池其实是一种池化的技术实现，池化技术的核心思想就是实现资源的复用，避免资源的重复创建和销毁带来的性能开销。线程池可以管理一堆线程，让线程执行完任务之后不进行销毁，而是继续去处理其它线程已经提交的任务。

使用线程池的好处：

降低资源消耗：通过重复利用已创建的线程降低线程创建和销毁造成的消耗
提高响应速度：当任务到达时，任务可以不需要等到线程创建就能立即执行
提高线程的可管理性：线程是稀缺资源，如果无限制的创建，不仅会消耗系统资源，还会降低系统的稳定性

线程池的构造

Java 主要是通过构建 ThreadPoolExecutor 来创建线程池的。构造方法参数如下：

public ThreadPoolExecutor(
 int corePoolSize, // 核心线程数
 int maximumPoolSize, // 最大线程数
 long keepAliveTime, // 空闲线程存活时间
 TimeUnit unit, // 时间单位
 BlockingQueue<Runnable> workQueue, // 任务队列
 ThreadFactory threadFactory, // 线程工厂
 RejectedExecutionHandler handler // 拒绝策略
)

corePoolSize：线程池中用来工作的核心线程数量
maximumPoolSize：最大线程数，线程池允许创建的最大线程数
keepAliveTime：超出 corePoolSize 后创建的线程存活时间
workQueue：任务队列，是一个阻塞队列
threadFactory：线程池内部创建线程所用的工厂
handler：拒绝策略

线程池的运行原理

1. 提交任务时的判断流程

提交任务
 ↓
线程数 < corePoolSize？
 ├── 是 → 创建核心线程执行任务
 └── 否 → 尝试放入workQueue
 ├── 成功 → 等待线程空闲获取任务
 └── 失败 → 线程数 < maximumPoolSize？
 ├── 是 → 创建非核心线程执行
 └── 否 → 执行拒绝策略

2. 四种拒绝策略

JDK 自带的 RejectedExecutionHandler 实现有 4 种：

策略	行为
`AbortPolicy`	丢弃任务，抛出运行时异常（默认）
`CallerRunsPolicy`	由提交任务的线程来执行任务
`DiscardPolicy`	丢弃这个任务，但是不抛异常
`DiscardOldestPolicy`	从队列中剔除最先进入队列的任务，然后再次提交任务

3. execute 方法核心逻辑

public void execute(Runnable command) {
 if (command == null) throw new NullPointerException();
 
 int c = ctl.get();
 
 // 1. 判断是否小于核心线程数
 if (workerCountOf(c) < corePoolSize) {
 if (addWorker(command, true))
 return;
 c = ctl.get();
 }
 
 // 2. 尝试将任务添加到任务队列中
 if (isRunning(c) && workQueue.offer(command)) {
 int recheck = ctl.get();
 if (!isRunning(recheck) && remove(command))
 reject(command);
 else if (workerCountOf(recheck) == 0)
 addWorker(null, false);
 }
 // 3. 尝试添加非核心线程来执行任务
 else if (!addWorker(command, false))
 reject(command);
}

线程池中线程复用的原理

线程在线程池内部被封装成了一个 Worker 对象，Worker 继承了 AQS，具有锁的特性。

创建线程来执行任务是通过 addWorker 方法。在创建 Worker 对象的时候，会把线程和任务一起封装到 Worker 内部，然后调用 runWorker 方法来让线程执行任务。

final void runWorker(Worker w) {
 Thread wt = Thread.currentThread();
 Runnable task = w.firstTask;
 w.firstTask = null;
 w.unlock();
 
 try {
 // 当有任务或能从队列获取任务时，持续运行
 while (task != null || (task = getTask()) != null) {
 w.lock();
 try {
 beforeExecute(wt, task);
 task.run();
 afterExecute(task, null);
 } finally {
 task = null;
 w.completedTasks++;
 w.unlock();
 }
 }
 } finally {
 processWorkerExit(w, completedAbruptly);
 }
}

关键点：while (task != null || (task = getTask()) != null) 这个循环让线程不会退出，而是不断从队列获取新任务，实现了线程复用。

自定义线程池的最佳实践

在实际项目中，不建议使用 Executors 工具类创建线程池，而是应该手动创建 ThreadPoolExecutor：

ThreadPoolExecutor executor = new ThreadPoolExecutor(
 10, // 核心线程数
 20, // 最大线程数
 60L, // 空闲存活时间
 TimeUnit.SECONDS, // 时间单位
 new LinkedBlockingQueue<>(1000), // 有界队列
 new ThreadFactoryBuilder().setNameFormat("business-pool-%d").build(),
 new ThreadPoolExecutor.CallerRunsPolicy() // 拒绝策略
);

注意事项：

核心线程数设置：CPU密集型任务设置为 CPU核心数+1，IO密集型任务设置为 CPU核心数*2
队列选择：建议使用有界队列，避免OOM
拒绝策略：根据业务场景选择合适的拒绝策略
线程池命名：便于排查问题

总结

线程池是 Java 并发编程中非常重要的组件，理解其工作原理对于编写高性能的并发程序至关重要。核心要点：

线程池通过复用线程来降低资源消耗
ThreadPoolExecutor 的核心参数决定了线程池的行为
任务提交流程：核心线程 → 队列 → 非核心线程 → 拒绝策略
线程复用通过 Worker + runWorker 的 while 循环实现
生产环境建议手动创建线程池，避免使用 Executors

Spring Cloud 微服务架构全解：注册发现、网关、熔断与实战

Thu, 25 Jun 2026 18:00:00 +0000

前言

Spring Cloud 是基于 Spring Boot 的微服务架构解决方案，提供了一系列工具和框架来解决分布式系统中的常见问题：服务注册与发现、配置中心、负载均衡、熔断降级、网关路由、链路追踪等。本文基于 Spring Cloud 2022.x + Spring Boot 3.x 体系讲解。

1. 微服务架构概览

 ┌──────────────┐
 │ 客户端 │
 └──────┬───────┘
 │
 ┌──────▼───────┐
 │ Gateway │ (路由、限流、鉴权)
 │ 网关服务 │
 └──────┬───────┘
 │
 ┌──────────────┼──────────────┐
 │ │ │
 ┌──────▼──────┐ ┌────▼──────┐ ┌─────▼─────┐
 │ 用户服务 │ │ 订单服务 │ │ 商品服务 │
 │ user-svc │ │ order-svc │ │ product-svc│
 └──────┬──────┘ └────┬──────┘ └─────┬─────┘
 │ │ │
 ┌──────▼──────────────▼──────────────▼─────┐
 │ Nacos (注册中心 + 配置中心) │
 └──────────────────────────────────────────┘
 │ │ │
 ┌──────▼──────┐ ┌────▼──────┐ ┌─────▼─────┐
 │ MySQL │ │ Redis │ │ RocketMQ │
 └─────────────┘ └───────────┘ └────────────┘

2. Spring Cloud 版本选择

Spring Cloud	Spring Boot	主要组件
2024.0.x	3.4.x / 3.5.x	Nacos 2.x, Sentinel, Gateway
2023.0.x (Leyton)	3.2.x / 3.3.x	Nacos 2.x, Sentinel, Gateway
2022.0.x (Kilburn)	3.0.x / 3.1.x	Nacos 2.x, Sentinel, Gateway

Spring Boot 4.x 适配的 Spring Cloud 版本请参考官方文档。

2.1 依赖管理（pom.xml）

<dependencyManagement>
 <dependencies>
 <!-- Spring Cloud 版本管理 -->
 <dependency>
 <groupId>org.springframework.cloud</groupId>
 <artifactId>spring-cloud-dependencies</artifactId>
 <version>2023.0.0</version>
 <type>pom</type>
 <scope>import</scope>
 </dependency>

 <!-- Spring Cloud Alibaba 版本管理 -->
 <dependency>
 <groupId>com.alibaba.cloud</groupId>
 <artifactId>spring-cloud-alibaba-dependencies</artifactId>
 <version>2023.0.0.0</version>
 <type>pom</type>
 <scope>import</scope>
 </dependency>
 </dependencies>
</dependencyManagement>

3. Nacos — 注册中心与配置中心

3.1 安装 Nacos

# Docker 快速启动
docker run -d \
 --name nacos \
 -p 8848:8848 \
 -p 9848:9848 \
 -e MODE=standalone \
 -e NACOS_AUTH_ENABLE=true \
 nacos/nacos-server:v2.3.0

# 访问控制台: http://localhost:8848/nacos
# 默认账号: nacos / nacos

3.2 服务注册

<!-- 引入依赖 -->
<dependency>
 <groupId>com.alibaba.cloud</groupId>
 <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
</dependency>

# application.yml
spring:
 application:
 name: user-service
 cloud:
 nacos:
 discovery:
 server-addr: localhost:8848
 namespace: dev
 group: DEFAULT_GROUP
 username: nacos
 password: nacos

// 启动类
@SpringBootApplication
@EnableDiscoveryClient
public class UserServiceApplication {
 public static void main(String[] args) {
 SpringApplication.run(UserServiceApplication.class, args);
 }
}

3.3 配置中心

<dependency>
 <groupId>com.alibaba.cloud</groupId>
 <artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
</dependency>
<dependency>
 <groupId>org.springframework.cloud</groupId>
 <artifactId>spring-cloud-starter-bootstrap</artifactId>
</dependency>

# bootstrap.yml
spring:
 application:
 name: user-service
 cloud:
 nacos:
 config:
 server-addr: localhost:8848
 file-extension: yml
 namespace: dev
 group: DEFAULT_GROUP
 # 共享配置
 shared-configs:
 - data-id: common.yml
 group: DEFAULT_GROUP
 refresh: true

// 动态刷新配置
@RestController
@RefreshScope
public class ConfigController {

 @Value("${app.custom-config}")
 private String customConfig;

 @GetMapping("/config")
 public String getConfig() {
 return customConfig;
 }
}

4. OpenFeign — 声明式 HTTP 调用

4.1 基本用法

<dependency>
 <groupId>org.springframework.cloud</groupId>
 <artifactId>spring-cloud-starter-openfeign</artifactId>
</dependency>
<dependency>
 <groupId>org.springframework.cloud</groupId>
 <artifactId>spring-cloud-starter-loadbalancer</artifactId>
</dependency>

// 启动类
@SpringBootApplication
@EnableFeignClients
public class OrderServiceApplication { }

// 定义 Feign 客户端
@FeignClient(name = "user-service", fallbackFactory = UserClientFallbackFactory.class)
public interface UserClient {

 @GetMapping("/api/users/{id}")
 ApiResponse<UserDTO> getUserById(@PathVariable("id") Long id);

 @PostMapping("/api/users/batch")
 ApiResponse<List<UserDTO>> getUsersByIds(@RequestBody List<Long> ids);
}

// 降级工厂
@Component
public class UserClientFallbackFactory implements FallbackFactory<UserClient> {
 @Override
 public UserClient create(Throwable cause) {
 return new UserClient() {
 @Override
 public ApiResponse<UserDTO> getUserById(Long id) {
 return ApiResponse.error(503, "用户服务不可用: " + cause.getMessage());
 }
 @Override
 public ApiResponse<List<UserDTO>> getUsersByIds(List<Long> ids) {
 return ApiResponse.error(503, "用户服务不可用");
 }
 };
 }
}

// 使用
@Service
@RequiredArgsConstructor
public class OrderService {

 private final UserClient userClient;

 public OrderDTO getOrderDetail(Long orderId) {
 Order order = orderRepository.findById(orderId).orElseThrow();
 // 调用用户服务
 ApiResponse<UserDTO> userResp = userClient.getUserById(order.getUserId());
 // 组装返回
 OrderDTO dto = new OrderDTO();
 dto.setOrder(order);
 dto.setUser(userResp.getData());
 return dto;
 }
}

4.2 Feign 配置

feign:
 client:
 config:
 default:
 connect-timeout: 5000
 read-timeout: 10000
 logger-level: FULL
 compression:
 request:
 enabled: true
 mime-types: application/json
 min-request-size: 2048
 response:
 enabled: true
 circuitbreaker:
 enabled: true

5. Gateway — API 网关

5.1 网关服务搭建

<dependency>
 <groupId>org.springframework.cloud</groupId>
 <artifactId>spring-cloud-starter-gateway</artifactId>
</dependency>
<dependency>
 <groupId>com.alibaba.cloud</groupId>
 <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
</dependency>

spring:
 application:
 name: gateway
 cloud:
 nacos:
 discovery:
 server-addr: localhost:8848
 gateway:
 # 路由配置
 routes:
 - id: user-service
 uri: lb://user-service  # 负载均衡
 predicates:
 - Path=/api/users/**
 filters:
 - StripPrefix=1  # 去掉前缀

 - id: order-service
 uri: lb://order-service
 predicates:
 - Path=/api/orders/**
 filters:
 - StripPrefix=1

 - id: product-service
 uri: lb://product-service
 predicates:
 - Path=/api/products/**
 filters:
 - StripPrefix=1

 # 全局 CORS
 globalcors:
 cors-configurations:
 '[/**]':
 allowedOrigins: "*"
 allowedMethods: "*"
 allowedHeaders: "*"

5.2 自定义过滤器

@Component
public class AuthFilter implements GlobalFilter, Ordered {

 @Override
 public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
 String token = exchange.getRequest().getHeaders().getFirst("Authorization");

 // 白名单
 String path = exchange.getRequest().getURI().getPath();
 if (path.contains("/auth/") || path.contains("/public/")) {
 return chain.filter(exchange);
 }

 // 验证 Token
 if (token == null || !validateToken(token)) {
 ServerHttpResponse response = exchange.getResponse();
 response.setStatusCode(HttpStatus.UNAUTHORIZED);
 response.getHeaders().setContentType(MediaType.APPLICATION_JSON);
 String body = "{\"code\":401,\"message\":\"未授权\"}";
 DataBuffer buffer = response.bufferFactory().wrap(body.getBytes());
 return response.writeWith(Mono.just(buffer));
 }

 // 将用户信息传递给下游服务
 ServerHttpRequest request = exchange.getRequest().mutate()
 .header("X-User-Id", getUserId(token))
 .build();

 return chain.filter(exchange.mutate().request(request).build());
 }

 @Override
 public int getOrder() {
 return -1; // 最高优先级
 }
}

6. Sentinel — 熔断降级与限流

6.1 引入依赖

<dependency>
 <groupId>com.alibaba.cloud</groupId>
 <artifactId>spring-cloud-starter-alibaba-sentinel</artifactId>
</dependency>

6.2 限流规则

@Service
public class ProductService {

 @SentinelResource(
 value = "getProduct",
 blockHandler = "getProductBlock",
 fallback = "getProductFallback"
 )
 public ProductDTO getProduct(Long id) {
 return productRepository.findById(id)
 .map(this::convertToDTO)
 .orElseThrow(() -> new BusinessException(404, "商品不存在"));
 }

 // 限流降级
 public ProductDTO getProductBlock(Long id, BlockException ex) {
 throw new BusinessException(429, "请求过于频繁，请稍后再试");
 }

 // 业务降级
 public ProductDTO getProductFallback(Long id, Throwable ex) {
 return ProductDTO.builder()
 .id(id)
 .name("商品信息暂不可用")
 .build();
 }
}

6.3 熔断规则（代码配置）

@Configuration
public class SentinelConfig {

 @PostConstruct
 public void initRules() {
 // 限流规则
 FlowRule flowRule = new FlowRule();
 flowRule.setResource("getProduct");
 flowRule.setGrade(RuleConstant.FLOW_GRADE_QPS);
 flowRule.setCount(100); // QPS 限制为 100
 flowRule.setControlBehavior(RuleConstant.CONTROL_BEHAVIOR_WARM_UP);
 flowRule.setWarmUpPeriodSec(10); // 预热 10 秒
 FlowRuleManager.loadRules(Collections.singletonList(flowRule));

 // 熔断规则
 DegradeRule degradeRule = new DegradeRule();
 degradeRule.setResource("getProduct");
 degradeRule.setGrade(CircuitBreakerStrategy.ERROR_RATIO.getType());
 degradeRule.setCount(0.5); // 错误率 50%
 degradeRule.setTimeWindow(30); // 熔断持续 30 秒
 degradeRule.setMinRequestAmount(10); // 最少 10 次请求
 degradeRule.setStatIntervalMs(10000); // 统计窗口 10 秒
 DegradeManager.loadRules(Collections.singletonList(degradeRule));
 }
}

6.4 网关限流

spring:
 cloud:
 gateway:
 routes:
 - id: user-service
 uri: lb://user-service
 predicates:
 - Path=/api/users/**
 filters:
 - name: RequestRateLimiter
 args:
 redis-rate-limiter.replenishRate: 10 # 每秒 10 个请求
 redis-rate-limiter.burstCapacity: 20 # 突发容量 20
 key-resolver: "#{@userKeyResolver}"

@Component
public class UserKeyResolver implements KeyResolver {
 @Override
 public Mono<String> resolve(ServerWebExchange exchange) {
 // 按用户 ID 限流
 String userId = exchange.getRequest().getHeaders().getFirst("X-User-Id");
 return Mono.just(userId != null ? userId : exchange.getRequest().getRemoteAddress().getHostString());
 }
}

7. Seata — 分布式事务

7.1 引入依赖

<dependency>
 <groupId>com.alibaba.cloud</groupId>
 <artifactId>spring-cloud-starter-alibaba-seata</artifactId>
</dependency>

7.2 使用 @GlobalTransactional

@Service
@RequiredArgsConstructor
public class OrderService {

 private final OrderMapper orderMapper;
 private final AccountClient accountClient;
 private final StorageClient storageClient;

 @GlobalTransactional(name = "create-order", rollbackFor = Exception.class)
 public void createOrder(OrderRequest request) {
 // 1. 创建订单
 Order order = new Order();
 order.setUserId(request.getUserId());
 order.setProductId(request.getProductId());
 order.setCount(request.getCount());
 order.setStatus(0);
 orderMapper.insert(order);

 // 2. 扣减库存（远程调用）
 storageClient.deduct(request.getProductId(), request.getCount());

 // 3. 扣减余额（远程调用）
 accountClient.debit(request.getUserId(), request.getTotalAmount());

 // 4. 更新订单状态
 order.setStatus(1);
 orderMapper.updateById(order);

 // 如果任何一步失败，所有操作都会回滚
 }
}

8. Sleuth + Zipkin — 链路追踪

<!-- 依赖 -->
<dependency>
 <groupId>io.micrometer</groupId>
 <artifactId>micrometer-tracing-bridge-brave</artifactId>
</dependency>
<dependency>
 <groupId>io.zipkin.reporter2</groupId>
 <artifactId>zipkin-reporter-brave</artifactId>
</dependency>

management:
 tracing:
 sampling:
 probability: 1.0 # 采样率（1.0 = 100%）
 zipkin:
 tracing:
 endpoint: http://localhost:9411/api/v2/spans

9. 完整项目结构

my-cloud/
├── pom.xml # 父 POM
├── gateway/ # 网关服务
│ ├── pom.xml
│ └── src/
├── user-service/ # 用户服务
│ ├── pom.xml
│ └── src/
├── order-service/ # 订单服务
│ ├── pom.xml
│ └── src/
├── product-service/ # 商品服务
│ ├── pom.xml
│ └── src/
└── common/ # 公共模块
 ├── pom.xml
 └── src/
 └── main/java/com/example/common/
 ├── model/ # 公共 DTO
 ├── exception/ # 异常定义
 ├── util/ # 工具类
 └── config/ # 公共配置

10. 核心组件对比

功能	Spring Cloud Netflix (旧)	Spring Cloud Alibaba (推荐)
注册中心	Eureka	Nacos
配置中心	Spring Cloud Config	Nacos
负载均衡	Ribbon	Spring Cloud LoadBalancer
远程调用	Feign	OpenFeign
网关	Zuul	Spring Cloud Gateway
熔断降级	Hystrix	Sentinel
分布式事务	—	Seata
消息队列	—	RocketMQ

11. 常见面试题

Q: Nacos 和 Eureka 的区别？ A: Nacos 同时支持 CP（配置中心）和 AP（注册中心）模式，支持配置中心，支持主动推送；Eureka 只支持 AP 模式，仅做注册中心。

Q: Sentinel 和 Hystrix 的区别？ A: Sentinel 支持实时监控 Dashboard、多种限流策略（QPS/线程数/热点参数）、网关限流；Hystrix 已停止维护，功能相对简单。

Q: Gateway 和 Zuul 的区别？ A: Gateway 基于 Spring WebFlux（响应式），性能更好；Zuul 1.x 基于 Servlet（阻塞式），性能较差。Zuul 2.x 未与 Spring Cloud 深度集成。

Q: 如何保证分布式事务一致性？ A: 常用方案：Seata（AT/TCC/SAGA 模式）、本地消息表 + MQ、最大努力通知等。

总结

Spring Cloud 核心组件：

Nacos — 注册中心 + 配置中心，服务发现与动态配置
OpenFeign — 声明式 HTTP 调用，简化微服务间通信
Gateway — API 网关，路由、限流、鉴权
Sentinel — 熔断降级 + 限流，保护服务稳定性
Seata — 分布式事务，保证数据一致性
Sleuth + Zipkin — 链路追踪，排查分布式调用问题
LoadBalancer — 客户端负载均衡

Spring Boot 4 从入门到实战：自动配置、Web 开发与生产部署

Thu, 25 Jun 2026 17:30:00 +0000

前言

Spring Boot 是 Spring 生态中最受欢迎的框架，它通过"约定优于配置"的理念，让开发者能快速创建独立运行的、生产级的 Spring 应用。目前最新版本为 Spring Boot 4.1.0（2026 年 6 月发布），要求 Java 17+，基于 Spring Framework 7，全面拥抱 Jakarta EE。

1. 核心特性

特性	说明
自动配置	根据引入的依赖自动配置 Bean
起步依赖	Starter 依赖简化 Maven/Gradle 配置
内嵌服务器	内嵌 Tomcat/Jetty/Undertow，无需外部部署
Actuator	生产级监控和管理端点
外部化配置	支持 YAML/Properties/环境变量/命令行参数
无代码生成	不生成代码，不修改字节码

2. 快速开始

2.1 创建项目

# 使用 Spring Initializr（推荐）
# https://start.spring.io

# 或使用命令行
curl https://start.spring.io/starter.tgz \
 -d type=maven-project \
 -d language=java \
 -d bootVersion=4.1.0 \
 -d baseDir=myapp \
 -d groupId=com.example \
 -d artifactId=myapp \
 -d name=myapp \
 -d packageName=com.example.myapp \
 -d javaVersion=17 \
 -d dependencies=web,data-jpa,mysql,lombok,actuator \
| tar -xzvf -

2.2 pom.xml 核心依赖

<parent>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-parent</artifactId>
 <version>4.1.0</version>
</parent>

<dependencies>
 <!-- Web -->
 <dependency>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-web</artifactId>
 </dependency>

 <!-- 数据库 -->
 <dependency>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-data-jpa</artifactId>
 </dependency>
 <dependency>
 <groupId>com.mysql</groupId>
 <artifactId>mysql-connector-j</artifactId>
 </dependency>

 <!-- Redis -->
 <dependency>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-data-redis</artifactId>
 </dependency>

 <!-- 参数校验 -->
 <dependency>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-validation</artifactId>
 </dependency>

 <!-- Lombok -->
 <dependency>
 <groupId>org.projectlombok</groupId>
 <artifactId>lombok</artifactId>
 <optional>true</optional>
 </dependency>

 <!-- 监控 -->
 <dependency>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-actuator</artifactId>
 </dependency>

 <!-- 测试 -->
 <dependency>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-test</artifactId>
 <scope>test</scope>
 </dependency>
</dependencies>

2.3 启动类

@SpringBootApplication
public class MyApplication {
 public static void main(String[] args) {
 SpringApplication.run(MyApplication.class, args);
 }
}

3. 自动配置原理

3.1 启动流程

@SpringBootApplication
 ├── @SpringBootConfiguration → 标记为配置类
 ├── @EnableAutoConfiguration → 开启自动配置
 │ └── @Import(AutoConfigurationImportSelector)
 │ └── 读取 META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports
 └── @ComponentScan → 扫描当前包及子包

3.2 自动配置条件注解

@ConditionalOnClass // 类路径下存在指定类
@ConditionalOnMissingClass // 类路径下不存在指定类
@ConditionalOnBean // 容器中存在指定 Bean
@ConditionalOnMissingBean // 容器中不存在指定 Bean
@ConditionalOnProperty // 配置属性满足条件
@ConditionalOnResource // 类路径下存在指定资源
@ConditionalOnWebApplication // 是 Web 应用

3.3 查看自动配置报告

# 启动时添加 --debug 参数
java -jar myapp.jar --debug

# 或在配置中添加
debug=true

日志中会显示：

Positive matches — 匹配成功的自动配置
Negative matches — 未匹配的自动配置
Unconditional classes — 无条件配置的类

4. 配置文件

4.1 application.yml

server:
 port: 8080
 servlet:
 context-path: /api

spring:
 # 数据源
 datasource:
 url: jdbc:mysql://localhost:3306/mydb?useSSL=false&serverTimezone=Asia/Shanghai
 username: root
 password: ${DB_PASSWORD:default}
 hikari:
 maximum-pool-size: 20
 minimum-idle: 5

 # JPA
 jpa:
 hibernate:
 ddl-auto: update
 show-sql: true
 properties:
 hibernate:
 format_sql: true

 # Redis
 data:
 redis:
 host: localhost
 port: 6379
 password: ${REDIS_PASSWORD:}
 database: 0

 # Jackson
 jackson:
 date-format: yyyy-MM-dd HH:mm:ss
 time-zone: Asia/Shanghai
 default-property-inclusion: non_null

# 自定义配置
app:
 name: My Application
 version: 1.0.0

# 日志
logging:
 level:
 root: INFO
 com.example.myapp: DEBUG
 org.hibernate.SQL: DEBUG
 file:
 name: logs/app.log
 max-size: 100MB
 max-history: 30

# Actuator
management:
 endpoints:
 web:
 exposure:
 include: health,info,metrics,prometheus
 endpoint:
 health:
 show-details: always

4.2 多环境配置

# application-dev.yml → 开发环境
# application-test.yml → 测试环境
# application-prod.yml → 生产环境

# 激活方式
java -jar myapp.jar --spring.profiles.active=prod

# 或环境变量
export SPRING_PROFILES_ACTIVE=prod

4.3 读取配置

// 方式一：@Value
@Value("${app.name}")
private String appName;

// 方式二：@ConfigurationProperties
@Data
@ConfigurationProperties(prefix = "app")
public class AppProperties {
 private String name;
 private String version;
 private List<String> servers;
}

// 在启动类上启用
@SpringBootApplication
@EnableConfigurationProperties(AppProperties.class)
public class MyApplication { }

5. Web 开发

5.1 RESTful Controller

@RestController
@RequestMapping("/api/users")
@RequiredArgsConstructor
public class UserController {

 private final UserService userService;

 @GetMapping
 public ApiResponse<List<UserDTO>> list(@RequestParam(defaultValue = "1") int page,
 @RequestParam(defaultValue = "10") int size) {
 return ApiResponse.success(userService.list(page, size));
 }

 @GetMapping("/{id}")
 public ApiResponse<UserDTO> getById(@PathVariable Long id) {
 return ApiResponse.success(userService.getById(id));
 }

 @PostMapping
 public ApiResponse<UserDTO> create(@Valid @RequestBody UserCreateRequest request) {
 return ApiResponse.success(userService.create(request));
 }

 @PutMapping("/{id}")
 public ApiResponse<UserDTO> update(@PathVariable Long id,
 @Valid @RequestBody UserUpdateRequest request) {
 return ApiResponse.success(userService.update(id, request));
 }

 @DeleteMapping("/{id}")
 public ApiResponse<Void> delete(@PathVariable Long id) {
 userService.delete(id);
 return ApiResponse.success(null);
 }
}

5.2 统一响应封装

@Data
@AllArgsConstructor
@NoArgsConstructor
public class ApiResponse<T> {
 private int code;
 private String message;
 private T data;

 public static <T> ApiResponse<T> success(T data) {
 return new ApiResponse<>(200, "OK", data);
 }

 public static <T> ApiResponse<T> error(int code, String message) {
 return new ApiResponse<>(code, message, null);
 }
}

5.3 全局异常处理

@RestControllerAdvice
@Slf4j
public class GlobalExceptionHandler {

 // 参数校验异常
 @ExceptionHandler(MethodArgumentNotValidException.class)
 public ApiResponse<Void> handleValidation(MethodArgumentNotValidException e) {
 String message = e.getBindingResult().getFieldErrors().stream()
 .map(fe -> fe.getField() + ": " + fe.getDefaultMessage())
 .collect(Collectors.joining(", "));
 return ApiResponse.error(400, message);
 }

 // 业务异常
 @ExceptionHandler(BusinessException.class)
 public ApiResponse<Void> handleBusiness(BusinessException e) {
 return ApiResponse.error(e.getCode(), e.getMessage());
 }

 // 未捕获异常
 @ExceptionHandler(Exception.class)
 public ApiResponse<Void> handleException(Exception e) {
 log.error("Unexpected error", e);
 return ApiResponse.error(500, "服务器内部错误");
 }
}

5.4 请求参数校验

@Data
public class UserCreateRequest {

 @NotBlank(message = "用户名不能为空")
 @Size(min = 2, max = 20, message = "用户名长度 2-20")
 private String username;

 @NotBlank(message = "邮箱不能为空")
 @Email(message = "邮箱格式不正确")
 private String email;

 @NotNull(message = "年龄不能为空")
 @Min(value = 1, message = "年龄最小 1")
 @Max(value = 150, message = "年龄最大 150")
 private Integer age;
}

5.5 拦截器

@Component
public class AuthInterceptor implements HandlerInterceptor {

 @Override
 public boolean preHandle(HttpServletRequest request,
 HttpServletResponse response,
 Object handler) throws Exception {
 String token = request.getHeader("Authorization");
 if (token == null || !validateToken(token)) {
 response.setStatus(401);
 response.getWriter().write("{\"code\":401,\"message\":\"未授权\"}");
 return false;
 }
 return true;
 }
}

@Configuration
public class WebConfig implements WebMvcConfigurer {

 @Autowired
 private AuthInterceptor authInterceptor;

 @Override
 public void addInterceptors(InterceptorRegistry registry) {
 registry.addInterceptor(authInterceptor)
 .addPathPatterns("/api/**")
 .excludePathPatterns("/api/auth/**");
 }
}

5.6 跨域配置

@Configuration
public class CorsConfig implements WebMvcConfigurer {

 @Override
 public void addCorsMappings(CorsRegistry registry) {
 registry.addMapping("/api/**")
 .allowedOrigins("http://localhost:3000")
 .allowedMethods("GET", "POST", "PUT", "DELETE", "OPTIONS")
 .allowedHeaders("*")
 .allowCredentials(true)
 .maxAge(3600);
 }
}

6. 数据访问

6.1 JPA 实体

@Entity
@Table(name = "users")
@Data
public class User {
 @Id
 @GeneratedValue(strategy = GenerationType.IDENTITY)
 private Long id;

 @Column(nullable = false, unique = true, length = 50)
 private String username;

 @Column(nullable = false)
 private String email;

 @Column(nullable = false)
 private Integer age;

 @CreationTimestamp
 private LocalDateTime createdAt;

 @UpdateTimestamp
 private LocalDateTime updatedAt;
}

6.2 JPA Repository

public interface UserRepository extends JpaRepository<User, Long> {

 Optional<User> findByUsername(String username);

 List<User> findByAgeBetween(Integer minAge, Integer maxAge);

 @Query("SELECT u FROM User u WHERE u.email LIKE %:keyword% OR u.username LIKE %:keyword%")
 Page<User> search(@Param("keyword") String keyword, Pageable pageable);

 @Modifying
 @Query("UPDATE User u SET u.email = :email WHERE u.id = :id")
 int updateEmail(@Param("id") Long id, @Param("email") String email);
}

6.3 Redis 缓存

@Service
@RequiredArgsConstructor
public class UserService {

 private final UserRepository userRepository;
 private final RedisTemplate<String, Object> redisTemplate;

 // 使用 RedisTemplate
 public UserDTO getById(Long id) {
 String key = "user:" + id;
 UserDTO cached = (UserDTO) redisTemplate.opsForValue().get(key);
 if (cached != null) return cached;

 User user = userRepository.findById(id)
 .orElseThrow(() -> new BusinessException(404, "用户不存在"));
 UserDTO dto = convertToDTO(user);
 redisTemplate.opsForValue().set(key, dto, 30, TimeUnit.MINUTES);
 return dto;
 }

 // 使用 Spring Cache 注解
 @Cacheable(value = "users", key = "#id")
 public UserDTO getByIdCached(Long id) { ... }

 @CachePut(value = "users", key = "#id")
 public UserDTO update(Long id, UserUpdateRequest request) { ... }

 @CacheEvict(value = "users", key = "#id")
 public void delete(Long id) { ... }
}

7. AOP 切面

@Aspect
@Component
@Slf4j
public class LogAspect {

 @Around("@annotation(logOperation)")
 public Object around(ProceedingJoinPoint point, LogOperation logOperation) throws Throwable {
 long start = System.currentTimeMillis();
 String methodName = point.getSignature().toShortString();

 log.info("开始执行: {} - {}", logOperation.value(), methodName);

 try {
 Object result = point.proceed();
 long cost = System.currentTimeMillis() - start;
 log.info("执行完成: {} - {} ({}ms)", logOperation.value(), methodName, cost);
 return result;
 } catch (Exception e) {
 log.error("执行异常: {} - {}", logOperation.value(), methodName, e);
 throw e;
 }
 }
}

// 自定义注解
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface LogOperation {
 String value() default "";
}

8. 定时任务

@SpringBootApplication
@EnableScheduling
public class MyApplication { }

@Component
@Slf4j
public class ScheduledTasks {

 @Scheduled(cron = "0 0 2 * * ?") // 每天凌晨 2 点
 public void dailyBackup() {
 log.info("执行每日备份...");
 }

 @Scheduled(fixedRate = 60000) // 每 60 秒
 public void syncData() {
 log.info("同步数据...");
 }

 @Scheduled(fixedDelay = 30000) // 上次完成后 30 秒
 public void cleanup() {
 log.info("清理任务...");
 }
}

9. 异步处理

@SpringBootApplication
@EnableAsync
public class MyApplication { }

@Configuration
public class AsyncConfig {

 @Bean("taskExecutor")
 public Executor taskExecutor() {
 ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
 executor.setCorePoolSize(5);
 executor.setMaxPoolSize(20);
 executor.setQueueCapacity(100);
 executor.setThreadNamePrefix("async-");
 executor.setRejectedExecutionHandler(new ThreadPoolExecutor.CallerRunsPolicy());
 return executor;
 }
}

@Service
public class NotificationService {

 @Async("taskExecutor")
 public CompletableFuture<String> sendEmail(String to, String content) {
 // 耗时操作
 return CompletableFuture.completedFuture("sent");
 }
}

10. 生产部署

10.1 打包

# Maven 打包
mvn clean package -DskipTests

# Gradle 打包
gradle bootJar

# 运行
java -jar target/myapp-1.0.0.jar

# 指定 profile
java -jar myapp.jar --spring.profiles.active=prod

# JVM 参数
java -Xms512m -Xmx1024m -XX:+UseG1GC -jar myapp.jar

10.2 Docker 部署

FROM eclipse-temurin:17-jre-alpine
WORKDIR /app
COPY target/*.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "app.jar"]

10.3 Actuator 监控端点

端点	说明
`/actuator/health`	健康检查
`/actuator/info`	应用信息
`/actuator/metrics`	指标数据
`/actuator/prometheus`	Prometheus 格式指标
`/actuator/env`	环境变量
`/actuator/configprops`	配置属性
`/actuator/beans`	所有 Bean
`/actuator/mappings`	URL 映射
`/actuator/loggers`	日志级别管理
`/actuator/threaddump`	线程 dump
`/actuator/heapdump`	堆 dump

11. 常用 Starter 一览

Starter	用途
spring-boot-starter-web	Web/RESTful
spring-boot-starter-data-jpa	JPA 数据访问
spring-boot-starter-data-redis	Redis
spring-boot-starter-data-mongodb	MongoDB
spring-boot-starter-security	安全认证
spring-boot-starter-validation	参数校验
spring-boot-starter-mail	邮件发送
spring-boot-starter-quartz	定时任务
spring-boot-starter-websocket	WebSocket
spring-boot-starter-actuator	监控管理
spring-boot-starter-test	单元测试
mybatis-plus-spring-boot3-starter	MyBatis-Plus

12. Spring Boot 版本选择

版本	状态	Java 要求	Spring Framework
4.1.x (推荐)	最新，OSS 支持到 2027.7	Java 17-26	7.0.x
4.0.x	稳定	Java 17-26	7.0.x
3.5.x	OSS 支持到 2026.6	Java 17-24	6.2.x
3.2.x	已停止 OSS 支持	Java 17-21	6.1.x
2.7.x	已停止支持	Java 8/11/17	5.3.x

💡 建议：新项目直接使用 Spring Boot 4.1.x + Java 21/25。

总结

Spring Boot 核心知识点：

自动配置 — 根据依赖自动配置，减少样板代码
起步依赖 — Starter 一站式引入所需依赖
Web 开发 — RESTful API、参数校验、异常处理、拦截器
数据访问 — JPA、Redis、MyBatis
AOP — 日志、权限、缓存等横切关注点
生产特性 — Actuator 监控、多环境配置、优雅停机
部署方式 — JAR 直接运行、Docker 容器化

Java 21 新特性详解：虚拟线程、Pattern Matching Switch 与现代并发

Thu, 25 Jun 2026 15:00:00 +0000

前言

Java 21 于 2023 年 9 月发布，是继 Java 17 之后的下一个长期支持版本（LTS）。它带来了 Java 并发编程的革命性变化——虚拟线程（Virtual Threads），以及一系列语法增强。对于需要处理高并发的后端开发者来说，Java 21 是一个里程碑式的版本。

1. 虚拟线程（Virtual Threads）

虚拟线程是 Project Loom 的核心成果，用极低的资源开销实现百万级并发。

1.1 传统线程 vs 虚拟线程

// 传统平台线程：每个线程占用约 1MB 内存
// 1 万个线程 ≈ 10GB 内存
Thread platformThread = new Thread(() -> System.out.println("Platform Thread"));

// 虚拟线程：每个虚拟线程仅占几 KB
// 100 万个虚拟线程也只需几 GB 内存
Thread virtualThread = Thread.ofVirtual().start(() -> System.out.println("Virtual Thread"));

// 创建虚拟线程（方式一：Builder）
Thread vt1 = Thread.ofVirtual()
 .name("my-vt", 0)
 .start(() -> doWork());

// 创建虚拟线程（方式二：工厂）
ExecutorService executor = Executors.newVirtualThreadPerTaskExecutor();
executor.submit(() -> doWork());

// 创建虚拟线程（方式三：直接创建）
Thread.startVirtualThread(() -> doWork());

1.2 与传统线程池对比

// 传统方式：固定线程池，线程数受限
ExecutorService pool = Executors.newFixedThreadPool(200);
for (int i = 0; i < 100_000; i++) {
 pool.submit(() -> {
 Thread.sleep(Duration.ofSeconds(1)); // 阻塞
 return fetchData();
 });
}
// 问题：200 个线程只能同时处理 200 个请求，其余排队

// 虚拟线程：每个任务一个线程，百万级并发
ExecutorService vExecutor = Executors.newVirtualThreadPerTaskExecutor();
for (int i = 0; i < 1_000_000; i++) {
 vExecutor.submit(() -> {
 Thread.sleep(Duration.ofSeconds(1)); // 阻塞不浪费资源
 return fetchData();
 });
}
// 100 万个任务几乎同时执行

1.3 实战：HTTP 服务

// 使用虚拟线程的 HTTP 服务器
public class VirtualThreadServer {
 public static void main(String[] args) throws IOException {
 // 传统方式需要线程池，虚拟线程直接创建
 var server = HttpServer.create(new InetSocketAddress(8080), 0);
 server.setExecutor(Executors.newVirtualThreadPerTaskExecutor());
 server.createContext("/api/users", exchange -> {
 // 每个请求一个虚拟线程，可以安全地阻塞
 String userId = extractUserId(exchange);
 User user = db.query(userId); // 阻塞 IO，虚拟线程自动让出
 Order order = fetchOrder(userId); // 阻塞 HTTP 调用
 String response = formatResponse(user, order);
 exchange.sendResponseHeaders(200, response.length());
 exchange.getResponseBody().write(response.getBytes());
 });
 server.start();
 }
}

1.4 虚拟线程注意事项

// ❌ 不要在虚拟线程中使用 synchronized（会导致载体线程被固定）
synchronized (lock) {
 // 这会阻止虚拟线程从载体线程上卸载
 doBlockingIO();
}

// ✅ 使用 ReentrantLock 替代
ReentrantLock lock = new ReentrantLock();
lock.lock();
try {
 doBlockingIO();
} finally {
 lock.unlock();
}

// ❌ 不要池化虚拟线程
// 虚拟线程的设计就是"用完即弃"，不需要池化
ExecutorService pool = Executors.newFixedThreadPool(100); // 不要这样做

// ✅ 正确用法
ExecutorService executor = Executors.newVirtualThreadPerTaskExecutor();

2. Pattern Matching for Switch

Java 21 正式特性。让 switch 支持类型模式匹配和解构。

2.1 类型模式匹配

// 传统写法
static String format(Object obj) {
 if (obj instanceof Integer i) {
 return String.format("int %d", i);
 } else if (obj instanceof Long l) {
 return String.format("long %d", l);
 } else if (obj instanceof Double d) {
 return String.format("double %f", d);
 } else if (obj instanceof String s) {
 return String.format("String %s", s);
 } else {
 return obj.toString();
 }
}

// Pattern Matching for Switch
static String format(Object obj) {
 return switch (obj) {
 case Integer i -> String.format("int %d", i);
 case Long l -> String.format("long %d", l);
 case Double d -> String.format("double %f", d);
 case String s -> String.format("String %s", s);
 case null -> "null";
 default -> obj.toString();
 };
}

2.2 Guarded Patterns（守卫模式）

static String classify(Object obj) {
 return switch (obj) {
 case String s && s.length() > 10 -> "长字符串: " + s.substring(0, 10) + "...";
 case String s && s.isEmpty() -> "空字符串";
 case String s -> "字符串: " + s;
 case Integer i && i > 0 -> "正整数: " + i;
 case Integer i && i < 0 -> "负整数: " + i;
 case Integer i -> "零";
 case null -> "null";
 default -> "其他: " + obj;
 };
}

2.3 配合 Sealed Classes

public sealed interface Shape permits Circle, Rectangle, Triangle {}
public record Circle(double radius) implements Shape {}
public record Rectangle(double w, double h) implements Shape {}
public record Triangle(double a, double b, double c) implements Shape {}

static double area(Shape shape) {
 return switch (shape) {
 case Circle c -> Math.PI * c.radius() * c.radius();
 case Rectangle r -> r.w() * r.h();
 case Triangle t -> {
 double s = (t.a() + t.b() + t.c()) / 2;
 yield Math.sqrt(s * (s - t.a()) * (s - t.b()) * (s - t.c()));
 }
 // 不需要 default！编译器知道已经穷举
 };
}

3. Record Patterns（记录模式）

Java 21 正式特性。对 Record 进行解构匹配。

public record Point(int x, int y) {}
public record Line(Point start, Point end) {}
public record Triangle(Point a, Point b, Point c) {}

// Record 解构模式
static double length(Line line) {
 return switch (line) {
 case Line(Point(int x1, int y1), Point(int x2, int y2)) ->
 Math.sqrt(Math.pow(x2 - x1, 2) + Math.pow(y2 - y1, 2));
 };
}

// 嵌套解构
static String describe(Object obj) {
 return switch (obj) {
 case Line(Point(var x1, var y1), Point(var x2, var y2)) ->
 "线段从 (%d,%d) 到 (%d,%d)".formatted(x1, y1, x2, y2);
 case Point(var x, var y) ->
 "点 (%d, %d)".formatted(x, y);
 default -> "未知形状";
 };
}

// 在 if 中使用
if (obj instanceof Line(Point(int x1, int y1), Point(int x2, int y2))) {
 System.out.printf("从 (%d,%d) 到 (%d,%d)%n", x1, y1, x2, y2);
}

4. Sequenced Collections（有序集合）

Java 21 引入了 SequencedCollection 接口，统一了有序集合的操作。

// 新接口层次
// SequencedCollection<E> extends Collection<E>
// - SequencedSet<E> extends Set<E>, SequencedCollection<E>
// - SequencedMap<K,V> extends Map<K,V>

// SequencedCollection 新方法
List<String> list = new ArrayList<>(List.of("a", "b", "c"));

list.getFirst(); // "a" — 获取第一个元素
list.getLast(); // "c" — 获取最后一个元素
list.addFirst("z"); // [z, a, b, c]
list.addLast("d"); // [z, a, b, c, d]
list.reversed(); // [d, c, b, a, z] — 返回反转视图

// SequencedMap 新方法
LinkedHashMap<String, Integer> map = new LinkedHashMap<>();
map.put("first", 1);
map.put("second", 2);
map.put("third", 3);

map.firstEntry(); // first=1
map.lastEntry(); // third=3
map.pollFirstEntry(); // 移除并返回 first=1
map.pollLastEntry(); // 移除并返回 third=3
map.putFirst("zero", 0); // 在最前面插入
map.putLast("four", 4); // 在最后面插入
map.reversed(); // 返回反转视图

// 适用类型
// ArrayList, LinkedList, ArrayDeque → SequencedCollection
// LinkedHashSet, TreeSet → SequencedSet
// LinkedHashMap, TreeMap → SequencedMap

5. Unnamed Patterns and Variables（未命名模式和变量）

Java 21 正式特性。用 _ 忽略不需要的变量。

// 未命名变量
if (obj instanceof Point(int x, int _)) {
 // 只关心 x，不关心 y
 System.out.println("x = " + x);
}

// 在 switch 中使用
switch (obj) {
 case Point(int x, _) -> System.out.println("x = " + x);
 case Line(_, Point(int x, _)) -> System.out.println("终点 x = " + x);
 default -> {}
}

// 在 lambda 中使用（忽略不需要的参数）
map.forEach((key, _) -> System.out.println(key)); // 不关心 value

// try-with-resources（资源需实现 AutoCloseable，这里忽略其引用）
try (var _ = acquireResource()) {
 // 不需要引用资源变量
}

// for 循环
for (var _ : range) {
 doSomething(); // 不需要迭代变量
}

6. String Templates（字符串模板）

预览特性。类似其他语言的字符串插值。

// STR 处理器（自动处理转义和格式化）
String name = "Alice";
int age = 30;
String message = STR."Hello, \{name}! You are \{age} years old.";
// "Hello, Alice! You are 30 years old."

// 嵌入表达式
String result = STR."The result is \{2 * 3 + 1}.";
// "The result is 7."

// 方法调用
String upper = STR."Name: \{name.toUpperCase()}";

// 多行
String html = STR."""
 <div class="user">
 <h1>\{name}</h1>
 <p>Age: \{age}</p>
 </div>
 """;

// RAW 处理器（不转义）
String raw = RAW."<script>alert('hello')</script>";

// FMT 处理器（支持格式化）
String formatted = FMT."%.2f\{3.14159}"; // "3.14"

7. Scoped Values（作用域值）

Java 21 预览特性。替代 ThreadLocal 的更安全方案。

// ThreadLocal 的问题：需要手动清理，容易内存泄漏
// Scoped Values：自动随作用域结束而清理

// 定义
private static final ScopedValue<User> CURRENT_USER = ScopedValue.newInstance();

// 使用
ScopedValue.where(CURRENT_USER, user).run(() -> {
 // 在这个作用域内可以访问 CURRENT_USER
 processRequest();
 handleOrder();
});

// 读取
void processRequest() {
 User user = CURRENT_USER.get(); // 获取当前用户
 // ...
}

8. Structured Concurrency（结构化并发）

Java 21 预览特性。将多线程任务组织为结构化的任务树。

// 传统方式：手动管理多个 Future
Future<User> userFuture = executor.submit(() -> fetchUser(id));
Future<Order> orderFuture = executor.submit(() -> fetchOrder(id));
User user = userFuture.get();
Order order = orderFuture.get();

// 结构化并发
try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {
 Subtask<User> userTask = scope.fork(() -> fetchUser(id));
 Subtask<Order> orderTask = scope.fork(() -> fetchOrder(id));

 scope.join(); // 等待所有任务完成
 scope.throwIfFailed(); // 如果有失败则抛出异常

 return new UserOrder(userTask.get(), orderTask.get());
}
// 自动关闭 scope，取消未完成的任务

// ShutdownOnSuccess：任一成功即取消其他
try (var scope = new StructuredTaskScope.ShutdownOnSuccess<String>()) {
 scope.fork(() -> queryFromDB());
 scope.fork(() -> queryFromCache());
 scope.fork(() -> queryFromAPI());

 scope.join(); // 等待所有任务完成
 return scope.result(); // 返回第一个成功的结果
}

9. Generational ZGC（分代 ZGC）

Java 21 引入分代 ZGC，性能显著提升。

# 启用分代 ZGC（Java 21 中需显式开启，默认仍为非分代；分代模式自 JDK 24 起成为默认）
java -XX:+UseZGC -XX:+ZGenerational -Xmx4g MyApp

# 特点：
# - 吞吐量提升约 25%
# - 停顿时间仍然 < 1ms
# - 内存占用更低
# - 更好的大堆支持

10. 从 Java 17 迁移到 Java 21

特性	Java 17	Java 21
Record	✅	✅
Sealed Classes	✅	✅
Pattern Matching (instanceof)	✅	✅
Pattern Matching (switch)	预览	✅ 正式
Record Patterns	❌	✅
虚拟线程	预览	✅ 正式
Sequenced Collections	❌	✅
String Templates	❌	预览
Scoped Values	❌	预览
结构化并发	❌	预览
分代 ZGC	❌	✅

总结

Java 21 的核心特性：

虚拟线程 — 革命性并发模型，百万级线程不再是梦
Pattern Matching Switch — 类型匹配 + 守卫模式 + 穷举检查
Record Patterns — Record 的解构匹配
Sequenced Collections — 统一有序集合的操作
未命名变量 — 用 _ 忽略不需要的变量
分代 ZGC — 更强的低延迟垃圾收集

如果你在用 Spring Boot 3.2+/4.x，可以直接使用 Java 21。虚拟线程是最大的卖点——对于 IO 密集型服务，性能提升非常可观。

💡 Java 25 LTS 已于 2025 年 9 月发布，新增了 Scoped Values 正式版（JEP 506）、Compact Object Headers 正式版（JEP 519）等特性；Structured Concurrency 在 Java 25 中仍为预览特性（JEP 505，第五次预览）。如果是全新项目，建议直接上 Java 25。

Java 17 新特性详解：Record、Sealed Classes、Pattern Matching 与现代 Java

Thu, 25 Jun 2026 14:30:00 +0000

前言

Java 17 于 2021 年 9 月发布，是继 Java 8 和 Java 11 之后的第三个长期支持版本（LTS）。Spring Boot 3.x 最低要求 Java 17，这使得 Java 17 成为当前企业开发的主流版本。相比 Java 8，Java 17 引入了大量语法糖和现代化改进，显著提升了开发效率。

1. Record（记录类型）

Record 是一种特殊的类，专门用于存储不可变数据，自动生成 equals()、hashCode()、toString() 和 getter。

1.1 基本用法

// 定义 Record
public record Point(int x, int y) {}

// 使用
Point p = new Point(10, 20);
System.out.println(p.x()); // 10（注意：不是 getX()）
System.out.println(p.y()); // 20
System.out.println(p); // Point[x=10, y=20]

// 自动实现
p.equals(new Point(10, 20)) // true
p.hashCode() // 基于 x, y 计算

1.2 自定义方法和构造器

public record Point(int x, int y) {
 // 紧凑构造器（验证参数）
 public Point {
 if (x < 0 || y < 0) {
 throw new IllegalArgumentException("坐标不能为负数");
 }
 }

 // 自定义方法
 public double distanceTo(Point other) {
 return Math.sqrt(Math.pow(this.x - other.x, 2) + Math.pow(this.y - other.y, 2));
 }

 // 静态方法
 public static Point origin() {
 return new Point(0, 0);
 }
}

Point p1 = new Point(3, 4);
Point p2 = new Point(6, 8);
System.out.println(p1.distanceTo(p2)); // 5.0

1.3 实战场景

// DTO / VO
public record UserDTO(String name, String email, int age) {}

// API 响应
public record ApiResponse<T>(int code, String message, T data) {
 public static <T> ApiResponse<T> success(T data) {
 return new ApiResponse<>(200, "OK", data);
 }
 public static <T> ApiResponse<T> error(String message) {
 return new ApiResponse<>(500, message, null);
 }
}

// Map 的 Entry
public record KeyValue<K, V>(K key, V value) implements Map.Entry<K, V> {
 @Override
 public V setValue(V value) {
 throw new UnsupportedOperationException();
 }
}

2. Sealed Classes（密封类）

密封类限制哪些类可以继承或实现它，提供更精确的类型控制。

2.1 基本用法

// 定义密封类
public sealed class Shape permits Circle, Rectangle, Triangle {
 // 公共方法
}

// 子类必须是 final、sealed 或 non-sealed
public final class Circle extends Shape {
 double radius;
}

public final class Rectangle extends Shape {
 double width, height;
}

public non-sealed class Triangle extends Shape {
 double a, b, c;
 // non-sealed 允许任意类继承
}

2.2 与 Record 结合

// 配合 Record 实现代数数据类型（ADT）
public sealed interface Expression
 permits Number, Add, Multiply, Negate {
}

public record Number(double value) implements Expression {}
public record Add(Expression left, Expression right) implements Expression {}
public record Multiply(Expression left, Expression right) implements Expression {}
public record Negate(Expression operand) implements Expression {}

2.3 与 Pattern Matching 结合

// 模式匹配 + sealed = 穷举检查
public static double evaluate(Expression expr) {
 return switch (expr) {
 case Number n -> n.value();
 case Add a -> evaluate(a.left()) + evaluate(a.right());
 case Multiply m -> evaluate(m.left()) * evaluate(m.right());
 case Negate n -> -evaluate(n.operand());
 // 不需要 default，编译器知道已穷举所有子类
 };
}

3. Pattern Matching for instanceof

Java 14 引入、Java 16 转正。在 instanceof 判断的同时完成类型转换。

// 传统写法
if (obj instanceof String) {
 String s = (String) obj;
 System.out.println(s.length());
}

// Java 16+ 写法
if (obj instanceof String s) {
 System.out.println(s.length()); // s 已经是 String 类型
}

// 可以在条件中直接使用变量
if (obj instanceof String s && s.length() > 5) {
 System.out.println(s.toUpperCase());
}

// 在 equals 中的典型应用
@Override
public boolean equals(Object obj) {
 return this == obj
 || (obj instanceof Point p && this.x == p.x && this.y == p.y);
}

4. Text Blocks（文本块）

Java 15 转正。多行字符串不再需要转义和拼接。

// 传统写法
String json = "{\n" +
 " \"name\": \"Alice\",\n" +
 " \"age\": 30\n" +
 "}";

// Text Block 写法
String json = """
 {
 "name": "Alice",
 "age": 30
 }
 """;

// SQL
String sql = """
 SELECT u.name, u.email, o.total
 FROM users u
 JOIN orders o ON u.id = o.user_id
 WHERE u.status = 'ACTIVE'
 ORDER BY o.created_at DESC
 """;

// HTML
String html = """
 <html>
 <body>
 <h1>Hello, World!</h1>
 </body>
 </html>
 """;

// 支持格式化占位符
String greeting = """
 Hello, %s!
 Welcome to %s.
 """.formatted("Alice", "Java 17");

// 行尾空格处理
String text = """
 Line 1 \s
 Line 2 \s
 """;

5. Switch 表达式

Java 14 转正。Switch 不仅是语句，还可以是表达式。

// 传统写法
String result;
switch (day) {
 case MONDAY:
 case FRIDAY:
 case SUNDAY:
 result = "好好工作";
 break;
 case TUESDAY:
 result = "继续努力";
 break;
 default:
 result = "未知";
 break;
}

// Switch 表达式
String result = switch (day) {
 case MONDAY, FRIDAY, SUNDAY -> "好好工作";
 case TUESDAY -> "继续努力";
 case WEDNESDAY, THURSDAY -> "快到周末了";
 case SATURDAY -> "休息日";
};

// yield 返回值（多行时使用）
int numLetters = switch (day) {
 case MONDAY, FRIDAY, SUNDAY -> {
 System.out.println("工作日");
 yield 6;
 }
 case TUESDAY -> {
 System.out.println("又是工作日");
 yield 7;
 }
 default -> {
 String s = day.toString();
 yield s.length();
 }
};

// 穷举检查（配合 enum 或 sealed class）
// 不需要 default，编译器会检查是否覆盖所有情况

6. 新的 HttpClient API

Java 11 引入、Java 15 完善。替代老旧的 HttpURLConnection。

HttpClient client = HttpClient.newBuilder()
 .connectTimeout(Duration.ofSeconds(10))
 .build();

// GET 请求
HttpRequest request = HttpRequest.newBuilder()
 .uri(URI.create("https://api.example.com/users"))
 .header("Accept", "application/json")
 .GET()
 .build();

// 同步
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode());
System.out.println(response.body());

// 异步
client.sendAsync(request, HttpResponse.BodyHandlers.ofString())
 .thenApply(HttpResponse::body)
 .thenAccept(System.out::println)
 .join();

// POST JSON
HttpRequest postRequest = HttpRequest.newBuilder()
 .uri(URI.create("https://api.example.com/users"))
 .header("Content-Type", "application/json")
 .POST(HttpRequest.BodyPublishers.ofString("""
 {"name": "Alice", "age": 30}
 """))
 .build();

// POST 文件
HttpRequest fileRequest = HttpRequest.newBuilder()
 .uri(URI.create("https://api.example.com/upload"))
 .POST(HttpRequest.BodyPublishers.ofFile(Path.of("file.txt")))
 .build();

7. 其他重要特性

7.1 instanceof 模式的反模式

// 不推荐：多余的变量作用域
if (obj instanceof String s) {
 // s 可用
} else {
 // s 不可用
 // 如果在 else 中使用 s 会编译错误
}

// 推荐：在最窄的作用域中使用

7.2 NullPointerException 增强消息

# Java 14+ 增强了 NPE 的错误信息
# 之前: Cannot invoke method on null
# 之后: Cannot invoke "String.length()" because the return value of "User.getName()" is null

# 启用（默认开启）
-XX:+ShowCodeDetailsInExceptionMessages

7.3 强封装 JDK 内部 API

// Java 17 默认禁止反射访问 JDK 内部 API
// 如果必须使用，需要添加 JVM 参数：
// --add-opens java.base/java.lang=ALL-UNNAMED
// --add-opens java.base/sun.nio.ch=ALL-UNNAMED

7.4 新的随机数生成器 API

// Java 17 引入了 RandomGenerator 接口
RandomGenerator generator = RandomGeneratorFactory.of("L128X1024MixRandom").create();
int random = generator.nextInt(100);

// 获取所有可用算法
RandomGeneratorFactory.all()
 .map(f -> f.name() + " (" + f.group() + ")")
 .forEach(System.out::println);

7.5 ZGC（生产就绪）

# Java 15 转正的低延迟垃圾收集器
java -XX:+UseZGC -Xmx4g MyApp

# 特点：
# - 停顿时间 < 1ms（不随堆大小增长）
# - 支持 TB 级堆
# - 吞吐量下降不超过 15%

7.6 Shenandoah GC（生产就绪）

# Java 15 转正
java -XX:+UseShenandoahGC -Xmx4g MyApp

# 特点：
# - 与 ZGC 类似的低延迟
# - 更早进入生产就绪状态
# - 适合对延迟敏感的应用

8. 从 Java 8 迁移到 Java 17

8.1 主要变化清单

变化	说明
删除 `--release 8` 兼容性	确保代码不使用已删除的 API
删除 `javax.*` 包	部分迁移到 `jakarta.*`（EE 相关）
强封装内部 API	`sun.misc.*` 等不再可直接访问
Nashorn 移除	Java 15 移除了 JavaScript 引擎
安全管理器弃用	`SecurityManager` 将在未来版本移除

8.2 迁移检查清单

# 1. 编译检查
javac --release 17 YourClass.java

# 2. 检查对 JDK 内部 API 的非法访问（如有反射访问内部 API，运行时会报警告或异常）
# 注意：--illegal-access 选项自 JDK 17 起已失效（JEP 403 强封装），改用下列方式按需开放
java --add-opens java.base/java.lang=ALL-UNNAMED -jar app.jar

# 3. 依赖检查
# Spring Boot 3.x 需要 Java 17
# 检查所有第三方库是否支持 Java 17

# 4. JVM 参数调整
# 移除已废弃的 GC 参数
# 更新反射访问参数

8.3 Spring Boot 3.x 迁移

<!-- pom.xml -->
<properties>
 <java.version>17</java.version>
</properties>

<!-- jakarta 命名空间迁移 -->
<!-- javax.servlet.* → jakarta.servlet.* -->
<!-- javax.persistence.* → jakarta.persistence.* -->

9. 版本对比

特性	Java 8	Java 17
Lambda/Stream	✅	✅
Optional	✅	✅
新日期 API	✅	✅
Record	❌	✅
Sealed Classes	❌	✅
Pattern Matching	❌	✅
Text Blocks	❌	✅
Switch 表达式	❌	✅
新 HttpClient	❌	✅
ZGC/Shenandoah	❌	✅ (生产就绪)
LTS 支持截止	Extended 2030 年	Premier 2026.9，Extended 2029.9

总结

Java 17 的核心特性：

Record — 不可变数据类的简洁声明，自动生成样板代码
Sealed Classes — 限制类的继承层次，配合 switch 实现穷举检查
Pattern Matching — instanceof + 类型转换一步到位
Text Blocks — 多行字符串不再痛苦
Switch 表达式 — 更简洁、更安全的 switch
新 HttpClient — 现代化的 HTTP 客户端
ZGC/Shenandoah — 低延迟垃圾收集器正式可用

如果你的项目还在 Java 8，现在是升级到 Java 17 的好时机。Spring Boot 3.x/4.x、Spring Cloud 2022+ 都要求 Java 17 最低版本。

⚠️ 注意：Java 17 Premier Support 将于 2026 年 9 月 到期，建议新项目直接使用 Java 21 或 Java 25 LTS。

Java 8 新特性详解：Lambda、Stream、Optional 与函数式编程

Thu, 25 Jun 2026 14:00:00 +0000

前言

Java 8 是 Java 发展史上最重要的版本之一，于 2014 年 3 月发布。它引入了函数式编程思想，彻底改变了 Java 的编码风格。至今仍有大量项目运行在 Java 8 上，掌握其特性是 Java 开发者的基本功。

1. Lambda 表达式

Lambda 是 Java 8 最核心的特性，让代码更简洁、更具表达力。

1.1 基本语法

// 语法: (参数列表) -> { 方法体 }

// 无参数
Runnable r = () -> System.out.println("Hello Lambda");

// 单个参数（可省略括号）
Consumer<String> print = s -> System.out.println(s);

// 多个参数
Comparator<String> comp = (a, b) -> a.length() - b.length();

// 多行方法体
BinaryOperator<Integer> add = (a, b) -> {
 int result = a + b;
 return result;
};

1.2 Lambda 与匿名内部类对比

// 之前：匿名内部类
List<String> list = Arrays.asList("c", "a", "b");
Collections.sort(list, new Comparator<String>() {
 @Override
 public int compare(String a, String b) {
 return a.compareTo(b);
 }
});

// 之后：Lambda
Collections.sort(list, (a, b) -> a.compareTo(b));
// 更简洁
Collections.sort(list, String::compareTo);

1.3 变量捕获

int num = 10; // effectively final
Runnable r = () -> System.out.println(num); // OK
// num = 20; // 编译错误，Lambda 要求变量为 final 或 effectively final

2. 函数式接口

函数式接口是只有一个抽象方法的接口，是 Lambda 的基础。

2.1 内置函数式接口

接口	方法	用途	示例
`Predicate<T>`	`boolean test(T t)`	条件判断	`s -> s.length() > 5`
`Function<T,R>`	`R apply(T t)`	类型转换	`s -> s.length()`
`Consumer<T>`	`void accept(T t)`	消费数据	`s -> System.out.println(s)`
`Supplier<T>`	`T get()`	生产数据	`() -> new ArrayList<>()`
`BiFunction<T,U,R>`	`R apply(T t, U u)`	双参数转换	`(a, b) -> a + b`
`UnaryOperator<T>`	`T apply(T t)`	一元操作	`s -> s.toUpperCase()`
`BinaryOperator<T>`	`T apply(T a, T b)`	二元操作	`(a, b) -> a + b`

2.2 自定义函数式接口

@FunctionalInterface
interface MyFunction<T, R> {
 R apply(T t);

 // 可以有默认方法
 default MyFunction<T, R> andThen(MyFunction<R, R> after) {
 return t -> after.apply(this.apply(t));
 }
}

// 使用
MyFunction<String, Integer> toLength = String::length;
MyFunction<String, Integer> toUpper = s -> s.toUpperCase().length();
System.out.println(toLength.apply("hello")); // 5
System.out.println(toLength.andThen(toUpper).apply("hello")); // 注意：这里类型不匹配需调整

3. 方法引用

方法引用是 Lambda 的简写形式。

// 1. 静态方法引用: ClassName::staticMethod
Function<String, Integer> parseInt = Integer::parseInt;
// 等价于: s -> Integer.parseInt(s)

// 2. 实例方法引用: instance::method
String str = "Hello";
Supplier<String> upper = str::toUpperCase;
// 等价于: () -> str.toUpperCase()

// 3. 对象方法引用: ClassName::method
Function<String, Integer> length = String::length;
// 等价于: s -> s.length()

// 4. 构造方法引用: ClassName::new
Supplier<ArrayList<String>> listFactory = ArrayList::new;
Function<Integer, ArrayList<String>> listWithCap = ArrayList::new;
// 等价于: n -> new ArrayList<>(n)

4. Stream API

Stream 是 Java 8 处理集合的核心 API，支持链式操作、惰性求值和并行处理。

4.1 创建 Stream

// 从集合创建
List<String> list = Arrays.asList("a", "b", "c");
Stream<String> stream = list.stream();

// 从数组创建
String[] arr = {"a", "b", "c"};
Stream<String> stream2 = Arrays.stream(arr);

// 直接创建
Stream<String> stream3 = Stream.of("a", "b", "c");

// 生成无限流
Stream<Integer> infinite = Stream.iterate(0, n -> n + 1);
Stream<Double> random = Stream.generate(Math::random);

// 范围流
IntStream range = IntStream.range(1, 10); // 1-9
IntStream rangeClosed = IntStream.rangeClosed(1, 10); // 1-10

// 文件流
Stream<String> lines = Files.lines(Paths.get("file.txt"));

4.2 中间操作（惰性）

List<String> names = Arrays.asList("Alice", "Bob", "Charlie", "David", "Eve");

// filter - 过滤
names.stream().filter(s -> s.length() > 3);

// map - 映射转换
names.stream().map(String::toUpperCase);
names.stream().map(String::length);

// flatMap - 扁平化映射
List<List<Integer>> nested = Arrays.asList(
 Arrays.asList(1, 2, 3),
 Arrays.asList(4, 5, 6)
);
nested.stream().flatMap(Collection::stream);
// 结果: 1, 2, 3, 4, 5, 6

// sorted - 排序
names.stream().sorted();
names.stream().sorted(Comparator.comparing(String::length).reversed());

// distinct - 去重
Stream.of(1, 2, 2, 3, 3).distinct(); // 1, 2, 3

// limit / skip - 截取
names.stream().limit(3); // 前3个
names.stream().skip(2); // 跳过前2个

// peek - 查看（调试用）
names.stream()
 .peek(s -> System.out.println("Before: " + s))
 .map(String::toUpperCase)
 .peek(s -> System.out.println("After: " + s))
 .collect(Collectors.toList());

4.3 终端操作

List<String> names = Arrays.asList("Alice", "Bob", "Charlie", "David");

// collect - 收集
List<String> result = names.stream()
 .filter(s -> s.length() > 3)
 .collect(Collectors.toList());

Set<String> set = names.stream().collect(Collectors.toSet());

String joined = names.stream().collect(Collectors.joining(", "));
// "Alice, Bob, Charlie, David"

// reduce - 归约
int sum = IntStream.rangeClosed(1, 100).reduce(0, Integer::sum);
// 5050

Optional<String> longest = names.stream()
 .reduce((a, b) -> a.length() >= b.length() ? a : b);

// count / min / max
long count = names.stream().filter(s -> s.startsWith("A")).count();
Optional<String> min = names.stream().min(String::compareTo);
Optional<String> max = names.stream().max(Comparator.comparing(String::length));

// forEach
names.stream().forEach(System.out::println);

// toArray
String[] array = names.stream().toArray(String[]::new);

// 匹配操作
boolean anyStartsWithA = names.stream().anyMatch(s -> s.startsWith("A"));
boolean allLongerThan3 = names.stream().allMatch(s -> s.length() > 3);
boolean noneStartsWithZ = names.stream().noneMatch(s -> s.startsWith("Z"));

// find
Optional<String> first = names.stream().filter(s -> s.length() > 3).findFirst();
Optional<String> any = names.stream().filter(s -> s.length() > 3).findAny();

4.4 Collectors 高级用法

List<Employee> employees = getEmployees();

// 分组
Map<String, List<Employee>> byDept = employees.stream()
 .collect(Collectors.groupingBy(Employee::getDepartment));

// 分组计数
Map<String, Long> countByDept = employees.stream()
 .collect(Collectors.groupingBy(Employee::getDepartment, Collectors.counting()));

// 分组求和
Map<String, Double> salaryByDept = employees.stream()
 .collect(Collectors.groupingBy(
 Employee::getDepartment,
 Collectors.summingDouble(Employee::getSalary)
 ));

// 分区（按条件分为两组）
Map<Boolean, List<Employee>> partitioned = employees.stream()
 .collect(Collectors.partitioningBy(e -> e.getSalary() > 10000));

// 统计
DoubleSummaryStatistics stats = employees.stream()
 .collect(Collectors.summarizingDouble(Employee::getSalary));
// stats.getCount(), stats.getSum(), stats.getAverage(), stats.getMax(), stats.getMin()

// toMap
Map<String, Double> salaryMap = employees.stream()
 .collect(Collectors.toMap(Employee::getName, Employee::getSalary));

// 有重复 key 时的处理
Map<String, Double> salaryMap2 = employees.stream()
 .collect(Collectors.toMap(Employee::getDepartment, Employee::getSalary, Double::sum));

4.5 并行流

// 串行转并行
long count = list.parallelStream()
 .filter(s -> s.length() > 3)
 .count();

// 或者
long count2 = list.stream()
 .parallel()
 .filter(s -> s.length() > 3)
 .count();

// 注意：并行流使用 ForkJoinPool，不适合 IO 密集型任务
// 数据量小时串行更快，并行有线程切换开销

5. Optional

Optional 用于优雅地处理可能为 null 的值，避免 NullPointerException。

5.1 创建 Optional

Optional<String> empty = Optional.empty();
Optional<String> opt = Optional.of("hello"); // 不能传 null
Optional<String> nullable = Optional.ofNullable(null); // 可以传 null

5.2 常用方法

Optional<String> opt = Optional.ofNullable(getName());

// isPresent / isEmpty
if (opt.isPresent()) {
 System.out.println(opt.get());
}

// ifPresent - 值存在时执行
opt.ifPresent(name -> System.out.println(name));
// 注意：ifPresentOrElse 是 Java 9 新增方法，Java 8 不可用
// Java 9+ 写法：
// opt.ifPresentOrElse(
// name -> System.out.println("Name: " + name),
// () -> System.out.println("Name is null")
// );

// orElse - 提供默认值
String name = opt.orElse("Unknown");
String name2 = opt.orElseGet(() -> computeDefault()); // 惰性求值
String name3 = opt.orElseThrow(() -> new RuntimeException("Name not found"));

// map / flatMap - 链式转换
Optional<Integer> length = opt.map(String::length);
Optional<String> upper = opt.map(String::toUpperCase);

// filter - 条件过滤
Optional<String> filtered = opt.filter(s -> s.length() > 3);

5.3 实战链式调用

// 传统写法
public String getUserCity(User user) {
 if (user != null) {
 Address addr = user.getAddress();
 if (addr != null) {
 String city = addr.getCity();
 if (city != null) {
 return city.toUpperCase();
 }
 }
 }
 return "UNKNOWN";
}

// Optional 写法
public String getUserCity(User user) {
 return Optional.ofNullable(user)
 .map(User::getAddress)
 .map(Address::getCity)
 .map(String::toUpperCase)
 .orElse("UNKNOWN");
}

6. 新的日期时间 API

Java 8 引入了 java.time 包，彻底解决了旧日期 API 的线程安全和设计缺陷。

// LocalDate - 只有日期
LocalDate today = LocalDate.now();
LocalDate birthday = LocalDate.of(1990, 6, 15);
LocalDate parsed = LocalDate.parse("2025-01-01");
int year = today.getYear();
int month = today.getMonthValue();
LocalDate nextWeek = today.plusWeeks(1);
LocalDate lastMonth = today.minusMonths(1);
boolean isBefore = today.isBefore(birthday);

// LocalTime - 只有时间
LocalTime now = LocalTime.now();
LocalTime time = LocalTime.of(14, 30, 0);
LocalTime later = now.plusHours(2);

// LocalDateTime - 日期 + 时间
LocalDateTime dateTime = LocalDateTime.now();
LocalDateTime specific = LocalDateTime.of(2025, 1, 1, 12, 0);

// ZonedDateTime - 带时区
ZonedDateTime zoned = ZonedDateTime.now(ZoneId.of("Asia/Shanghai"));

// Instant - 时间戳（UTC）
Instant instant = Instant.now();
long epochSecond = instant.getEpochSecond();
long epochMilli = instant.toEpochMilli();

// Duration - 时间段（秒/纳秒）
Duration duration = Duration.between(startTime, endTime);
Duration twoHours = Duration.ofHours(2);
long seconds = duration.getSeconds();

// Period - 日期段（年/月/日）
Period period = Period.between(startDate, endDate);
Period threeMonths = Period.ofMonths(3);
int days = period.getDays();

// 格式化
DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
String formatted = dateTime.format(formatter);
LocalDateTime parsed2 = LocalDateTime.parse("2025-01-01 12:00:00", formatter);

7. CompletableFuture

异步编程利器，支持链式调用和组合。

// 创建异步任务
CompletableFuture<String> future = CompletableFuture.supplyAsync(() -> {
 // 耗时操作
 return fetchDataFromDB();
});

// 链式处理
CompletableFuture<Integer> result = CompletableFuture
 .supplyAsync(() -> "Hello")
 .thenApply(s -> s + " World") // 同步转换
 .thenApply(String::length); // 同步转换

// 异步处理
CompletableFuture<Void> future2 = CompletableFuture
 .supplyAsync(() -> fetchData())
 .thenAcceptAsync(data -> saveToDB(data)); // 异步消费

// 组合多个异步任务
CompletableFuture<String> userFuture = CompletableFuture.supplyAsync(() -> getUser());
CompletableFuture<String> orderFuture = CompletableFuture.supplyAsync(() -> getOrder());

CompletableFuture<String> combined = userFuture.thenCombine(orderFuture,
 (user, order) -> user + " - " + order);

// 等待所有完成
CompletableFuture.allOf(future1, future2, future3).join();

// 任一完成
CompletableFuture.anyOf(future1, future2, future3).join();

// 异常处理
CompletableFuture<String> safe = CompletableFuture
 .supplyAsync(() -> riskyOperation())
 .exceptionally(ex -> "Default Value")
 .handle((result, ex) -> ex != null ? "Error" : result);

8. 其他新特性

8.1 接口默认方法和静态方法

public interface Vehicle {
 // 抽象方法
 void start();

 // 默认方法（有实现）
 default void honk() {
 System.out.println("Beep!");
 }

 // 静态方法
 static boolean isMotorized(Vehicle v) {
 return true;
 }
}

8.2 重复注解

@Repeatable(Schedules.class)
@interface Schedule {
 String time();
}

@interface Schedules {
 Schedule[] value();
}

@Schedule(time = "08:00")
@Schedule(time = "12:00")
@Schedule(time = "18:00")
public void doSomething() { }

8.3 Base64 编解码

// 基本编码
String encoded = Base64.getEncoder().encodeToString("Hello".getBytes());
byte[] decoded = Base64.getDecoder().decode(encoded);

// URL 安全编码
String urlSafe = Base64.getUrlEncoder().encodeToString(data);

// MIME 编码
String mime = Base64.getMimeEncoder().encodeToString(data);

9. 版本选择建议

场景	建议
老项目维护	继续使用 Java 8，Extended Support 到 2030 年（Oracle JDK 需订阅）
新项目启动	建议直接使用 Java 21 或 25（均为 LTS）
Spring Boot 4.x	最低要求 Java 17，推荐 Java 21+
学习 Lambda/Stream	Java 8 特性是最基础的，必须掌握

💡 LTS 版本线：Java 8 → 11 → 17 → 21 → 25（2025 年 9 月发布）→ 29（2027 年 9 月）

总结

Java 8 的核心特性：

Lambda 表达式 — 简化匿名内部类，函数式编程的基础
函数式接口 — Predicate/Function/Consumer/Supplier 四大金刚
方法引用 — Lambda 的简写形式
Stream API — 集合操作的声明式编程，支持并行处理
Optional — 优雅处理空值，避免 NPE
新日期时间 API — 线程安全、设计合理的 java.time 包
CompletableFuture — 异步编程的链式调用

这些特性至今仍是 Java 开发的核心基础，无论使用哪个 JDK 版本都必须熟练掌握。

2025 年 Java Spring 面试题精选

Fri, 01 May 2026 14:00:00 +0000

概述

本文整理了 2025 年常见的 Java Spring 面试题，涵盖 Spring Core、Spring Boot、Spring MVC、Spring Cloud 等核心知识点，帮助开发者系统备战面试。

一、Spring Core

1. 什么是 IoC（控制反转）？

IoC 是一种设计思想，将对象的创建和依赖管理交给 Spring 容器，而不是由开发者手动 new 对象。Spring 通过依赖注入（DI）实现 IoC，降低了代码耦合度。

2. Spring Bean 的作用域有哪些？

作用域	说明
`singleton`	默认，整个容器中只有一个实例
`prototype`	每次请求创建一个新的实例
`request`	每次 HTTP 请求创建一个实例（Web 应用）
`session`	每个 HTTP Session 创建一个实例
`application`	每个 ServletContext 创建一个实例

3. @Autowired 和 @Resource 的区别？

@Autowired：Spring 注解，默认按类型注入，可配合 @Qualifier 按名称注入
@Resource：JSR-250 注解，默认按名称注入，找不到再按类型注入

4. Spring Bean 的生命周期？

实例化 Bean
属性注入（依赖注入）
调用 BeanNameAware、BeanFactoryAware 等接口
调用 BeanPostProcessor#postProcessBeforeInitialization
调用 @PostConstruct / InitializingBean#afterPropertiesSet / init-method
调用 BeanPostProcessor#postProcessAfterInitialization
Bean 就绪，可使用
调用 @PreDestroy / DisposableBean#destroy / destroy-method

二、Spring Boot

5. Spring Boot 的核心优势？

自动配置：根据引入的依赖自动配置 Bean
起步依赖：简化 Maven/Gradle 依赖管理
内嵌服务器：无需外部 Tomcat，直接 java -jar 运行
Actuator：提供生产级监控端点

6. @SpringBootApplication 注解的作用？

@SpringBootApplication 是组合注解，包含：

@SpringBootConfiguration：标记为配置类
@EnableAutoConfiguration：启用自动配置
@ComponentScan：扫描当前包及子包的组件

7. Spring Boot 自动配置原理？

核心是 @EnableAutoConfiguration 注解，通过 SpringFactoriesLoader 加载 META-INF/spring.factories（Spring Boot 3.x 改为 META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports）中定义的自动配置类。结合 @Conditional 系列注解（如 @ConditionalOnClass、@ConditionalOnMissingBean）按条件决定是否生效。

8. 如何自定义 Starter？

创建 xxx-spring-boot-autoconfigure 模块，编写自动配置类
创建 xxx-spring-boot-starter 模块，引入 autoconfigure 依赖
在 META-INF/spring.factories 或 AutoConfiguration.imports 中注册

三、Spring MVC

9. Spring MVC 的请求处理流程？

客户端发送请求到 DispatcherServlet
DispatcherServlet 查询 HandlerMapping 获取对应的 Handler
通过 HandlerAdapter 调用具体的 Controller 方法
Controller 处理业务，返回 ModelAndView
ViewResolver 解析视图名称
渲染视图并返回响应

10. @RestController 和 @Controller 的区别？

@Controller：返回视图名称，需要配合 @ResponseBody 返回数据
@RestController：等价于 @Controller + @ResponseBody，所有方法默认返回 JSON/XML

四、Spring Cloud

11. 常见的服务注册中心有哪些？

Nacos：阿里开源，支持配置管理和服务发现
Eureka：Netflix 开源，AP 模型（已停止维护）
Consul：HashiCorp 出品，支持健康检查
Zookeeper：CP 模型，强一致性

12. 什么是服务熔断和降级？

熔断：当下游服务异常率超过阈值时，熔断器打开，快速失败，避免雪崩
降级：熔断后的兜底策略，返回默认值或缓存数据

常用框架：Sentinel、Resilience4j、Hystrix（已停止维护）

13. Spring Cloud Gateway 核心概念？

Route（路由）：网关的基本单元
Predicate（断言）：匹配请求条件
Filter（过滤器）：对请求/响应进行处理

五、数据访问

14. Spring 事务传播行为有哪些？

传播行为	说明
`REQUIRED`	默认，有则加入，无则创建
`REQUIRES_NEW`	总是新建事务，挂起当前事务
`SUPPORTS`	有则加入，无则非事务执行
`NOT_SUPPORTED`	非事务执行，挂起当前事务
`MANDATORY`	必须在事务中，否则抛异常
`NEVER`	不能在事务中，否则抛异常
`NESTED`	嵌套事务，外部回滚则一起回滚

15. @Transactional 失效的常见场景？

方法非 public 修饰
同类方法内部调用（未经过代理）
异常被 catch 未抛出
抛出的异常类型不是 RuntimeException
数据库引擎不支持事务（如 MyISAM）

六、并发与缓存

16. Spring 中如何使用缓存？

@Cacheable(value = "users", key = "#id")
public User getUserById(Long id) {
 return userMapper.selectById(id);
}

@CacheEvict(value = "users", key = "#id")
public void deleteUser(Long id) {
 userMapper.deleteById(id);
}

支持的缓存实现：Redis、Caffeine、EhCache 等。

17. @Async 异步执行注意事项？

需在启动类添加 @EnableAsync
方法需为 public，且不能在同一个类内部调用
推荐自定义线程池，避免使用默认的 SimpleAsyncTaskExecutor

总结

以上是 2025 年高频 Java Spring 面试题的核心要点。建议结合源码理解底层原理，而不仅仅背诵答案。Spring 生态不断演进，持续关注 Spring Boot 3.x 和 Spring Cloud 2024/2025 版本的新特性至关重要。