# 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) 中的署名与来源信息。