# camel-flow-server-starter **Repository Path**: BOBO_17/camel-flow-server-starter ## Basic Information - **Project Name**: camel-flow-server-starter - **Description**: 把一份 Flow JSON 编译成 Apache Camel 4 路由的 Spring Boot Starter。 - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-11-09 - **Last Updated**: 2026-11-13 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # flow-server-starter 把一份 **Flow JSON** 编译成 **Apache Camel 4** 路由的 Spring Boot Starter。 你只需要把描述流程的 JSON `POST` 到管理接口,服务端会完成解析、校验、编译、替换路由和持久化;已部署的流程在重启后自动恢复,把 `.json` 文件放进热部署目录也能立即生效。适合给低代码平台、内部集成平台或已有 JSON 流程设计器提供后端运行时。 - 管理接口与 REST 流程共用一个独立的 Jetty 端口(默认 `8086`),不占用宿主 `server.port`。 - 内置 75 个节点,全部通过 `@FlowNodeDef` 注解扫描注册,也能用配置追加自定义节点包。 - 部署失败时若存在上一版本会自动回滚;删除、覆盖部署都是幂等的。 ## 生态仓库 | 仓库 | 说明 | | --- | --- | | [flow-designer-web](https://gitee.com/BOBO_17/flow-designer-web) | React + antd 可视化设计器,读取 `/nodes` 元数据驱动表单,支持画布编排、校验定位、撤销重做与日志终端 | | [flow-host-sample](https://gitee.com/BOBO_17/flow-host-sample) | 只依赖本 starter 的最小宿主工程,用于验证空项目接入、多实例共库与全部节点回归 | 三个仓库的关系:`flow-designer-web` 产出 Flow JSON → `POST /flow` 交给 `flow-server-starter` 编译成 Camel 路由;`flow-host-sample` 是运行这些流程的宿主与回归环境。 ## 特性 - **节点即配置**:75 个内置节点覆盖入口、数据读写(含 Excel)、流程控制、调用、存储与消息;入口 15 个。 - **增强能力**:Excel 读写与报表模板导出(POI / EasyExcel 双引擎,多行模板块、表尾移动、合并单元格、公式偏移、类型化写入)、Redis / Redisson / ZooKeeper 分布式锁(自动续期)、跨实例幂等消费(Redis / JDBC 仓库自动装配)、路由级 DLQ 与 `onException`。 - **注解注册**:启动时扫描 `cn.seeyou520.flow.nodes` 与 `flow.node-packages` 下的 `@FlowNodeDef`,重复 `type` 启动即失败,扫描期不可加载的节点会被跳过。 - **完整表达式体系**:`constant` / `simple` / `groovy` / `header` / `exchangeProperty` / `method` / `jsonpath` / `xpath` / `spel`。 - **结构校验前置**:入口合法性、未知 `type`、必填 `props`、嵌套子链都在部署前检查,避免“能部署但一跑就报错”。 - **可回滚部署**:新路由编译失败时用内存中的上一版本重建;原始异常不会被掩盖。 - **持久化可选**:有 `DataSource` 时用 `JdbcTemplate` 读写 `T_FLOWS`,无 `DataSource` 时自动退化为内存模式。 - **启动恢复与文件热部署**:`ApplicationReadyEvent` 时从库恢复当前 `flow.server` 的流程;监听 `flow.git.tmpdir` 下的 `.json` 文件并即时部署(不落库)。 - **可选组件零侵入**:Kafka、RabbitMQ、Redis、MinIO、WebSocket、cron、JSONPath、XPath、FTP、邮件、MQTT、RocketMQ、S3、MongoDB、Elasticsearch 等组件按需引入,节点实现只拼接 URI,不在字段/父类/方法签名中引用可选类型。 - **可选日志终端**:开启后把运行时日志通过 WebSocket 推给前端设计器,支持 Logback 与 Log4j2 两种实现,默认关闭。 ## 技术栈 | 项 | 取值 | | --- | --- | | Maven 坐标 | `cn.seeyou520:flow-server-starter:1.0.0` | | JDK | 21 | | Spring Boot | 3.5.16 | | Apache Camel | 4.14.9 | | 管理接口 | Camel REST DSL + Jetty | | 持久化 | Spring `JdbcTemplate`(可选) | | 构建 | Maven,单模块 | ## 快速开始 ### 1. 引入依赖 ```xml cn.seeyou520 flow-server-starter 1.0.0 ``` > 如果制品尚未发布到中央仓库或私服,先在项目根目录执行 `mvn install` 安装到本地仓库。 Starter 已自带 `camel-spring-boot-starter`、`camel-jetty-starter`、`camel-jackson-starter`、`camel-groovy-starter` 等基础组件;Kafka、RabbitMQ、Redis、MinIO、Excel(POI / EasyExcel)、Redisson、Curator 等按需另行引入(见 [docs/NODES.md](docs/NODES.md#可选依赖坐标))。 > `camel-mock` 已在本 starter 中显式引入:`camel-spring-boot-starter` 传递的 `camel-dataset-starter` 会自动配置并引用 `MockComponent`,缺失时宿主启动即失败,因此不要把它排除掉。 > > 管理接口默认不开启 `/api-doc`。需要 OpenAPI 文档时,宿主额外引入 `camel-openapi-java-starter` 即可自动生效。 ### 2. 添加配置 ```yaml flow: enabled: true server: demo # 服务标识,参与 routeId,多实例部署时必须唯一 rest-port: 8086 # 管理接口与 REST 流程共用端口 admin-token: change-me # 留空则不校验管理接口 allow-script: true admin: # 管理接口 CORS,设计器通常跨端口访问 cors-origin: "*" # 允许的来源;多来源用逗号分隔。allow-credentials=true 时不能为 * cors-headers: "Content-Type,Authorization,X-Flow-Token" allow-credentials: false git: tmpdir: ./flow-drop # 放入 *.json 会自动部署;置空可关闭 terminal: # 可选日志终端,默认关闭 enabled: false backend: AUTO # AUTO / LOGBACK / LOG4J2 path: /terminal # 挂在宿主 server.port 上 queue-capacity: 1024 allowed-origins: "*" spring: datasource: # 可选;不配 DataSource 则流程只存在内存中。以下以 H2 为例,需自行引入驱动 url: jdbc:h2:mem:flow;DB_CLOSE_DELAY=-1;MODE=MySQL driver-class-name: org.h2.Driver username: sa password: "" sql: init: mode: always schema-locations: classpath:demo/schema.sql ``` 需要持久化时,在库中准备 `T_FLOWS` 表(可直接使用 [`src/main/resources/demo/schema.sql`](src/main/resources/demo/schema.sql)): ```sql CREATE TABLE IF NOT EXISTS T_FLOWS ( ROUTE_ID VARCHAR(255) NOT NULL PRIMARY KEY, FLOW_SERVER VARCHAR(255), FLOW_URI VARCHAR(512), FLOW_GROUP VARCHAR(255), FLOW_DESC VARCHAR(512), FLOW_JSON CLOB, CREATE_TIME TIMESTAMP DEFAULT CURRENT_TIMESTAMP, UPDATE_TIME TIMESTAMP DEFAULT CURRENT_TIMESTAMP ); ``` ### 3. 部署第一个流程 保存为 `hello.json`: ```json { "id": "demo-hello", "desc": "示例:GET /demo/hello/{name}", "group": "示例/问候", "schemaVersion": 1, "nodes": [ { "id": "n1", "type": "rest", "props": { "method": "GET", "path": "/demo/hello/{name}", "desc": "返回一句问候" } }, { "id": "n2", "type": "setHeader", "props": { "header": "Content-Type", "lang": "constant", "script": "text/plain; charset=UTF-8" } }, { "id": "n3", "type": "setBody", "props": { "lang": "simple", "script": "hello, ${header.name}" } } ] } ``` 部署: ```bash curl -s -X POST 'http://localhost:8086/flow' \ -H 'Content-Type: application/json' \ -H 'X-Flow-Token: change-me' \ --data-binary @hello.json ``` 返回: ```json {"errorCode":0,"msg":"部署完成","routeId":"demo_ZGVtby1oZWxsbw"} ``` `routeId` 由服务端生成:`flow.server + "_" + Base64Url(id 或入口 URI)`(无 padding),不接受外部传入。 ### 4. 验证 ```bash # 调用流程(REST 流程由 Jetty 在 flow.rest-port 上暴露) curl -s 'http://localhost:8086/demo/hello/bobo' # hello, bobo # 查看流程树 curl -s 'http://localhost:8086/flows' -H 'X-Flow-Token: change-me' # 只校验、不部署 curl -s -X POST 'http://localhost:8086/flow/validate' \ -H 'Content-Type: application/json' \ -H 'X-Flow-Token: change-me' \ --data-binary @hello.json ``` ### 运行自带 demo ```bash mvn -Pdemo spring-boot:run -Dspring-boot.run.profiles=demo ``` - `application-demo.yml` 位于 `src/main/resources/` 根目录,通过 `--spring.profiles.active=demo` 或 `-Dspring-boot.run.profiles=demo` 激活。 - demo 使用 H2 内存库;启动后由 `DemoApplication` 加载 `demo/flows/demo-hello.json`。 - demo 的 `server.port=8080` 只是 Spring Boot(Tomcat)端口;**REST 流程与管理接口都由 Jetty 在 8086 提供**,示例地址是 `http://localhost:8086/demo/hello/bobo`。 - 启动日志中应出现 `已注册节点 75 个:...`。 - demo 已开启日志终端,可连 `ws://localhost:8080/terminal` 观察实时日志。 ## 构建与测试 ```bash mvn install # 安装到本地仓库,供 flow-host-sample 等宿主引用 mvn test # 单元与集成测试,当前 77 项通过 ``` Redis 相关的 Testcontainers 用例在无 Docker 环境会自动跳过,不影响其余测试。测试覆盖解析与校验、节点注册、路由编译、部署回滚与持久化。 ## 三种流程来源 Java Builder 与界面配置最终都产出同一份 Flow JSON,共用节点注册、校验与编译;原生 Camel 路由独立存在,三种方式可以在同一个应用里共存。 | 方式 | 用法 | 说明 | | --- | --- | --- | | 原生 Camel | 宿主自己写 `RouteBuilder` | 不经过 Flow DSL,`/flows` 与设计器不可见,适合纯代码固定路由 | | Java Builder | `FlowBuilder` + `NodeBuilder`,声明为 Bean 后启动自动部署 | 不落库,代码即版本 | | 界面配置 | 设计器生成 JSON 后调 `POST /flow` | 落库;手写 JSON 与该方式等价 | ### Java Builder ```java @Bean FlowBuilder helloFlow() { return FlowBuilder.create("hello") .desc("示例流程") .group("示例/问候") .node(NodeBuilder.rest("GET", "/hello/{name}").prop("desc", "返回一句问候")) .node(NodeBuilder.setHeader("Content-Type", "constant", "text/plain; charset=UTF-8")) .node(NodeBuilder.setBody("simple", "hello, ${header.name}")); } ``` - `FlowBuilder` Bean 会在启动阶段(早于从数据库恢复)按 `@Order` 部署,且不写库;同 id 的库内流程随后会覆盖它。 - 容器节点用链式方法表达:`choice().when(...).otherwise(...)`、`filter(...)`、`split(...)`、`threads(...)`、`loopCount(...)`、`loopWhile(...)`、`tryNode(...).catchBlock(...).finallyBody(...)`。 - 也可以手动控制: ```java flowBuilder.deploy(deployService); // 部署并落库 flowBuilder.deploy(deployService, false); // 只更新内存与路由 flowBuilder.validate(deployService); // 只校验,返回 issues ``` ## 管理接口 管理接口监听 `flow.rest-port`(默认 `8086`)。配置了 `flow.admin-token` 时需要携带 `X-Flow-Token: ` 或 `Authorization: Bearer `;token 为空则不校验。 | 方法 | 路径 | 说明 | | --- | --- | --- | | `GET` | `/` | 引导信息(名称、版本、server、restPort、schemaVersion、allowScript、nodeCount、终端状态) | | `POST` | `/flow` | 解析、校验、部署并落库,返回 `routeId` | | `POST` | `/flow/validate` | 只做解析与结构校验,返回 `valid/errors/issues/routeId/uri` | | `GET` | `/flow/{routeId}` | 查看流程详情(`flow` 为 JSON 对象、`id/schemaVersion/uptimeMillis`) | | `GET` | `/flows` | 按 `group` 分级的流程树,叶子含 `routeId/id/desc/group/schemaVersion/uptimeMillis` | | `GET` | `/nodes` | 节点元数据(分类、必填、字段类型/枚举/默认值、容器类型) | | `GET` | `/subflows` | `from direct:` 入口的子流程列表 | | `DELETE` | `/flow/{routeId}` | 删除路由(同时删 `-impl`)并从库删除 | | `POST` | `/groovySyntaxCheck` | Groovy 语法检查,返回 `OK` 或错误文本 | 统一异常响应为 JSON:`{"errorCode":400|401|500,"msg":"..."}`。`IllegalArgumentException` 映射 400,鉴权失败 401,其余 500。`/groovySyntaxCheck` 成功时返回纯文本 `OK`。 `POST /flow/validate` 的 `issues` 为结构化问题列表,便于前端定位: ```json { "valid": false, "errors": ["nodes[1].props.lang 不支持的语言:foo"], "issues": [ {"path": "nodes[1].props.lang", "nodeId": "n2", "nodeType": "setBody", "field": "lang", "message": "不支持的语言:foo"} ] } ``` 校验同时覆盖:必填 props、节点类型注册、入口类型、重复 `nodeId`、表达式 `lang` 白名单、`script` 非空、`groovy` 语法,以及 `flow.allow-script=false` 时的脚本拒绝,保证 validate 与 deploy 结论一致。 `GET /nodes` 返回: ```json { "categories": [{"key": "entry", "title": "入口"}], "nodes": [{ "type": "setBody", "category": "data", "title": "设置消息体", "desc": "用表达式设置消息体", "entry": false, "order": 10, "container": null, "required": ["lang", "script"], "props": [ {"name": "lang", "label": "表达式语言", "type": "select", "required": true, "default": "simple", "options": [{"value": "simple", "label": "simple"}], "multiline": false}, {"name": "script", "label": "表达式内容", "type": "textarea", "required": true} ] }] } ``` ## 日志终端(可选) 默认关闭。宿主需要 `spring-boot-starter-websocket`(starter 已声明为 optional)和 Servlet Web 环境,然后开启: ```yaml flow: terminal: enabled: true backend: AUTO ``` 日志仍按宿主原有配置输出,同时额外推送到 `ws://:/terminal`,每行格式为 `[HH:mm:ss.SSS] [thread] LEVEL logger - message`。 ```js const ws = new WebSocket(`ws://${location.hostname}:8080/terminal`); ws.onmessage = (event) => console.log(event.data); ``` - `backend`:`AUTO` 优先 Logback,其次 Log4j2;显式指定但 classpath 中没有对应实现时只告警,不影响启动。 - 广播队列满时会丢弃新日志并限频告警,不会反压业务线程。 - 日志可能包含业务敏感数据,生产环境应关闭该功能,或在网关层对该路径做鉴权。 ## 目录结构 ```text flow-server-starter/ ├── pom.xml ├── README.md ├── docs/ │ ├── GUIDE.md # 架构、生命周期、配置、扩展节点 │ ├── DSL.md # Flow JSON 协议、表达式、嵌套容器、配方、排错 │ └── NODES.md # 75 个节点逐项清单与可选依赖 ├── src/main/java/cn/seeyou520/flow/ │ ├── FlowServerAutoConfiguration.java │ ├── config/FlowProperties.java │ ├── domain/{FlowDefinition,NodeSpec,FlowSummary}.java │ ├── protocol/{FlowParser,FlowValidator,ValidationResult,ExpressionFactory,PredicateFactory}.java │ ├── registry/{FlowNodeDef,FlowNode,FlowBuildContext,FlowNodeRegistry}.java │ ├── runtime/{RouteCompiler,DeployService,FlowRegistry,FlowStore,JdbcFlowStore,NoopFlowStore,FlowBootstrap,GroovyScriptProcessor}.java │ ├── web/{AdminRoutes,AdminAuthProcessor}.java │ ├── nodes/ │ │ ├── entry/ 15 个入口节点 │ │ ├── data/ 13 个数据读写节点(含 DataFormatFactory) │ │ ├── control/ 16 个流程控制节点 │ │ ├── call/ 9 个调用节点 │ │ ├── excel/ 3 个 Excel 读写节点(POI / EasyExcel 双引擎) │ │ ├── integration/ 19 个存储与消息节点 │ │ └── NodeSupport.java │ └── demo/DemoApplication.java ├── src/main/resources/ │ ├── META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports │ ├── application-demo.yml │ └── demo/ │ ├── schema.sql │ └── flows/demo-hello.json └── src/test/java/cn/seeyou520/flow/ ├── protocol/FlowValidatorTest.java ├── registry/{FlowNodeRegistryTest,NodeCatalogTest}.java ├── runtime/{RouteCompilerTest,DeployServiceTest,ErrorHandlerTest,ExcelNodeTest, │ ExcelTemplateNodeTest,IdempotentConsumerNodeTest,DistributedLockNodeTest}.java ├── nodes/NodeUriTest.java ├── dsl/FlowBuilderTest.java ├── idempotent/{JdbcIdempotentRepositoryTest,RedisIdempotentRepositoryTest}.java └── lock/{RedisDistributedLockTest,RedisIntegrationTest,RedissonDistributedLockTest,ZookeeperDistributedLockTest}.java ``` ## 扩展自定义节点 ### 第一步:写一个实现类 类必须实现 `FlowNode`、带 public 无参构造,并用 `@FlowNodeDef` 声明 `type`。下面的示例可以直接编译: ```java package com.example.flow.nodes; import cn.seeyou520.flow.domain.NodeSpec; import cn.seeyou520.flow.protocol.ExpressionFactory; import cn.seeyou520.flow.registry.FlowBuildContext; import cn.seeyou520.flow.registry.FlowNode; import cn.seeyou520.flow.registry.FlowNodeDef; import org.apache.camel.model.ProcessorDefinition; import java.util.List; @FlowNodeDef(value = "setCorrelationId", order = 200) @SuppressWarnings("rawtypes") public class SetCorrelationIdNode implements FlowNode { @Override public List requiredProps() { return List.of("header"); } @Override public ProcessorDefinition append(FlowBuildContext ctx, NodeSpec node, ProcessorDefinition current) { return current.setHeader(node.reqStr("header"), ExpressionFactory.expression("simple", "${exchangeId}")); } } ``` ### 第二步:声明扫描包 ```yaml flow: node-packages: - com.example.flow.nodes ``` ### 第三步:在流程里使用 ```json { "id": "custom-node-demo", "desc": "使用自定义节点", "group": "示例/扩展", "schemaVersion": 1, "nodes": [ {"id": "n1", "type": "from", "props": {"uri": "direct:custom"}}, {"id": "n2", "type": "setCorrelationId", "props": {"header": "X-Correlation-Id"}}, {"id": "n3", "type": "setBody", "props": {"lang": "simple", "script": "${header.X-Correlation-Id}"}} ] } ``` 启动日志会打印注册总数;用 `POST /flow` 部署后可从 `GET /flows` 看到。 自定义入口节点额外实现 `entryUri(NodeSpec)` 并在注解上写 `entry = true`;必填字段写在 `requiredProps()` 中,校验器会统一检查。详细规则见 [docs/GUIDE.md](docs/GUIDE.md#扩展自定义节点)。 ## 文档索引 - [架构、部署生命周期、配置、三种流程定义方式与扩展节点](docs/GUIDE.md) - [Flow JSON 协议、表达式、嵌套容器、常用配方与排错](docs/DSL.md) - [75 个节点完整清单与可选依赖坐标](docs/NODES.md) ## 来源与许可证 本项目派生自 tigerface 的 flow-server-starter 设计思想(https://github.com/tigerfacejs/flow-server-starter),上游未提供 LICENSE;本项目为独立重写,未复制上游源码,对上游的架构思路与节点体系致以感谢。 本项目采用 [Apache License 2.0](LICENSE) 开源,Copyright 2026 刘艳波。再分发时请保留 [NOTICE](NOTICE) 中的署名与来源信息。