Skip to content
BranchesTags

Repository files navigation

Vine Flow

Grow your business flows.

Vine Flow 是一个面向 JVM / Spring Boot 业务系统的多 DSL 通用流程编排引擎。

它的目标不是替代重型 BPMN 平台，而是为订单、支付、退款、风控、营销、履约等后端业务链路，提供一套轻量、可扩展、可观测、可治理的流程编排能力。

Vine 希望让复杂业务流程像藤蔓一样自然生长、分支、连接和收束，同时保持工程上的清晰、优雅和可维护。

目录

Vine 是什么

Vine 是一个面向 JVM / Spring Boot 业务系统的多 DSL 通用流程编排引擎。

它聚焦的是后端业务流程编排，而不是通用型、重量级、平台化的 BPMN 解决方案。对于订单、支付、退款、风控、营销、履约、审批、数据处理 Pipeline 这类“流程很强、业务很重”的场景，Vine 提供一种更贴近工程代码、更容易集成到现有 Spring Boot 系统中的做法。

Vine 的核心设计是：

  • 用多种 DSL 描述流程。
  • 所有 DSL 统一收敛到内部 FlowDefinition 模型。
  • 用统一 Runtime 执行流程。
  • 把业务节点实现和流程编排明确分层。

为什么需要 Vine

在真实业务系统里，很多核心逻辑并不是一个简单方法能表达清楚的。

以创建订单为例，流程里可能同时包含：

  • 校验商品、库存、规格、余额、配送地区。
  • 计算商品金额、优惠券、会员折扣、金币抵扣、运费。
  • 生成主订单、店铺订单、订单明细。
  • 锁定资源、保存订单、发布事件。

如果直接让开发者或 AI 一次性写完整流程代码，通常很容易出现这些问题：

  1. 流程代码变成一大段过程式面条代码。
  2. 业务步骤和编排逻辑混在一起。
  3. 过度封装，抽象层级失控。
  4. 异常兜底过多，真实失败原因被掩盖。
  5. 节点边界不清晰，后续难以测试和复用。
  6. AI 修改局部逻辑时容易破坏整体流程。

Vine 的思路是：把复杂流程拆成原子化节点，再用对 AI 和人类都友好的 DSL 进行编排。

这样流程结构是显式的，节点边界是清楚的，执行路径是可观察的，后续扩展和治理也更容易落地。

为什么 Vine 对 AI 编程友好

Vine 的一个重要设计目标，是让复杂业务流程更适合由 AI 辅助实现。

传统方式下，AI 往往会把“完整创建订单流程”直接写成一个巨大的 Service。而在 Vine 中，这个任务可以天然拆成两层：

  • 第一层：实现小而明确的原子节点。
  • 第二层：用 DSL 描述节点之间的连接、分支、并行、失败处理和结果汇聚。

这会显著降低 AI 生成复杂流程代码时的失控概率，也更利于人工 review、单测和渐进式演进。

详细说明见：Vine 与 AI 编程的关系

核心能力

  • 多 DSL 流程定义：Java Fluent API、YAML DSL、XML DSL。
  • 统一内部模型：所有定义方式最终都编译到 FlowDefinition。
  • 轻量运行时：统一执行引擎、上下文、注册表、表达式求值。
  • Spring Boot 原生集成：Starter 自动装配、Bean 调用、classpath 流程自动加载。
  • 可观测基础能力：FlowInstance、NodeExecutionRecord、日志监听器、Micrometer 监听器。
  • 并发编排基础能力：并行节点真实并发执行，支持基础错误聚合与部分成功策略。
  • 结构导出：支持 Mermaid 导出，便于可视化和文档化。

当前支持的定义方式与编排形式

定义方式

当前 Vine 已支持以下流程定义入口，按推荐阅读顺序排列：

  1. vine-java: Java Fluent API
  2. vine-yaml: YAML DSL
  3. vine-xml: XML DSL

它们都会被解析或构建成统一的 FlowDefinition，再交给 vine-runtime 执行。

当前已支持的编排形式

  • service：调用 Spring Bean 方法。
  • chain：按顺序执行多个 step。
  • parallel：并行执行多个 branch。
  • choice：按条件路由到不同分支。
  • throw：显式抛出业务错误。
  • transitions：用显式边描述节点流转关系。

当前已支持的运行与治理基础

  • FlowDefinition 统一流程模型。
  • FlowContext 统一上下文。
  • FlowRegistry 流程注册与查找。
  • FlowInstance 与 NodeExecutionRecord 执行记录。
  • 基于 SpEL 的表达式求值。
  • classpath*:vine/flows/**/*.yaml 与 classpath*:vine/flows/**/*.xml 自动加载。
  • Spring Boot Starter 自动装配。
  • Micrometer 指标监听器基础集成。

规划中的能力

  • switch / join / return / sub-flow / script 等更多节点类型。
  • 更完整的错误处理、补偿与事务治理能力。
  • 更完善的管理端、流程可视化与版本治理能力。

模块结构

  • vine-bom: 依赖版本管理。
  • vine-core: 核心模型、枚举、校验器、共享抽象，不依赖 Spring。
  • vine-runtime: 统一流程执行运行时。
  • vine-spring: Spring Bean 集成与运行时适配。
  • vine-spring-boot-starter: 自动装配与外部化配置。
  • vine-management: 管理与治理能力的承载模块。
  • vine-yaml: YAML DSL 解析器。
  • vine-xml: XML DSL 解析器。
  • vine-java: Java Fluent API。
  • vine-benchmark: 性能与回归基准模块。

快速开始

环境要求

  • Java 11
  • Maven 3.8+
  • Spring Boot 2.7.x

构建项目

cd /Users/wuu/Projects/indie-hacker/lighting-tech.io/Vine/source-code
mvn -q -DskipTests compile

如果你希望把当前版本安装到本地 Maven 仓库，便于在其他项目中引用：

mvn -q -DskipTests install

Spring Boot 配置示例

vine:
  enabled: true
  locations:
    - classpath*:vine/flows/**/*.yaml
    - classpath*:vine/flows/**/*.xml
  expression-engine: spel
  runtime:
    default-timeout: 5s
    executor:
      core-size: 8
      max-size: 32

示例

Java Fluent API

Java Fluent API 是当前最直接、最适合在 IDE 中逐步构建与调试流程的定义方式。

现在也支持直接用 Lambda 绑定 service / chain step 节点逻辑：

FlowDefinition flowDefinition = FlowBuilder.flow("lambda_demo")
        .service("loadUser")
            .handler(root -> {
                Object userId = ((java.util.Map<?, ?>) root.get("input")).get("userId");
                return "user-" + userId;
            })
            .output("$.output.result")
            .end()
        .build();

同一个 Lambda 实例在 Java Fluent 侧会复用缓存过的 handlerKey，运行时优先走直接 handler 调用，不再依赖 bean + method 反射。

FlowDefinition flowDefinition = FlowBuilder.flow("create_order")
        .name("创建订单流程")
        .version("1.0.0")
        .optionTimeout(5000)
        .service("loadUser")
            .name("加载用户信息")
            .bean("userService")
            .method("getUserById")
            .arg("userId", "${input.userId}")
            .output("$.context.user")
            .end()
        .parallel("validateOrder")
            .failFast(false)
            .waitAll(true)
            .partialSuccess(true)
            .branch("validateProduct")
                .bean("productValidator")
                .method("validate")
                .output("$.context.validation.product")
                .endBranch()
            .branch("validateStock")
                .bean("stockValidator")
                .method("validate")
                .output("$.context.validation.stock")
                .endBranch()
            .end()
        .choice("checkValidation")
            .mode("first")
            .when("${context.validation.product != null && context.validation.stock != null}")
                .to("buildOrder")
            .otherwise()
                .to("validationFailed")
            .end()
        .service("buildOrder")
            .bean("orderService")
            .method("build")
            .output("$.output.result")
            .end()
        .throwNode("validationFailed")
            .errorCode("ORDER_VALIDATE_FAILED")
            .message("创建订单校验失败")
            .end()
        .transitions()
            .from("loadUser").to("validateOrder")
            .from("validateOrder").to("checkValidation")
            .end()
        .build();

YAML DSL

flow:
  id: create_order
  name: 创建订单流程
  version: 1.0.0

  nodes:
    - id: load_user
      type: service
      bean: userService
      method: getUserById
      output: $.context.user

    - id: validate_order
      type: parallel
      branches:
        - id: validate_product
          type: service
          bean: productValidator
          method: validate
        - id: validate_stock
          type: service
          bean: stockValidator
          method: validate

    - id: build_order
      type: service
      bean: orderService
      method: build
      output: $.output.result

  transitions:
    - from: load_user
      to: validate_order
    - from: validate_order
      to: build_order

XML DSL

<flow id="create_order" name="创建订单流程" version="1.0.0">
    <service id="loadUser"
             bean="userService"
             method="getUserById"
             output="$.context.user"/>

    <parallel id="validateOrder" name="创建订单前置校验" failFast="false">
        <service id="validateProduct"
                 bean="productValidator"
                 method="validate"/>
        <service id="validateStock"
                 bean="stockValidator"
                 method="validate"/>
    </parallel>

    <service id="buildOrder"
             bean="orderService"
             method="build"
             output="$.output.result"/>

    <transitions>
        <transition from="loadUser" to="validateOrder"/>
        <transition from="validateOrder" to="buildOrder"/>
    </transitions>
</flow>

文档

当前仓库已经包含一版最小 AI 节点验证实现，DSL 重点是：

  • type: ai
  • instruction
  • output
  • expect（可选，当前支持 enum / json / regex）

当前 Starter 也已经支持多 provider AI 配置，内置 provider 类型包括：

  • openai
  • claude
  • deepseek
  • zhipu
  • minimax
  • grok
  • gemini
  • openai-compatible

示例配置：

vine:
  ai:
    enabled: true
    default-provider: openai
    providers:
      openai:
        type: openai
        api-key: ${OPENAI_API_KEY}
        base-url: https://api.openai.com
        default-model: gpt-4.1-mini
        available-models:
          - gpt-4.1-mini
          - gpt-4.1
      claude:
        type: claude
        api-key: ${ANTHROPIC_API_KEY}
        base-url: https://api.anthropic.com
        default-model: claude-3-5-sonnet-latest
        available-models:
          - claude-3-5-sonnet-latest
      deepseek:
        type: deepseek
        api-key: ${DEEPSEEK_API_KEY}
        base-url: https://api.deepseek.com
        default-model: deepseek-chat
        available-models:
          - deepseek-chat
      gemini:
        type: gemini
        api-key: ${GEMINI_API_KEY}
        base-url: https://generativelanguage.googleapis.com
        default-model: gemini-2.0-flash
        available-models:
          - gemini-2.0-flash

如果你需要理解 Vine 的整体设计背景、边界与建模方向，建议结合项目协调目录中的 docs/Vine技术方案.md 一起阅读。

项目状态

当前项目处于早期阶段，已经完成多模块初始化和第一批核心能力落地，适合继续推进：

  • 统一流程模型与运行时。
  • YAML / XML / Java Fluent API 三种定义入口。
  • Spring Boot Starter 自动装配。
  • 并行节点基础执行与执行记录。

现阶段仍有一些明确边界：

  • 并行分支错误聚合和部分成功策略仍是基础版。
  • 节点执行记录当前主要保存在运行时内存结构中。
  • 管理端与可视化治理能力仍在演进中。

Contributing

欢迎提交 Issue、设计讨论和 Pull Request。

提交改动时，建议优先关注这些原则：

  • 所有 DSL 都必须收敛到统一的 FlowDefinition。
  • vine-core 不引入 Spring 依赖。
  • Starter 保持轻薄，业务逻辑留在下层模块。
  • 新增流程能力时，优先先明确统一模型，再扩展 DSL 前端和 Runtime。

License

本项目采用 Apache License 2.0 开源协议。

Author

  • Author: JaveysWuu
  • Email: wujiawei0926@gmail.com

About

面向 JVM / Spring Boot 业务系统的多 DSL 通用流程编排引擎

Resources

Readme
Apache-2.0 license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages