【RuoYi-SpringBoot3-Pro】：AI 能力再扩展，一个方法打通 n8n 工作流
为什么要在 RuoYi-SpringBoot3-Pro 里集成 n8n？
n8n 是一个开源的工作流自动化平台，我在下面的文章中已经做了介绍，感兴趣的小伙伴可以看下，这里不做敖述。
RuoYi-SpringBoot3-Pro作为一个企业级的快速开发框架，本身已经接入 AI 对话能力 ,但是仅限于 AI 对话，无法实现复杂的 AI 功能，集成 Spring AI 又让框架显得太过笨重，所以这里通过引入 n8n 来实现 AI 能力的扩展。Java 端只负责触发，具体的 AI 功能全部在 n8n 里实现。
实现方案
1. RuoYi-SpringBoot3-Pro 添加处理方法
在 ruoyi-common 模块的 com.ruoyi.common.utils.ai 包下新增了一个 N8n 工具类，核心就一个 webhook 方法：
/**
* 通用 Webhook 调用接口
*
* @param baseUrl n8n 服务地址 (如: https://n8n.example.com)
* @param webhookId Webhook ID
* @param token 认证 Token (可选，如果配置了则添加到请求头 n-token)
* @param payload 请求体 (JSON 对象)
* @return 响应内容 (文本)
*/
public static String webhook(String baseUrl, String webhookId, String token, JSONObject payload) {
// 构建请求 URL
String url = baseUrl + "/webhook/" + webhookId;
// 构建请求
HttpRequest request = HttpRequest.post(url)
.header("Content-Type", "application/json")
.header("Accept", "application/json")
.body(JSONUtil.toJsonStr(payload));
// 如果配置了 token，添加到请求头
if (StrUtil.isNotBlank(token)) {
request.header("n-token", token);
}
// 发送请求
try (HttpResponse response = request.execute()) {
if (!response.isOk()) {
throw new RuntimeException("请求失败: " + response.getStatus() + " " + response.body());
}
return response.body();
}
}
请求接口：baseUrl 和 webhookId 分开传，是为了方便配置化管理。baseUrl 可以放在配置文件里，而 webhookId 则根据不同的业务场景使用不同的值。
Token 认证：n8n 的 Webhook 支持设置认证头，我这里用的是自定义的 n-token 请求头。你也可以根据自己的安全策略改成 Bearer Token 或者 Basic Auth。
payload 请求参数：与 n8n 工作流业务处理的参数一致。
返回值处理：直接返回响应体的文本内容。因为 n8n 工作流的输出可能是各种格式——纯文本、JSON、甚至 HTML，所以这里不做解析，交给调用方自己处理。
2. n8n 添加测试工作流
重点是使用 Webhook 触发器，配置参考：
3. 调用工作流
JSONObject jsonObject = new JSONObject();
jsonObject.put("markdown", "## 编写一篇以幼儿教育为主题的文章");
String body = N8n.webhook("http://n8n.test.com", "Webhook ID", "token", jsonObject);
4. 一些建议
- 生产环境一定要配置 Token：Webhook 暴露在公网上，没有认证的话谁都能调用
- 设置合理的超时时间：AI 类的工作流执行时间可能比较长，注意调整 HTTP 客户端的超时配置
- 做好异常处理：网络问题、n8n 服务不可用等情况都要考虑到
- 日志记录：关键的 Webhook 调用建议记录请求和响应日志，方便排查问题
进阶：支持文件上传
有些场景下，我们需要把文件传给 n8n 进行处理（比如 OCR 识别、图片处理、文档分析等）。为此，工具类中也扩展了支持文件上传的方法 webhookWithFile：
/**
* 带文件上传的 Webhook 调用接口
*/
public static String webhookWithFile(String baseUrl, String webhookId, String token, JSONObject payload, java.io.File file) {
// 内部封装为 Attachment 列表调用通用接口
return webhook(baseUrl, webhookId, token, payload, java.util.Collections.singletonList(new Attachment("file", file, file.getName())));
}
使用示例：
// 准备参数
JSONObject payload = new JSONObject();
File file = new File("/tmp/invoice.png");
// 调用 n8n
String result = N8n.webhookWithFile("http://n8n.test.com", "Webhook ID", "token",, payload, file);
总结
这次新增的 n8n 集成功能，本质上是把复杂的 AI 编排逻辑从 Java 代码里抽离出来，交给更适合做这件事的工具。Java 端保持简洁，只负责触发和接收结果；复杂的工作流在 n8n 里可视化配置，改起来方便，调试也直观。
