我造了一个 Java 能力包:让 AI 直接调用你的业务代码

我造了一个 Java 能力包:让 AI 直接调用你的业务代码

一个注解,把你的业务方法变成大模型能用的工具。 本文源码已开源:gitee.com/wizard-cn/u...

大家好,我是小巫。

今天不聊概念,聊一个我自己造、自己天天在用的东西------um-sdk。

它解决的问题很朴素:Java 项目里那些反反复复要写一遍的东西,能不能只写一次?

工具类、枚举、支付、邮件、缓存......每个项目都要抄一遍。更麻烦的是,这两年大家都在接大模型、接 AI 助手,可业务代码怎么让 AI 调起来,又是一套全新的体力活。

于是我干脆把这些都收进了一个包,还顺手把 AI 那一层也焊了进去。


先说结论:它到底能干什么

一句话:一套依赖,干掉日常 Java 开发 80% 的重复造轮子工作,还能让 AI 直接调用你的业务方法。

比如你在写一个订单系统,想让 AI 助手能查订单。传统做法是你得啃 MCP 协议、拼 JSON-RPC、手写参数描述......折腾半天。

用 um-sdk,你只需要这样:

java 复制代码
public class OrderTools {

    @McpTool(name = "query_order", description = "按订单号查询订单详情")
    public String query(@McpParam(name = "orderNo", description = "订单号", required = true) String orderNo) {
        return JacksonUtils.toJson(orderService.findByNo(orderNo));
    }
}

就这一坨代码,你的订单查询能力就变成了 AI 可调用的工具。

然后起一个 Stdio 服务,在 Cursor 或 Claude 里配一下地址,AI 就能自己调你的方法了:

java 复制代码
McpServer server = McpServer.builder()
        .name("Order MCP")
        .version("1.0.0")
        .transport(Transport.stdio())
        .scan(OrderTools.class)
        .build();
server.start();

这就是我觉得 um-sdk 最有意思的地方------AI 能力不是外挂,而是原生的一等公民。


出现原因:为什么我非要自己造一个

先说清楚背景,这个包不是凭空冒出来的。

我是一个写了十几年 Java 的人。这些年里,我发现自己和团队一直在重复三件事:

第一件,工具类到处复制粘贴。 每个新项目开局,第一件事就是从老项目里把 DateUtils、HttpUtils、AesUtils 拷过来。拷完之后还要改------因为这个项目 JDK 是 17,那个是 8;这个用了 hutool,那个不许引第三方。同一段 MD5 逻辑,我写过不下二十遍。

第二件,枚举永远不够用。 业务方要加一个订单状态,你得改代码、发版。业务方要支持英文展示,你得在每个枚举里塞翻译。业务方要字典表能配置,你得推翻重写。

第三件,AI 时代的新体力活。 2024 年之后,几乎每个项目都开始接大模型。可你很快会发现:OpenAI 一套 SDK、DeepSeek 一套、百炼一套、本地 Ollama 又是一套。想换个模型,等于重写一遍接入层。

这三件事叠加起来,就有了 um-sdk 的定位:

把"所有 Java 项目都要写的重复件"收进一个包,再把"所有 AI 应用都要写的重复件"也收进同一个包。

适用场景很广:Spring Boot 微服务、纯 Java 命令行工具、边缘设备、Serverless 函数、甚至嵌入式 Java 场景。


先看整体架构

um-sdk 按两条技术栈组织,底座是共享的基础模块:

graph TB subgraph 应用宿主层 SA[um-spring-starter<br/>Spring Boot 宿主] UA[um-ultra-starter<br/>轻量框架宿主] end subgraph 框架层 SP[Spring Boot<br/>宿主自带, compileOnly] UL[um-ultra<br/>零依赖 IoC/AOP] end subgraph um-ultra 生态 UW[um-ultra-web<br/>Netty] UD[um-ultra-db<br/>MyBatis-Plus] UC[um-ultra-cache<br/>三介质缓存] UN[um-ultra-nacos<br/>注册配置] end subgraph 基础能力层 UT[um-util<br/>工具集] UE[um-enums<br/>动态枚举] EP[um-epay<br/>支付] ML[um-mail<br/>邮件] MC[um-mcp<br/>MCP 协议] AG[um-agent<br/>LLM Agent] end SA --> SP SA --> UT SA --> UE SA --> EP SA --> ML SA --> MC SA --> AG UA --> UL UA --> UW UA --> UD UA --> UC UA --> UN UA --> EP UA --> ML UA --> MC UA --> AG UL --> UT UL --> UE UW --> UL UD --> UL UC --> UL UN --> UL AG --> MC MC --> UT

重点看两个地方:

左边 up-spring-starter ------ 你已经有 Spring Boot 项目,想加 AI 能力?引它就行,不动架构。Spring 依赖只做 compileOnly,版本完全你自己掌控。

右边 um-ultra-starter ------ 你想彻底离开 Spring,跑一个毫秒级启动的轻量服务?引它,IoC、AOP、Web、DB、缓存、注册中心全套都有。

底座是 6 个基础模块,零框架强依赖,任何 Java 项目都能直接用。


五分钟上手:三行依赖跑起来

第一步:加仓库

xml 复制代码
<repositories>
    <repository>
        <id>um-nexus</id>
        <url>https://nexus.umnet.com.cn/repository/um-maven/</url>
    </repository>
    <repository>
        <id>aliyun-public</id>
        <url>https://maven.aliyun.com/repository/public/</url>
    </repository>
</repositories>

第二步:引依赖

想只引一块能力,就引单模块:

gradle 复制代码
implementation 'cn.com.umnet:um-util:1.3.21-SNAPSHOT'

想加 AI 能力:

gradle 复制代码
implementation 'cn.com.umnet:um-mcp:1.3.21-SNAPSHOT'
implementation 'cn.com.umnet:um-agent:1.3.21-SNAPSHOT'

Spring Boot 项目全家桶:

gradle 复制代码
implementation 'cn.com.umnet:um-spring-starter:1.3.21-SNAPSHOT'

第三步:写代码

先来个最简单的------工具类,静态调用,不需要任何容器:

java 复制代码
// 安全执行:异常不炸业务,失败给默认值
int size = TryUtils.get(() -> Integer.parseInt(input)).orElse(0);

// 一行 JWT 签发与校验
String token = SimpleJwtUtils.sign("userId=1001", secret, 3600);
String data  = SimpleJwtUtils.verify(token, secret);

// 树形结构一行建
List<TreeNode> menu = TreeBuilder.build(flatList, "id", "parentId", "children");

// 带重试的 HTTP 调用
RetryPolicy policy = RetryPolicy.of(3, Duration.ofSeconds(1), 2.0);
String resp = SimpleHttpUtils.getWithRetry(url, policy);

没有 Spring,没有启动类,没有配置文件。引进来就能用。

这就是 um-util 的设计底线:工具类不应该需要你为它准备运行环境。


核心能力详解

一、um-util:把工具类做透

um-util 有 20 多个静态工具类,我按用途分了几组:

分组 代表类 解决什么
基础 StrUtils AssertUtils BeanUtils 字符串、断言、Bean 拷贝
加密 AesUtils RsaUtils SignUtils 对称/非对称加解密、签名验签
数据 JacksonUtils TreeBuilder 统一 JSON、树形结构
网络 SimpleHttpUtils RetryPolicy HTTP 调用、重试策略
实用 SimpleJwtUtils QrcodeUtils TryUtils ProfilerUtils JWT、二维码、安全执行、耗时分析
监控 Jvm Server JVM 与服务运行时指标

其中我私心最喜欢的是 TryUtils。Java 里最烦的就是 try-catch 套娃,一个方法里写三个 try-catch,可读性直接崩。

TryUtils 把它压成一行:

java 复制代码
// 传统写法
int result;
try {
    result = Integer.parseInt(input);
} catch (NumberFormatException e) {
    result = 0;
}

// TryUtils 写法
int result = TryUtils.get(() -> Integer.parseInt(input)).orElse(0);

这一行代码背后,是几百个重复的 try-catch 被删掉。

二、um-enums:让枚举活过来

普通 Java 枚举是死的------写死在代码里,改一次发一次版。

um-enums 做了两件事:

第一,描述支持国际化。 一个枚举项,中文叫"已支付",英文叫"Paid",不用你在枚举里塞一堆翻译方法。

第二,支持 SPI 动态供给。 通过 EnumProvider 接口,你可以在运行时从数据库、配置中心拉取枚举项。业务方要加状态?往字典表加一行就行,不用发版。

java 复制代码
// 按 code 取多语言描述
String zh = EnumUtils.getDescription(OrderStatus.class, "PAID", "zh-CN");
String en = EnumUtils.getDescription(OrderStatus.class, "PAID", "en");

// 通过代理做属性访问
EnumProxy<OrderStatus> proxy = EnumUtils.proxy(OrderStatus.class);
OrderStatus s = proxy.valueOf("PAID");

三、um-mcp:AI 调用的桥梁(核心亮点)

这部分我展开讲讲,因为它是整个 SDK 里最有前瞻性的模块。

MCP 是什么? 简单说,它是让大模型能够调用外部工具的一套标准协议。类比一下:USB 是设备连接电脑的标准接口,MCP 就是 AI 连接业务系统的标准接口。

um-sdk 把 MCP 实现成了一个注解驱动的小框架,提供三种传输方式:

传输 适用场景 类比
Stdio 被 Cursor/Claude 直接调用 打印机插电脑,独占
HTTP 多个 Agent 共享服务 网络打印机,谁都能连
Embedded 进程内直连,本地测试 内置模块,无需外接

注解体系也很简单,四个注解够用:

注解 作用
@McpTool 声明一个工具方法
@McpParam 声明工具参数(含描述、是否必填)
@McpResource 声明一个资源(如缓存、文件)
@McpPrompt 声明提示模板

完整示例:

java 复制代码
public class WeatherTools {

    @McpTool(name = "get_weather", description = "查询指定城市天气")
    public String getWeather(
            @McpParam(name = "city", description = "城市名", required = true) String city) {
        return WeatherClient.query(city);
    }

    @McpResource(uri = "weather://cache", name = "天气缓存")
    public String getCache() {
        return JacksonUtils.toJson(WeatherCache.getAll());
    }
}

注意 description 这个字段------它是写给大模型看的。 你描述得越清楚,AI 调用得越准。这件事的重要性,写过 Prompt 的人都懂。

四、um-agent:五家模型,一行切换(核心亮点)

有了工具还不够,还得有个 Agent 去组织大模型和工具的对话。

um-agent 提供统一抽象,支持五家平台:

java 复制代码
Agent agent = AgentBuilder.create()
        .platform(LlmPlatform.DEEPSEEK, c -> c.apiKey(key).model("deepseek-chat"))
        .systemPrompt("你是运维助手,能调用工具查系统状态")
        .mcp("http://localhost:9005/mcp")   // 自动挂载远端 MCP 工具
        .memory(new FileMemory("./.agent-memory"))
        .build();

agent.chat("帮我查下今天有哪些告警,汇总成表格", event -> {
    if (event.type() == StreamType.CONTENT_DELTA) {
        System.out.print(event.delta());
    }
});

换成 OpenAI 只需要改一行:

java 复制代码
.platform(LlmPlatform.OPENAI, c -> c.apiKey(key).model("gpt-4o"))

它内置了几个我认为很实用的能力:

  • 工具调用循环 ------ 自动处理"模型要调工具 → 执行 → 结果回传模型"的循环
  • 流式输出 ------ 事件回调逐字输出,做打字机效果
  • Memory ------ 内存版和文件版,会话上下文能持久化
  • Skill 插件 ------ 内置数据库 Skill、沙箱 Skill
  • 多模型路由 ------ 关键词路由 + LLM 分类路由,可以按任务分流到不同模型降本

多模型路由这块举个实际例子:你把数学题路由给便宜的 DeepSeek,代码题路由给 gpt-4o,闲聊路由给小模型。同一个 Agent,按内容自动分流,成本直接打下来。

java 复制代码
Agent routerAgent = AgentBuilder.create()
        .routing(RoutingModel.builder()
                .addStrategy(new KeywordStrategy(Map.of(
                        "数学", "deepseek-math",
                        "代码", "gpt-4o",
                        "default", "gpt-4o-mini"
                )))
                .build())
        .build();

五、um-ultra:毫秒级启动的轻量框架(差异化亮点)

这个模块是我花心思最多的。

为什么造它? 因为 Spring 太重了。

我在做边缘计算和一些 Serverless 场景时,被 Spring 的启动时间和内存占用折磨得够呛。一个只需要暴露三个接口的服务,Spring 要吃掉几百 MB 内存、启动好几秒。

um-ultra 的定位很明确:和 Spring 同一生态位,但零第三方框架依赖。

只带 snakeyaml(解析 YAML)和 asm(字节码增强)两个小包。启动毫秒级 ,内存数十 MB。

它对标 Spring 的核心能力:

能力 um-ultra Spring
IoC 容器 ✅ @Component @Inject ✅
AOP 拦截 ✅ MethodInterceptor ✅
配置注入 ✅ @Value 支持热刷新 ✅
Web 服务 ✅ Netty ✅ Servlet
事务 ✅ @Transactional ✅
多数据源 ✅ @DS ✅
事件总线 ✅ EventManager ✅

启动方式极简:

java 复制代码
public class DemoApp {
    public static void main(String[] args) {
        Ultra.run(DemoApp.class, args);
    }
}

就这一行,一个完整的应用就起来了。

再来看个完整的小服务:

java 复制代码
@Controller
@Mapping("/user")
public class UserController {

    @Inject
    private UserService userService;

    @GetMapping("/{id}")
    public Object detail(@RequestParam("id") Long id) {
        return userService.findById(id);
    }
}

@Component
public class UserService {

    @Inject
    private UserMapper mapper;

    @Transactional
    public Object findById(Long id) {
        return mapper.selectById(id);
    }
}

如果你写过 Spring,你会发现这个写法几乎没有学习成本。注解名字都是照抄 Spring 的,迁移过来基本是改 import 的事。

um-ultra 用 Plugin SPI 做扩展,生态模块按需装配:

模块 能力
um-ultra-web Netty HTTP + 路由 + CORS/CSRF/XSS 过滤器 + WebSocket
um-ultra-db 多数据源 + MyBatis-Plus + 声明式事务
um-ultra-cache 统一缓存,三种介质
um-ultra-nacos 注册发现 + 配置中心

六、um-ultra-cache:一个接口,三种介质

这是我最近新加的模块,解决一个老问题:缓存介质换了,代码也得换。

开发环境用内存,生产用 Redis,某些大对象场景想用 MongoDB......每种介质一套 API,切换就要改代码。

um-ultra-cache 把它统一成一个 UCache 接口:

java 复制代码
UCache cache = UCacheManager.create(
        UCacheProperties.ofRedis("redis://127.0.0.1:6379", "", 0));

// 未命中自动加载,天然防击穿
User user = cache.getOrLoad("user:" + id, User.class, k -> userService.load(id));

// 简单分布式锁语义
boolean locked = cache.putIfAbsent("lock:order:" + no, "1", Duration.ofSeconds(30));

// 需要底层能力时直接用 Redisson
RedissonClient client = cache.client(RedissonClient.class);

三个关键设计:

第一,getOrLoad 天然防击穿。 Redis 实现里用分布式锁,内存实现里用 Caffeine 原子操作。缓存击穿这个经典问题,接口层就给你挡住了。

第二,改配置切介质。 只改 YAML 一个字段:

yaml 复制代码
app:
  cache:
    type: memory        # 改成 redis / mongo 即可
    ttlSeconds: 1800
    maxSize: 10000

第三,client() 逃生通道。 这是我很坚持的一点------缓存抽象不能把底层封死。你需要 Redisson 的分布式集合、需要 Mongo 的聚合查询,直接拿原生客户端,不用绕过抽象层另起炉灶。

好的抽象不是把底层藏起来,而是让 80% 的场景变简单,同时给 20% 的场景留一扇门。


一张表看懂适用场景

场景 推荐度 怎么用
给现有项目加 AI / MCP 能力 ⭐⭐⭐⭐⭐ 引 um-mcp 或 um-agent,架构不动
需要统一工具 / 枚举基础库 ⭐⭐⭐⭐⭐ 引 um-util + um-enums,零框架污染
边缘设备、CLI、Serverless ⭐⭐⭐⭐⭐ 引 um-ultra,毫秒启动低内存
全新企业级微服务 ⭐⭐⭐ Spring Cloud 为主,um-sdk 作补充
强合规 / 依赖成熟社区支持 ⭐⭐ 建议等正式 Release + 文档完善

客观说说缺点

写到这里都是好处,我得诚实说说问题。

第一,版本还是 SNAPSHOT。 1.3.21-SNAPSHOT 是快照版,API 没有承诺完全稳定。生产环境引入请务必锁死具体版本,或者等正式 Release。

第二,依赖私有仓库。 构件发在 nexus.umnet.com.cn,外部团队使用需要仓库访问权限。这也是我把它开源到 Gitee 的原因------源码是看得见摸得着的,你完全可以自己 clone 下来本地构建。

bash 复制代码
git clone https://gitee.com/wizard-cn/um-sdk.git
cd um-sdk
./gradlew clean build -x test

第三,um-ultra 生态不及 Spring。 它只覆盖了 IoC/AOP/Web/DB/Cache/Nacos 这些核心。Spring 那套 Security、Batch、Cloud Gateway、Actuator 都没有对标实现。复杂企业级场景,我依然建议 Spring 为主。

第四,社区规模小。 这是我个人造的体系,遇到问题可查资料有限。好处是源码全在仓库里,坏处是踩坑主要靠读代码和自己琢磨。

第五,um-ultra 有学习曲线。 虽然注解照抄了 Spring,但 Plugin SPI 这套扩展机制、配置热更新这些设计,需要重新理解一遍。深度绑定 Spring 的团队,短期有迁移成本。

我宁愿把这些都写明白,也不想你引进来之后才发现。工具选型最怕的不是有缺点,而是没被告知缺点。


和同类对比

作品 优点 缺点 适用场景
um-sdk MCP/Agent 原生内置、零框架强依赖、轻量框架可选 SNAPSHOT、社区小、私有仓库 Java 项目需要 AI 能力或统一基础库
Hutool 工具类极全、生态成熟、社区大 无框架层、无 AI 能力 只要工具类
Spring Boot 生态最全、社区最大、企业标配 体积大、启动慢、依赖重 传统企业级微服务
LangChain4j Java 侧 LLM 编排能力强 需自行封装 MCP、较重 纯 AI 应用

um-sdk 的差异化在于:它把"业务基础能力"和"AI 调用能力"放在同一个包里,并给你一个能选 Spring 也能选轻量框架的出口。


写在最后

um-sdk 最开始只是我为了少写点重复代码造的私货。

后来我发现,AI 时代真正稀缺的不是模型,而是**"让模型能看懂、能调用的业务结构"**。

一个 @McpTool 注解,本质上是在给大模型写说明书------告诉它"这里有个能力,参数是什么,能解决什么问题"。

这件事做得越早,你的系统在 AI 时代的可复用性就越高。

一句话总结:um-sdk 是一个 Java 能力包,它把重复工作收进一个依赖,把 AI 调用变成一个注解。


关于我们

源码已经开源在 Gitee,Apache-2.0 协议,欢迎 star 和提 issue:

如果你也在为"业务代码怎么让 AI 调"这件事折腾,欢迎来找我聊聊。

希望这篇文章对您有所帮助!如果有任何问题,欢迎交流讨论。更多内容欢迎关注 小巫编程室 公众号。也希望您能点赞和转发支持,您的喜欢与支持是小编最大的鼓励,小巫编程室感谢您的关注与支持。🎉🎉🎉🚀🚀🚀


参考资料

相关推荐
小y的笔记15 分钟前
JavaScript URL 状态同步
前端·javascript
十有八七15 分钟前
手搓 Agent(五):学会翻书——RAG,先查资料再回答
前端·人工智能·后端
Swot29 分钟前
产品 RAG 知识库与 AI 顾问 设计与实现
前端·后端
深入云栈1 小时前
Netty 4.2.x 源码深度解析 (二十四):池化内存分配 —— PoolArena、PoolChunk 与 PoolSubpage
java·后端·架构
ServBay2 小时前
PHP 8.6 最新发布:语法更新、实用函数与升级要点
后端·php
惜.己2 小时前
Java结合idea简单使用Playwright
java·开发语言·自动化
我不会起名字3222 小时前
Agent 总调错工具?MCP 接进 Go 后端的 4 个约束
后端·go·agent·mcp
考虑考虑2 小时前
git刷新远程分支列表
git·后端·gitlab
htzyl2062 小时前
前端样式-弹窗淡入淡出,为什么你的 `transition` 一直不生效
前端·css·html