我造了一个 Java 能力包:让 AI 直接调用你的业务代码
一个注解,把你的业务方法变成大模型能用的工具。 本文源码已开源:gitee.com/wizard-cn/u…
大家好,我是小巫。
今天不聊概念,聊一个我自己造、自己天天在用的东西——um-sdk。
它解决的问题很朴素:Java 项目里那些反反复复要写一遍的东西,能不能只写一次?
工具类、枚举、支付、邮件、缓存……每个项目都要抄一遍。更麻烦的是,这两年大家都在接大模型、接 AI 助手,可业务代码怎么让 AI 调起来,又是一套全新的体力活。
于是我干脆把这些都收进了一个包,还顺手把 AI 那一层也焊了进去。
先说结论:它到底能干什么
一句话:一套依赖,干掉日常 Java 开发 80% 的重复造轮子工作,还能让 AI 直接调用你的业务方法。
比如你在写一个订单系统,想让 AI 助手能查订单。传统做法是你得啃 MCP 协议、拼 JSON-RPC、手写参数描述……折腾半天。
用 um-sdk,你只需要这样:
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 就能自己调你的方法了:
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 项目都能直接用。
五分钟上手:三行依赖跑起来
第一步:加仓库
<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>
第二步:引依赖
想只引一块能力,就引单模块:
implementation 'cn.com.umnet:um-util:1.3.21-SNAPSHOT'
想加 AI 能力:
implementation 'cn.com.umnet:um-mcp:1.3.21-SNAPSHOT'
implementation 'cn.com.umnet:um-agent:1.3.21-SNAPSHOT'
Spring Boot 项目全家桶:
implementation 'cn.com.umnet:um-spring-starter:1.3.21-SNAPSHOT'
第三步:写代码
先来个最简单的——工具类,静态调用,不需要任何容器:
// 安全执行:异常不炸业务,失败给默认值
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 把它压成一行:
// 传统写法
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 接口,你可以在运行时从数据库、配置中心拉取枚举项。业务方要加状态?往字典表加一行就行,不用发版。
// 按 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 | 声明提示模板 |
完整示例:
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 提供统一抽象,支持五家平台:
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 只需要改一行:
.platform(LlmPlatform.OPENAI, c -> c.apiKey(key).model("gpt-4o"))
它内置了几个我认为很实用的能力:
- 工具调用循环 —— 自动处理"模型要调工具 → 执行 → 结果回传模型"的循环
- 流式输出 —— 事件回调逐字输出,做打字机效果
- Memory —— 内存版和文件版,会话上下文能持久化
- Skill 插件 —— 内置数据库 Skill、沙箱 Skill
- 多模型路由 —— 关键词路由 + LLM 分类路由,可以按任务分流到不同模型降本
多模型路由这块举个实际例子:你把数学题路由给便宜的 DeepSeek,代码题路由给 gpt-4o,闲聊路由给小模型。同一个 Agent,按内容自动分流,成本直接打下来。
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 | ✅ |
启动方式极简:
public class DemoApp {
public static void main(String[] args) {
Ultra.run(DemoApp.class, args);
}
}
就这一行,一个完整的应用就起来了。
再来看个完整的小服务:
@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 接口:
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 一个字段:
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 下来本地构建。
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:
- 仓库:gitee.com/wizard-cn/u…
- 分支:
master - 协议:Apache-2.0
如果你也在为"业务代码怎么让 AI 调"这件事折腾,欢迎来找我聊聊。
希望这篇文章对您有所帮助!如果有任何问题,欢迎交流讨论。更多内容欢迎关注 小巫编程室 公众号。也希望您能点赞和转发支持,您的喜欢与支持是小编最大的鼓励,小巫编程室感谢您的关注与支持。🎉🎉🎉🚀🚀🚀
参考资料
- um-sdk 源码仓库 gitee.com/wizard-cn/u…
- MCP 协议官方规范 modelcontextprotocol.io
- MyBatis-Plus 文档 baomidou.com