Spring Boot on 吾爱主机

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 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 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 生命周期尾段的系统来说，这是成本最低、收益最高的一步。

Elasticsearch 完全指南：从原理到实战的全面教程

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

前言

Elasticsearch（简称 ES）是基于 Lucene 的分布式实时全文搜索引擎，能够快速存储、搜索和分析海量数据。它是 ELK 技术栈的核心组件，广泛应用于日志分析、全文搜索、实时监控等场景。

1. 核心概念

1.1 与 MySQL 对比

ES 概念	MySQL 概念	说明
Index（索引）	Database（数据库）	数据存储的地方
Type（类型）	Table（表）	ES7+ 已移除
Document（文档）	Row（行）	最小数据单元
Field（字段）	Column（列）	最小单位
Shard（分片）	—	数据水平拆分
Replica（副本）	—	高可用备份

1.2 倒排索引原理

倒排索引是 ES 高性能搜索的核心。与正向索引（文档→关键词）相反，倒排索引是关键词→文档 ID 的映射。

正向索引：文档1 → [苏州街, 维亚大厦]
倒排索引：苏州街 → [文档1, 文档2]
 维亚大厦 → [文档1]
 桔子酒店 → [文档2]

倒排索引的结构：

组件	说明
Term（词项）	分词后的单词
Term Dictionary（词典）	所有词项的集合
Term Index（词项索引）	加速查找词项的索引（FST 结构）
Posting List（倒排列表）	包含词项的文档 ID、词频、位置等

1.3 text 与 keyword 的区别

类型	分词	适用场景	示例
text	会分词	全文搜索	文章标题、描述
keyword	不分词	精确匹配、排序、聚合	状态码、邮箱、标签

1.4 query 与 filter 的区别

对比项	query	filter
相关性评分	✅ 计算 `_score`	❌ 不计算
性能	较慢	更快
缓存	不缓存	可缓存结果
使用场景	全文搜索	精确过滤

2. 安装与配置

2.1 Docker 安装

# 单节点启动
docker run -d --name elasticsearch \
 -p 9200:9200 -p 9300:9300 \
 -e "discovery.type=single-node" \
 -e "xpack.security.enabled=false" \
 -e "ES_JAVA_OPTS=-Xms512m -Xmx512m" \
 elasticsearch:8.13.0

2.2 Docker Compose 部署（ES + Kibana）

version: '3.8'
services:
 elasticsearch:
 image: elasticsearch:8.13.0
 container_name: elasticsearch
 environment:
 - discovery.type=single-node
 - xpack.security.enabled=false
 - ES_JAVA_OPTS=-Xms1g -Xmx1g
 ports:
 - "9200:9200"
 - "9300:9300"
 volumes:
 - es_data:/usr/share/elasticsearch/data

 kibana:
 image: kibana:8.13.0
 container_name: kibana
 environment:
 - ELASTICSEARCH_HOSTS=http://elasticsearch:9200
 ports:
 - "5601:5601"
 depends_on:
 - elasticsearch

volumes:
 es_data:

2.3 核心配置（elasticsearch.yml）

cluster.name: my-cluster
node.name: node-1
network.host: 0.0.0.0
http.port: 9200
discovery.seed_hosts: ["node-1", "node-2", "node-3"]
cluster.initial_master_nodes: ["node-1"]

# 内存锁定（避免 swap）
bootstrap.memory_lock: true

2.4 验证安装

# 检查集群状态
curl http://localhost:9200/_cluster/health?pretty

# 查看节点信息
curl http://localhost:9200/_cat/nodes?v

# 查看所有索引
curl http://localhost:9200/_cat/indices?v

3. REST API — CRUD 操作

3.1 创建文档

# 指定 ID
PUT /my-index/_doc/1
{
 "name": "张三",
 "age": 25,
 "email": "zhangsan@example.com"
}

# 自动生成 ID
POST /my-index/_doc
{
 "name": "李四",
 "age": 30
}

3.2 获取文档

GET /my-index/_doc/1

# 只返回指定字段
GET /my-index/_doc/1?_source=name,email

3.3 更新文档

# 全量更新（覆盖）
PUT /my-index/_doc/1
{
 "name": "张三",
 "age": 26
}

# 部分更新
POST /my-index/_update/1
{
 "doc": {
 "age": 26
 }
}

3.4 删除文档

DELETE /my-index/_doc/1

3.5 批量操作（Bulk API）

POST _bulk
{"index": {"_index": "my-index", "_id": "3"}}
{"name": "王五", "age": 28}
{"index": {"_index": "my-index", "_id": "4"}}
{"name": "赵六", "age": 32}
{"update": {"_index": "my-index", "_id": "1"}}
{"doc": {"age": 27}}
{"delete": {"_index": "my-index", "_id": "2"}}

💡 性能提示：Bulk API 建议每批 5-15MB，不要超过 1000 条。

4. Mapping（映射）

4.1 字段类型

类型	说明	示例
text	全文检索，会被分词	标题、描述
keyword	精确值，不分词	邮箱、状态码
integer/long	整数	年龄、数量
float/double	浮点	价格、评分
date	日期	创建时间
boolean	布尔	是否启用
geo_point	地理坐标	经纬度
nested	嵌套对象数组	评论列表
object	对象类型	地址信息

4.2 创建显式映射

PUT /products
{
 "settings": {
 "number_of_shards": 3,
 "number_of_replicas": 1
 },
 "mappings": {
 "properties": {
 "name": {
 "type": "text",
 "analyzer": "ik_max_word",
 "search_analyzer": "ik_smart",
 "fields": {
 "keyword": { "type": "keyword" }
 }
 },
 "price": { "type": "double" },
 "category": { "type": "keyword" },
 "tags": { "type": "keyword" },
 "createTime": {
 "type": "date",
 "format": "yyyy-MM-dd HH:mm:ss"
 },
 "isActive": { "type": "boolean" }
 }
 }
}

4.3 映射参数

参数	说明
analyzer	写入时的分词器
search_analyzer	搜索时的分词器
fields	多字段映射（如 text + keyword）
index	是否建立索引（默认 true）
doc_values	是否开启列式存储（用于排序/聚合）
coerce	是否自动类型转换

4.4 数据迁移（Reindex）

已存在的映射字段不能修改，需要创建新索引后迁移：

# 创建新索引
PUT /new-index
{ "mappings": { ... } }

# 迁移数据
POST _reindex
{
 "source": { "index": "old-index" },
 "dest": { "index": "new-index" }
}

# 切换别名
POST _aliases
{
 "actions": [
 { "remove": { "index": "old-index", "alias": "my-alias" } },
 { "add": { "index": "new-index", "alias": "my-alias" } }
 ]
}

5. Query DSL

5.1 查询所有

GET /my-index/_search
{
 "query": { "match_all": {} },
 "from": 0,
 "size": 10,
 "sort": [{ "createTime": { "order": "desc" } }]
}

5.2 match（全文检索）

# 单字段匹配
GET /my-index/_search
{
 "query": {
 "match": { "name": "苹果手机" }
 }
}

# 短语匹配（不分词，整体匹配）
GET /my-index/_search
{
 "query": {
 "match_phrase": { "name": "苹果手机" }
 }
}

# 多字段匹配
GET /my-index/_search
{
 "query": {
 "multi_match": {
 "query": "苹果",
 "fields": ["name^3", "description"]
 }
 }
}

5.3 term（精确匹配）

# keyword 字段精确匹配
GET /my-index/_search
{
 "query": {
 "term": { "category": "电子产品" }
 }
}

5.4 range（范围查询）

GET /my-index/_search
{
 "query": {
 "range": {
 "price": {
 "gte": 100,
 "lte": 500
 }
 }
 }
}

5.5 bool（复合查询）

GET /my-index/_search
{
 "query": {
 "bool": {
 "must": [
 { "match": { "name": "手机" } }
 ],
 "filter": [
 { "term": { "category": "电子产品" } },
 { "range": { "price": { "gte": 1000, "lte": 5000 } } }
 ],
 "must_not": [
 { "term": { "isActive": false } }
 ],
 "should": [
 { "term": { "tags": "热销" } }
 ]
 }
 }
}

5.6 其他查询

# 通配符查询
{ "wildcard": { "name": "苹果*" } }

# 模糊查询（容错）
{ "fuzzy": { "name": "苹果" } }

# 前缀查询
{ "prefix": { "name": "苹果" } }

# 字段存在查询
{ "exists": { "field": "email" } }

# ID 查询
{ "ids": { "values": ["1", "2", "3"] } }

6. Aggregations（聚合）

6.1 桶聚合（分组）

# 按字段分组
GET /my-index/_search
{
 "size": 0,
 "aggs": {
 "by_category": {
 "terms": { "field": "category", "size": 10 }
 }
 }
}

# 按日期分桶
GET /my-index/_search
{
 "size": 0,
 "aggs": {
 "by_month": {
 "date_histogram": {
 "field": "createTime",
 "calendar_interval": "month"
 }
 }
 }
}

# 范围分桶
GET /my-index/_search
{
 "size": 0,
 "aggs": {
 "price_ranges": {
 "range": {
 "field": "price",
 "ranges": [
 { "to": 100 },
 { "from": 100, "to": 500 },
 { "from": 500 }
 ]
 }
 }
 }
}

6.2 指标聚合（计算）

# 统计聚合
GET /my-index/_search
{
 "size": 0,
 "aggs": {
 "price_stats": { "stats": { "field": "price" } },
 "price_avg": { "avg": { "field": "price" } },
 "price_sum": { "sum": { "field": "price" } },
 "unique_categories": { "cardinality": { "field": "category" } }
 }
}

6.3 嵌套聚合

# 按类别分组，计算每组的平均价格和最高价格
GET /my-index/_search
{
 "size": 0,
 "aggs": {
 "by_category": {
 "terms": { "field": "category", "size": 10 },
 "aggs": {
 "avg_price": { "avg": { "field": "price" } },
 "max_price": { "max": { "field": "price" } }
 }
 }
 }
}

7. Analysis（分析器）

7.1 分析器组成

原始文本 → [字符过滤器] → [分词器] → [分词过滤器] → 词项输出

7.2 内置分析器

分析器	说明
Standard	默认，按 Unicode 分割，小写化
Simple	按非字母分割，小写化
Whitespace	按空格分割
Keyword	不分词，整体作为一个词项
Pattern	正则表达式分割

7.3 IK 中文分词器

IK Analyzer 是最常用的中文分词插件，提供两种模式：

模式	说明	使用场景
ik_smart	粗粒度分词	搜索时
ik_max_word	细粒度分词	索引时

# 测试分词
POST _analyze
{
 "analyzer": "ik_smart",
 "text": "中华人民共和国国歌"
}
# 结果：中华人民共和国 / 国歌

POST _analyze
{
 "analyzer": "ik_max_word",
 "text": "中华人民共和国国歌"
}
# 结果：中华人民共和国 / 中华人民共和 / 中华 / 人民共和国 / 人民 / 共和国 / 共和 / 国歌

7.4 自定义分析器

PUT /my-index
{
 "settings": {
 "analysis": {
 "analyzer": {
 "my_analyzer": {
 "type": "custom",
 "char_filter": ["html_strip"],
 "tokenizer": "standard",
 "filter": ["lowercase", "stop", "snowball"]
 }
 }
 }
 }
}

8. 索引管理

8.1 别名（Alias）

# 创建别名
POST _aliases
{
 "actions": [
 { "add": { "index": "my-index-v1", "alias": "my-index" } }
 ]
}

# 零停机切换索引
POST _aliases
{
 "actions": [
 { "remove": { "index": "my-index-v1", "alias": "my-index" } },
 { "add": { "index": "my-index-v2", "alias": "my-index" } }
 ]
}

8.2 索引模板

PUT _index_template/logs-template
{
 "index_patterns": ["logs-*"],
 "template": {
 "settings": {
 "number_of_shards": 3,
 "number_of_replicas": 1
 },
 "mappings": {
 "properties": {
 "timestamp": { "type": "date" },
 "message": { "type": "text" },
 "level": { "type": "keyword" }
 }
 }
 }
}

8.3 ILM（索引生命周期管理）

PUT _ilm/policy/logs-policy
{
 "policy": {
 "phases": {
 "hot": {
 "actions": {
 "rollover": {
 "max_size": "50GB",
 "max_age": "1d"
 }
 }
 },
 "warm": {
 "min_age": "7d",
 "actions": {
 "shrink": { "number_of_shards": 1 },
 "forcemerge": { "max_num_segments": 1 }
 }
 },
 "delete": {
 "min_age": "30d",
 "actions": { "delete": {} }
 }
 }
 }
}

9. 性能优化

9.1 索引优化

策略	说明
批量导入时关闭副本	`number_of_replicas: 0`
调整 refresh_interval	改为 30s 减少 refresh 频率
使用 Bulk API	每批 5-15MB
使用 SSD	提升 IO 性能
增大 translog 刷盘阈值	`flush_threshold_size: 1gb`

9.2 查询优化

策略	说明
用 filter 替代 query	filter 可缓存，不计算评分
避免 nested 和 parent-child	nested 慢几倍，parent-child 慢几百倍
使用 keyword 而非 integer	keyword 查询更快
强制合并只读索引	`forcemerge` 到单个 segment
预热 filesystem cache	`index.store.preload`

9.3 JVM 调优

# 堆内存：Min(节点内存/2, 32GB)
ES_JAVA_OPTS=-Xms16g -Xmx16g

# 关闭 swap
bootstrap.memory_lock: true

# 最大文件句柄数
ulimit -n 65535

9.4 分片策略

策略	建议
分片数量	节点数 × (1~3)
单分片大小	10-50GB
副本数量	`max(max_failures, ceil(节点数/主分片数) - 1)`
分片不可修改	设置后不能改，需 reindex

9.5 冷热分离

热数据（最近 7 天）→ SSD 节点 → 高性能查询
温数据（7-30 天） → HDD 节点 → force_merge + shrink
冷数据（>30 天） → 归档/删除 → ILM 自动管理

10. Spring Boot 集成

10.1 版本兼容

Spring Boot	ES 版本	Spring Data ES
4.x	8.x	5.x
3.x	8.x	5.x
2.7.x	7.17.x	4.4.x

10.2 依赖配置

<dependency>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-data-elasticsearch</artifactId>
</dependency>

spring:
 elasticsearch:
 uris: localhost:9200
 username: elastic
 password: changeme

10.3 实体类

@Data
@Document(indexName = "products")
public class Product {
 @Id
 private String id;

 @MultiField(
 mainField = @Field(type = FieldType.Text, analyzer = "ik_max_word", searchAnalyzer = "ik_smart"),
 otherFields = @InnerField(suffix = "keyword", type = FieldType.Keyword)
 )
 private String name;

 @Field(type = FieldType.Text, analyzer = "ik_max_word")
 private String description;

 @Field(type = FieldType.Double)
 private BigDecimal price;

 @Field(type = FieldType.Keyword)
 private String category;

 @Field(type = FieldType.Date, format = DateFormat.date_hour_minute_second)
 private LocalDateTime createTime;
}

10.4 Repository 接口

@Repository
public interface ProductRepository extends ElasticsearchRepository<Product, String> {
 List<Product> findByName(String name);
 List<Product> findByCategory(String category);
 List<Product> findByPriceBetween(BigDecimal min, BigDecimal max);
 Page<Product> findByCategory(String category, Pageable pageable);
}

10.5 新版 Elasticsearch Java Client

// 替代已废弃的 RestHighLevelClient
ElasticsearchClient client = new ElasticsearchClient(
 new ElasticsearchTransport(
 new RestClientTransport(
 RestClient.builder(new HttpHost("localhost", 9200)),
 new JacksonJsonpMapper()
 )
 )
);

// 复杂查询
SearchResponse<Product> response = client.search(s -> s
 .index("products")
 .query(q -> q.bool(b -> b
 .must(m -> m.match(mt -> mt.field("name").query("手机")))
 .filter(f -> f.term(t -> t.field("category").value("电子产品")))
 .filter(f -> f.range(r -> r.field("price").gte(JsonData.of(1000))))
 ))
 .from(0).size(10),
 Product.class
);

11. ELK 技术栈

11.1 架构

应用日志 → Filebeat → Logstash → Elasticsearch → Kibana
 ↓
 过滤、转换、富化

11.2 组件说明

组件	作用
Elasticsearch	存储、索引、搜索、分析
Logstash	数据收集、过滤、转换
Kibana	数据可视化、仪表盘
Filebeat	轻量级日志采集器

11.3 Filebeat 配置

filebeat.inputs:
- type: log
 enabled: true
 paths:
 - /var/log/*.log

output.logstash:
 hosts: ["localhost:5044"]

11.4 Logstash 配置

input {
 beats { port => 5044 }
}

filter {
 grok { match => { "message" => "%{COMBINEDAPACHELOG}" } }
 date { match => [ "timestamp", "dd/MMM/yyyy:HH:mm:ss Z" ] }
}

output {
 elasticsearch {
 hosts => ["localhost:9200"]
 index => "logs-%{+YYYY.MM.dd}"
 }
}

12. 常见面试题

问题	要点
什么是倒排索引？	关键词→文档 ID 的映射，与正向索引相反
ES 写入流程？	协调节点→主分片→memory buffer→translog→refresh→flush
ES 搜索流程？	Query Then Fetch：先查 ID，再取文档
近实时搜索？	refresh 默认每秒一次，数据从 buffer 到 cache 才可搜索
如何避免脑裂？	ES 7+ 已移除 minimum_master_nodes，由集群协调层（voting configuration）自动防脑裂；首次启动配置 cluster.initial_master_nodes，并将 master 与 data 角色分离
分片数量怎么定？	节点数 × (1~3)，单分片 10-50GB，设置后不可改
query vs filter？	query 计算评分，filter 不计算可缓存
分析器组成？	字符过滤器 + 分词器 + 分词过滤器

总结

Elasticsearch 核心知识点：

倒排索引 — ES 高性能搜索的核心原理
Query DSL — match/term/bool/filter 构建复杂查询
聚合分析 — 桶聚合 + 指标聚合实现数据分析
IK 分词 — 中文搜索必备
Mapping — 字段类型和映射参数的合理配置
性能优化 — 分片策略、冷热分离、JVM 调优
Spring Boot 集成 — Repository + 新版 Java Client
ELK 栈 — 日志采集、处理、存储、可视化的完整方案

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 容器化

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 版本的新特性至关重要。

Spring Boot on 吾爱主机

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

一、Agent 的最小闭环

二、依赖和模型

三、用 Java 接口定义 AI Service

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

五、绑定模型、Memory 和 Tools

六、Chat Memory 不是业务数据库

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

八、如何对工具做测试

1. 纯 Java 工具测试

2. 模型工具选择测试

3. 端到端故障测试

九、MCP 什么时候加入

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

十一、常见问题

模型从不调用工具

同一用户的对话串到一起

退款工具被重复调用

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

换模型后效果明显变化

十二、生产清单

总结

参考资料

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

一、为什么需要 Supervisor

二、环境与依赖

三、先写最窄的业务工具

四、构建两个专业 ReactAgent

五、把子 Agent 变成 Supervisor 的工具

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

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

八、常见问题与排查

1. 子 Agent 从不被调用

2. 依赖冲突或类找不到

3. 时间被理解错

4. 重启后任务消失

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

九、什么时候不用多 Agent

总结

参考资料

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

这次发布的关键信息

2025.0.13 包含哪些模块

值得关注的修复点

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

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

3. Spring Data JPA：Hibernate 依赖升级

Maven 项目怎么升级

Gradle 项目怎么升级

升级前后的回归检查清单

升级前

升级后

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

团队落地建议

小结

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

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

二、这次实际更新了什么

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

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

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

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

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

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

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

五、怎么升级到 3.5.16

Maven

Gradle

六、升级后重点验证什么

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

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

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

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

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

升级前

升级中

升级后

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

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

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

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