🎯 今日核心问题
- Agent 项目的分层和传统 MVC 有什么不同?为什么「工具」必须是一个独立的层?
- 单体多模块还是单体单模块?拆模块的收益在哪一天开始兑现?
- 依赖选型上,哪些地方值得多花一天,哪些地方应该果断用最笨的方案?
📖 精读提纲
【一】五层结构:把「不确定」关进一个盒子
传统 MVC 里,Service 层是稳定逻辑。Agent 项目恰好相反:模型调用是整条链路上最不确定的一段,所以要把所有不确定性收进一层,其余各层保持确定性、可单测。
- api 层:Controller + DTO,只做参数校验与鉴权,不含任何业务判断。
- agent 层:Prompt 组装、ReAct 循环、上下文裁剪、终止条件。不确定性的唯一容身处。
- tool 层:每个工具是一个实现
AgentTool的 Bean,入参出参都是强类型 record,自己负责降级与超时。 - domain 层:订单、工单这类纯业务模型与规则,不依赖任何 LLM SDK。
- infra 层:模型客户端、向量库、数据库、缓存、消息队列的具体实现。
关键约束:domain 层不允许 import agent 层的任何类。这条用 ArchUnit 一条测试就能守住,违反时构建直接失败。分层不是画给面试官看的,是让「换模型」变成只改 infra 层的一个类。
【二】模块怎么切
不要一上来就拆微服务或多 Maven 模块。两周项目的最佳实践是单模块 + 包结构严格分层:需求还不稳定时切模块,切一次改一次。如果非要拆,只拆 core(domain + tool 契约)与 app(api + agent + infra)——这两个之间的依赖是真稳定,其余都是猜的。包命名直接映射层,评审时看目录树就知道有没有越层。
【三】依赖选型的三条原则
- 能用官方 SDK 就别自己包 HTTP:模型调用用 LangChain4j 或厂商官方 SDK,但必须再包一层自己的
LlmClient接口,理由是可 mock、可换厂商、可加超时与重试。 - 流式输出第一天就要定:
SseEmitter或 WebFlux 的Flux二选一,后面改成本极高。同步 Controller 返完整 JSON 的项目,到 D5 想加打字机效果几乎要重写。 - trace 表必须手写:Agent 要记录每轮 thought/action/observation,用 MySQL 8 的
JSON列存比建十张关联表实用得多。
【四】第一天就要有的三件东西
- 统一返回体与异常处理:
ApiResult<T>+@RestControllerAdvice,错误码枚举化。Agent 的失败种类多(模型超时、工具失败、预算耗尽、内容被拦),没有统一错误码,前端和运维都会被搞疯。 - 配置分层:
application.yml只放非敏感默认值,密钥从环境变量注入,通过@ConfigurationProperties强类型绑定。不要出现散落各处的@Value。 - 一个能跑通空链路的 happy path:Controller → Agent(假实现)→ echo 工具 → 返回。当天必须完成,它是后面所有工作的地基。
三件东西里,第二件最容易被跳过,但它决定了 D5 那天是「改两行环境变量」还是「翻遍全仓库找硬编码的 key」。
💻 代码示例
工具契约与注册表——整个项目最重要的抽象,一次定对省掉后面无数返工:
public interface AgentTool {
String name();
String description();
String jsonSchema();
SideEffect sideEffect();
ToolResult execute(Map<String, Object> args, ToolContext ctx);
enum SideEffect { READ_ONLY, IDEMPOTENT_WRITE, NON_IDEMPOTENT_WRITE }
}
public record ToolResult(boolean success, String observation, String errorCode) {
public static ToolResult ok(String obs) { return new ToolResult(true, obs, null); }
public static ToolResult fail(String c) { return new ToolResult(false, "工具执行失败:" + c, c); }
}
public record ToolContext(String traceId, String userId, Instant deadline) {
public boolean expired() { return Instant.now().isAfter(deadline); }
}
@Component
public class ToolRegistry {
private final Map<String, AgentTool> tools;
public ToolRegistry(List<AgentTool> beans) {
this.tools = beans.stream().collect(Collectors.toUnmodifiableMap(AgentTool::name, t -> t));
}
public AgentTool get(String name) {
AgentTool t = tools.get(name);
if (t == null) throw new IllegalArgumentException("未注册的工具: " + name);
return t;
}
/** 只读工具才允许进入自动重试白名单 */
public List<AgentTool> retryable() {
return tools.values().stream()
.filter(t -> t.sideEffect() != AgentTool.SideEffect.NON_IDEMPOTENT_WRITE)
.toList();
}
}
目录结构直接照这个建:
src/main/java/com/example/agent/
├── api/ AgentController, ApiResult, GlobalExceptionHandler
├── agent/ ReActLoop, PromptBuilder, ContextTrimmer
├── tool/ AgentTool, ToolRegistry, tool/impl/OrderQueryTool
├── domain/ Order, Ticket, OrderRepository(接口)
└── infra/ LlmClient, MyBatisOrderRepository, TraceStore
【五】依赖选型的具体对照
- 模型调用:LangChain4j 1.x 或官方 SDK,不要在 RestTemplate 上自己搓——工具调用协议、流式解析、重试都要自己实现。
- 结构化输出:模型原生 structured outputs + Jackson 二次校验,不用正则抽 JSON。
- 向量库:PGVector(与业务库同实例)或 Qdrant,两周项目不值得为向量库单独运维。
- 观测:Actuator + Micrometer,指标命名与分位数都有现成实现。
这张表的用法不是照抄,而是每一行都要能说出「为什么不选另一个」。被问「为什么不用 Spring AI」,能答出「ChatClient 更偏对话场景,LangChain4j 的 AiServices 做工具绑定更直接」就够了。依赖版本别追新,Spring Boot 3.2 + JDK 17 + LangChain4j 1.x 是当前最稳的组合。
【六】DTO 要分两套
Controller 的 DTO 和工具入参不要复用。Controller 收用户视角字段(question、sessionId),工具收模型视角字段(严格 schema、必填少、类型窄)。混用的后果是模型去填 sessionId,或用户能在工具参数里注入不该给的字段。多写三十行转换,换掉一整类越权问题。
另外 jsonSchema() 里的字段描述要当 Prompt 写:orderNo 与 orderNo(形如 ORD-2026xxxx,用户没提供就留空) 在填参准确率上能差 8 个百分点。
✏️ 今日动手
建工程、写死五层包结构、把 AgentTool + ToolRegistry + 一个真实工具落地。下面这个 OrderQueryTool 已经是可用的实现(依赖注入 repository,参数严格校验,失败返回结构化错误),照抄改表名即可:
@Component
@RequiredArgsConstructor
public class OrderQueryTool implements AgentTool {
private final OrderRepository repo;
@Override public String name() { return "query_order"; }
@Override public String description() {
return "按订单号查询订单状态与金额。订单号形如 ORD-2026xxxx。";
}
@Override public String jsonSchema() {
return "{\"type\":\"object\",\"properties\":{"
+ "\"orderNo\":{\"type\":\"string\",\"description\":\"订单号,形如 ORD-20261215\"},"
+ "\"detail\":{\"type\":\"boolean\",\"description\":\"是否返回商品明细\"}},"
+ "\"required\":[\"orderNo\"]}";
}
@Override public SideEffect sideEffect() { return SideEffect.READ_ONLY; }
@Override
public ToolResult execute(Map<String, Object> args, ToolContext ctx) {
Object raw = args.get("orderNo");
if (raw == null || String.valueOf(raw).isBlank()) {
return ToolResult.fail("MISSING_ORDER_NO");
}
String orderNo = String.valueOf(raw).trim().toUpperCase();
if (!orderNo.matches("^ORD-\\d{8}$")) {
return ToolResult.fail("INVALID_ORDER_NO");
}
return repo.findByNo(orderNo)
.filter(o -> o.userId().equals(ctx.userId())) // 数据级隔离,不信任模型传的 userId
.map(o -> ToolResult.ok(o.toObservation()))
.orElseGet(() -> ToolResult.fail("ORDER_NOT_FOUND"));
}
}
注意三处设计:userId 只从 ctx 取、参数先校验再查库、找不到订单返回 ORDER_NOT_FOUND 而不是空字符串——空字符串会让模型误以为「查到了但没有内容」,进而编造。
再用 curl 打一次 /api/agent/chat 拿到结果,并加一条 ArchUnit 测试断言 domain 层不依赖 agent 层。
🔖 明日预告
骨架有了,明天把它接活:Controller 收请求、Agent 跑 ReAct 循环、工具被真实调用、结果带着 trace 回到前端,并把每一步落库。