Mastering Liteflow: Core Concepts and a Real‑World Spring Boot Demo

Workflow (Workflow) breaks a business process into ordered task nodes executed automatically, defining who does what under which conditions. Example: leave request flow employee → leader approval → HR record → end.

Reasons to use workflow: visualized and standardized processes; clear responsibilities; support for complex branches and conditions (e.g., amount > 10k requires senior approval); process changes without code changes; monitoring and audit logs.

Liteflow is a lightweight Java workflow engine that does not follow standard BPMN. It uses a custom DSL defined in configuration files (YAML or XML) and supports all Java versions including JDK 17 and Spring Boot 3. Advantages: ultra‑lightweight, fast startup, easy learning, suitable for business orchestration such as order processing, after‑sale, and risk control.

Core concepts of Liteflow:

Component (Node) : the smallest execution unit, written in Java. Types include ordinary, switch, loop, and condition components; each has a unique nodeId.

Chain : a sequence of nodes combined by DSL to represent a complete business flow.

EL syntax : the primary expression language used by Liteflow, enabling readable and concise orchestration.

Key DSL keywords (with examples):

THEN(node1, node2, node3)               // sequential execution
WHEN(node1, node2)                       // parallel execution, all must finish
IF(conditionNode, trueNode, falseNode)   // conditional branching
SWITCH(choiceNode).CASE("1", THEN(...)).DEFAULT(fallback) // multi‑branch selection
FOR(times, flow)                         // fixed‑count loop
WHILE(conditionNode, flow)               // repeat while condition is true
FORIN(collection, flow)                 // iterate over a list
PRE(startLog)                            // executed before the chain
FINALLY(endLog)                          // always executed after the chain
EXCEPTION(errorNode)                     // error handling node
IGNORE_ERROR(node)                      // skip node on error
MUST(node)                               // node must complete in parallel block

Configuration examples:

YAML (EL source):

liteflow:
  rule-source: el
  rules: |
    chainName: order_chain
    PRE(start_log)
    THEN(order, stock, IF(is_vip, discount_pay, normal_pay), send_msg)
    FINALLY(end_log)
    .EXCEPTION(error_notify)

XML format:

<flow>
  <chain name="order_chain">
    <pre>start_log</pre>
    <then>
      <node id="order"/>
      <node id="stock"/>
      <if test="is_vip">
        <then><node id="discount_pay"/></then>
        <else><node id="normal_pay"/></else>
      </if>
      <node id="send_msg"/>
    </then>
    <finally>end_log</finally>
    <exception>error_notify</exception>
  </chain>
</flow>

Practical tips gathered from experience:

Component IDs must exactly match the @Component name (case‑sensitive).

The first argument of IF must be a boolean component.

WHEN runs in multiple threads; avoid non‑thread‑safe variables inside parallel nodes.

EL statements should not contain stray semicolons; use the pipe (|) in YAML to preserve line breaks.

Liteflow only orchestrates execution order; business logic stays inside Java components.

Typical scenarios for Liteflow include business step flows, multi‑branch routing, and frequently changing rules, especially when traditional approval features (roles, tasks, delegation) are unnecessary.

Project demo (Spring Boot 3.2 + Java 17):

Project structure includes a Maven pom.xml with dependencies on spring-boot-starter-web, liteflow-spring-boot-starter (version 2.13.2), and Lombok.

<project ...>
  <parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.2.12</version>
  </parent>
  <properties>
    <java.version>17</java.version>
    <liteflow.version>2.13.2</liteflow.version>
  </properties>
  <dependencies>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
      <groupId>com.yomahub</groupId>
      <artifactId>liteflow-spring-boot-starter</artifactId>
      <version>${liteflow.version}</version>
    </dependency>
    <dependency>
      <groupId>org.projectlombok</groupId>
      <artifactId>lombok</artifactId>
      <scope>provided</scope>
    </dependency>
  </dependencies>
</project>

Data classes such as DemoContext hold workflow variables (name, age, loop counters, step list). Components are annotated with @LiteflowComponent and define methods using @LiteflowMethod (e.g., calculateAge, aLiteFlow, bLiteFlow, cLiteFlow).

@Data
public class DemoContext implements Serializable {
    private String name;
    private Integer age;
    private int loopTarget;
    private int loopIndex = 0;
    private List<String> steps = new ArrayList<>();
    public void addStep(String step) { steps.add(step); }
}

The flow definition ( flow.el.xml) composes the chain:

<flow>
  <chain name="demoChain">
    customizedTypeData = '{"customizedType":"longxia_biancheng"}';
    THEN(
      PAR(calculateAge),
      ALiteFlow,
      BLiteFlow.bind("customizedTypeData",customizedTypeData),
      CLiteFlow
    );
  </chain>
</flow>

Application properties point Liteflow to the EL file and enable execution logging:

server:
  port: 8080
spring:
  application:
    name: liteflow-demo
liteflow:
  rule-source: flow.el.xml
  print-execution: true

A configuration class logs the loaded chains at startup, and a service class executes the chain, captures the LiteflowResponse, and returns a custom DemoResponse containing success flag, message, execution steps, and elapsed time.

The REST controller exposes GET /api/demo/run which returns the result wrapped in a generic Result object.

Running the application and invoking the endpoint produces console output showing each node execution and a JSON response with the step trace, confirming that Liteflow works correctly in a Spring Boot 3.2 + Java 17 environment.

Images illustrate the architecture diagram, project structure, console logs, and successful HTTP response.