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

0 阅读13分钟

我造了一个 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 RetryPolicyHTTP 调用、重试策略
实用SimpleJwtUtils QrcodeUtils TryUtils ProfilerUtilsJWT、二维码、安全执行、耗时分析
监控Jvm ServerJVM 与服务运行时指标

其中我私心最喜欢的是 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-ultraSpring
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-webNetty 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-sdkMCP/Agent 原生内置、零框架强依赖、轻量框架可选SNAPSHOT、社区小、私有仓库Java 项目需要 AI 能力或统一基础库
Hutool工具类极全、生态成熟、社区大无框架层、无 AI 能力只要工具类
Spring Boot生态最全、社区最大、企业标配体积大、启动慢、依赖重传统企业级微服务
LangChain4jJava 侧 LLM 编排能力强需自行封装 MCP、较重纯 AI 应用

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


写在最后

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

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

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

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

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


关于我们

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

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

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


参考资料