🎯 今日核心问题
- 怎么做到"加一个
@Tool方法就自动可用",而不用在每个 AiService 里手工列工具? - 模型返回的参数是 JSON,怎么安全地映射到 Java 方法签名并反射执行?
- 工具怎么用上 Spring 的依赖注入、事务和请求上下文(TraceId、当前用户)?
- 为什么反射执行工具必须做权限与白名单校验,而不是"反正方法名是模型给的"?
📖 精读提纲
【一】工具注册表的本质:一张 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)。
【四】常见误区
- ❌ 用
Class.forName+ new 实例反射——绕过了 Spring 容器,注入全为 null,事务注解也失效。 - ❌ 注册表 key 用
method.getName()——两个类有同名方法就互相覆盖,应该用显式工具名或类简名.方法名。 - ❌ 忽略
setAccessible(true)在模块化环境下的限制——优先把工具方法声明为public。 - ❌ 每次请求重新扫描注解构建 schema——开销虽小但毫无必要,启动期构建 + 缓存,变更走显式刷新接口。
- ❌ 允许模型调用任意 Bean 方法(比如把
ApplicationContext塞进去)——工具白名单必须是显式的。
💻 代码示例
一个可运行的动态注册表,包含启动扫描、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 表现差异很大。明天用实验数据对比结构化与自然语言返回值。