🎯 今日核心问题

  1. Agent 项目的分层和传统 MVC 有什么不同?为什么「工具」必须是一个独立的层?
  2. 单体多模块还是单体单模块?拆模块的收益在哪一天开始兑现?
  3. 依赖选型上,哪些地方值得多花一天,哪些地方应该果断用最笨的方案?

📖 精读提纲

【一】五层结构:把「不确定」关进一个盒子

传统 MVC 里,Service 层是稳定逻辑。Agent 项目恰好相反:模型调用是整条链路上最不确定的一段,所以要把所有不确定性收进一层,其余各层保持确定性、可单测。

关键约束:domain 层不允许 import agent 层的任何类。这条用 ArchUnit 一条测试就能守住,违反时构建直接失败。分层不是画给面试官看的,是让「换模型」变成只改 infra 层的一个类。

【二】模块怎么切

不要一上来就拆微服务或多 Maven 模块。两周项目的最佳实践是单模块 + 包结构严格分层:需求还不稳定时切模块,切一次改一次。如果非要拆,只拆 core(domain + tool 契约)与 app(api + agent + infra)——这两个之间的依赖是真稳定,其余都是猜的。包命名直接映射层,评审时看目录树就知道有没有越层。

【三】依赖选型的三条原则

【四】第一天就要有的三件东西

  1. 统一返回体与异常处理:ApiResult<T> + @RestControllerAdvice,错误码枚举化。Agent 的失败种类多(模型超时、工具失败、预算耗尽、内容被拦),没有统一错误码,前端和运维都会被搞疯。
  2. 配置分层:application.yml 只放非敏感默认值,密钥从环境变量注入,通过 @ConfigurationProperties 强类型绑定。不要出现散落各处的 @Value。
  3. 一个能跑通空链路的 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

【五】依赖选型的具体对照

这张表的用法不是照抄,而是每一行都要能说出「为什么不选另一个」。被问「为什么不用 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 回到前端,并把每一步落库。