🎯 今日核心问题

  1. 怎么做到"加一个 @Tool 方法就自动可用",而不用在每个 AiService 里手工列工具?
  2. 模型返回的参数是 JSON,怎么安全地映射到 Java 方法签名并反射执行?
  3. 工具怎么用上 Spring 的依赖注入、事务和请求上下文(TraceId、当前用户)?
  4. 为什么反射执行工具必须做权限与白名单校验,而不是"反正方法名是模型给的"?

📖 精读提纲

【一】工具注册表的本质:一张 name → (bean, method, schema) 的映射

框不框架,工具注册就三件事:发现(哪些 Bean 的哪些方法算工具)、描述(生成一份可发给模型的 schema 列表)、执行(按 name 找到方法,把 JSON 参数反序列化后 invoke)。LangChain4j 的 AiServices.tools(...) 已经替你做了这三步,但它的问题是无法在运行时增删、无法按用户权限过滤工具集、也不方便加统一埋点。所以生产环境通常自己维护一层 DynamicToolRegistry:启动时扫描所有带 @Tool 的方法构建注册表,每次请求按租户/权限过滤出可用工具列表,执行时走统一的超时、日志、异常包装。

【二】参数绑定:反射执行最容易出事的三个点

第一,类型转换。模型给的 "2026-10-29" 要变成 LocalDate,"1" 要变成 Boolean.TRUE,标量参数用 Jackson 的 convertValue 转,复杂参数直接 readValue 成 DTO——统一用 ObjectMapper 而不是自己 Integer.parseInt。第二,缺省参数。可选参数模型可能不给,反射调用时 null 会进方法体,DTO 更安全:先反序列化成 DTO 再 invoke,缺的字段自然为 null,跟你定义的默认值逻辑一致。第三,异常边界。业务方法抛出的异常绝不能直接冒到框架层,必须转成结构化的错误结果返回给模型,否则整个 Agent 循环就断了(D5 详述)。

【三】实战应用:Spring Boot 场景

典型的 Controller → AgentService → ToolRegistry → (Tool → Repository/HttpClient) 四层。Controller 只收 {sessionId, message};AgentService 负责多轮循环;ToolRegistry 是纯技术组件,不含业务判断;Tool 类是薄封装,内部调用 Repository 或外部 Client,方法上可正常使用 @Transactional——但要注意,工具方法被反射调用时走的仍然是 Spring 代理对象,所以 bean.method() 这种反射方式能拿到事务增强,前提是你从容器里取的是代理 Bean 而不是 getClass() 新建的实例。同理,@Async、@Retryable 都生效。TraceId 通过 RequestContextHolder 或 MDC 传递,因为反射调用发生在同一线程内(并行调用时例外,见 D6)。

【四】常见误区

💻 代码示例

一个可运行的动态注册表,包含启动扫描、schema 生成、按权限过滤和反射执行:

public record ToolDef(String name, Object bean, Method method,
                      ToolSpecification spec, String group) {}

@Component
@Slf4j
public class DynamicToolRegistry implements ApplicationContextAware {

    private final Map<String, ToolDef> byName = new ConcurrentHashMap<>();
    private final ObjectMapper mapper;
    private ApplicationContext ctx;

    public DynamicToolRegistry(ObjectMapper mapper) { this.mapper = mapper; }

    @Override
    public void setApplicationContext(ApplicationContext ctx) {
        this.ctx = ctx;
        // 扫描所有带 @Tool 方法的 Bean
        for (String beanName : ctx.getBeanDefinitionNames()) {
            Object bean;
            try { bean = ctx.getBean(beanName); } catch (Exception e) { continue; }
            Class<?> target = AopUtils.getTargetClass(bean);
            if (AnnotationUtils.findAnnotation(target, Component.class) == null) continue;

            for (Method m : ReflectionUtils.getAllDeclaredMethods(target)) {
                Tool ann = AnnotationUtils.findAnnotation(m, Tool.class);
                if (ann == null) continue;

                String name = ann.name().isBlank() ? m.getName() : ann.name();
                ToolSpecification spec = ToolSpecifications.toolSpecificationFrom(m);
                Group g = AnnotationUtils.findAnnotation(target, Group.class);
                byName.put(name, new ToolDef(name, bean, m, spec,
                        g == null ? "default" : g.value()));
                log.info("registered tool {} -> {}.{}", name, target.getSimpleName(), m.getName());
            }
        }
        log.info("tool registry ready, total={}", byName.size());
    }

    /** 给模型用的工具清单:按权限组过滤,避免把用户没权限的工具暴露出去 */
    public List<ToolSpecification> specsFor(Set<String> allowedGroups) {
        return byName.values().stream()
                .filter(t -> allowedGroups.contains(t.group()) || "default".equals(t.group()))
                .map(ToolDef::spec)
                .toList();
    }

    /** 反射执行:name + 原始 JSON 参数 → 结果对象 */
    public Object invoke(String name, String rawArgumentsJson) {
        ToolDef def = byName.get(name);
        if (def == null) throw new UnknownToolException(name);   // 模型幻觉工具名

        Object[] args = bindArguments(def.method(), rawArgumentsJson);
        try {
            return def.method().invoke(def.bean(), args);
        } catch (InvocationTargetException e) {
            throw new ToolExecutionException(name, e.getTargetException());
        } catch (IllegalAccessException e) {
            throw new IllegalStateException("tool not accessible: " + name, e);
        }
    }

    private Object[] bindArguments(Method method, String json) {
        Parameter[] params = method.getParameters();
        if (params.length == 1 && !isScalar(params[0].getType())) {
            // 单 DTO 参数:直接反序列化,未提供的字段自然为 null
            return new Object[]{ mapper.convertValue(readTree(json), params[0].getType()) };
        }
        JsonNode root = readTree(json);
        Object[] out = new Object[params.length];
        for (int i = 0; i < params.length; i++) {
            JsonNode v = root.get(params[i].getName());
            if (v == null || v.isNull()) {
                out[i] = params[i].getType().isPrimitive() ? defaultOf(params[i].getType()) : null;
            } else {
                // 用 Jackson 转换,兼容 "1" → Boolean、ISO 字符串 → LocalDate
                out[i] = mapper.convertValue(v, params[i].getType());
            }
        }
        return out;
    }

    private JsonNode readTree(String json) {
        try {
            return json == null || json.isBlank() ? mapper.createObjectNode() : mapper.readTree(json);
        } catch (Exception e) {
            throw new ToolArgumentException("invalid json: " + json, e);
        }
    }

    private static boolean isScalar(Class<?> t) {
        return t.isPrimitive() || t == String.class || Number.class.isAssignableFrom(t)
            || t == Boolean.class || t == LocalDate.class || t == LocalDateTime.class;
    }

    private static Object defaultOf(Class<?> t) {
        if (t == boolean.class) return false;
        if (t == int.class) return 0;
        if (t == long.class) return 0L;
        if (t == double.class) return 0d;
        return null;
    }
}

在 AgentService 里把它接进循环,工具清单按当前用户过滤:

@Service
@RequiredArgsConstructor
public class AgentService {

    private final ChatModel model;
    private final DynamicToolRegistry registry;

    @Transactional(propagation = Propagation.NOT_SUPPORTED) // 模型调用不占用数据库连接
    public String chat(String userMessage, Set<String> userGroups) {
        List<ToolSpecification> tools = registry.specsFor(userGroups);
        ChatResponse resp = model.chat(
                ChatRequest.builder()
                        .messages(List.of(SystemMessage.from("你是订单助手,只回答事实,不确定就调工具。"),
                                          UserMessage.from(userMessage)))
                        .toolSpecifications(tools)
                        .build());

        for (ToolExecutionRequest req : resp.aiMessage().toolExecutionRequests()) {
            Object result = registry.invoke(req.name(), req.arguments());
            // 结果转 JSON 字符串回填,结构统一(D4 展开)
            return model.chat(ChatRequest.builder()
                    .messages(List.of(
                            SystemMessage.from("你是订单助手。"),
                            UserMessage.from(userMessage),
                            resp.aiMessage(),
                            ToolExecutionResultMessage.from(req,
                                    mapper.writeValueAsString(result))))
                    .build()).aiMessage().text();
        }
        return resp.aiMessage().text();
    }
}

✏️ 今日动手

1)实现 DynamicToolRegistry,启动后打印注册表(工具名 / 所属类 / 权限组),确认 @Tool 方法全部被发现且没有重名覆盖。

2)暴露 GET /api/tools 返回当前可用工具 schema 列表,用真实模型跑三次不同问题,检查每次 specsFor 过滤是否生效(用一个没有 admin 组的用户,确认高危工具不出现)。

3)写单元测试覆盖三种参数绑定:单 DTO、多标量、缺省必填参数。故意传 {"orderNo":"A123","withItems":"true"}(字符串布尔),验证 convertValue 能正确转成 true;再传非法日期,确认抛的是 ToolArgumentException 而不是 NPE。

🔖 明日预告

注册和执行都通了,下一个问题是:工具该返回什么?返 OrderView 序列化后的 JSON,还是返一句"该订单已发货,但不支持退款"?两种做法后面的 Agent 表现差异很大。明天用实验数据对比结构化与自然语言返回值。