【RuoYi-SpringBoot3-Pro】：AI 能力再扩展，一个方法打通 n8n 工作流

为什么要在 RuoYi-SpringBoot3-Pro 里集成 n8n？

n8n 是一个开源的工作流自动化平台，我在下面的文章中已经做了介绍，感兴趣的小伙伴可以看下，这里不做敖述。

• 【AI 工具箱】n8n：AI 工作流自动化平台
• 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 里可视化配置，改起来方便，调试也直观。

往期教程合集

RuoYi-SpringBoot3-Pro