dbos-java

DBOS Java 最佳实践

使用 DBOS 持久化工作流构建可靠、容错的 Java 应用程序指南。

适用场景

以下情况请参考这些指南：

• 将 DBOS 添加到现有 Java 或 Kotlin 代码中
• 创建工作流和步骤
• 使用队列进行并发控制
• 实现工作流通信（事件、消息、流）
• 配置和启动 DBOS 应用程序，包括使用 Spring Boot
• 在外部应用程序中使用 DBOSClient
• 测试 DBOS 应用程序

按优先级划分的规则类别

优先级	类别	影响	前缀
1	生命周期	CRITICAL	lifecycle-
2	工作流	CRITICAL	workflow-
3	步骤	HIGH	step-
4	队列	HIGH	queue-
5	通信	MEDIUM	comm-
6	模式	MEDIUM	pattern-
7	测试	LOW-MEDIUM	test-
8	客户端	MEDIUM	client-
9	高级	LOW	advanced-

关键规则

安装

添加 DBOS 依赖（推荐使用 Java 17+、Gradle 8+）：

dependencies {
    implementation("dev.dbos:transact:1.2.0")
    implementation("org.slf4j:slf4j-simple:2.0.17") // to see DBOS log messages
}

DBOS 需要兼容 PostgreSQL 的数据库。连接设置通常通过 DBOS_SYSTEM_JDBC_URL、PGUSER 和 PGPASSWORD 提供。

DBOS 配置和启动

DBOS 应用程序必须创建一个 DBOS 实例，注册其工作流类，然后启动：

import dev.dbos.transact.DBOS;
import dev.dbos.transact.config.DBOSConfig;
import dev.dbos.transact.workflow.Workflow;

interface Example {
  String workflow(String input);
}

class ExampleImpl implements Example {
  private final DBOS dbos;

  ExampleImpl(DBOS dbos) {
    this.dbos = dbos;
  }

  @Override
  @Workflow
  public String workflow(String input) {
    return dbos.runStep(() -> fetchData(input), "fetchData");
  }

  private String fetchData(String input) { /* external call */ return input; }
}

public class App {
  public static void main(String[] args) {
    DBOSConfig config = DBOSConfig.defaultsFromEnv("my-app")
        .withAppVersion("0.1.0");
    DBOS dbos = new DBOS(config);

    Example proxy = dbos.registerProxy(Example.class, new ExampleImpl(dbos));

    dbos.launch();

    proxy.workflow("input"); // durable: called through the proxy
  }
}

创建新应用程序时，设置 withAppVersion("0.1.0")。如果省略，DBOS 会根据 工作流代码、SDK 版本和应用程序名称生成一个不透明哈希。编辑现有应用程序时，保留其已配置的版本 不变——更改版本属于部署决策（请参阅 references/advanced-versioning.md）。版本名称在共享系统数据库中必须唯一， 因此共享同一个数据库的应用程序需要使用不同的版本字符串（例如 "billing-0.1.0"；请参阅 references/advanced-shared-database.md）。

传递给 DBOSConfig.defaults(appName) / defaultsFromEnv(appName) 的名称用于标识应用程序，并归属其创建的 所有内容。多个应用程序（可使用任意语言）可以共享一个系统数据库，并通过应用程序名称实现隔离（1.1+，请参阅 references/advanced-shared-database.md）。

工作流和步骤结构

工作流是在通过 registerProxy 注册的类上使用 @Workflow 注解的普通方法。任何复杂、非确定性或会调用外部服务的操作 都必须作为步骤运行，可通过 dbos.runStep 执行，也可定义为带有 @Step 注解并通过代理调用的方法：

@Workflow
public String myWorkflow(String url) throws Exception {
  // Inline lambda step — use for one-off work
  String body = dbos.runStep(() -> httpGet(url), "httpGet");
  // Reusable step declared with @Step — MUST be invoked through the proxy (self)
  return self.parse(body);
}

@Step(maxAttempts = 3)
public String parse(String body) { /* ... */ }

关键限制

• 只有通过 registerProxy 返回的代理（或在 Spring Boot 中通过注入的自引用）调用工作流和 @Step 方法时，它们才具有持久性。通过 this 调用会绕过 DBOS。
• 必须在 launch() 之前注册所有工作流类；数据库支持的队列则在 launch() 之后注册
• 请勿在步骤中启动、加入队列或检索工作流，也不要在步骤中调用 send、recv、setEvent 或 getEvent
• 工作流必须具有确定性——随机数、当前时间、I/O 和线程操作都应放在步骤中
• 请勿从工作流或步骤中修改其自身作用域之外的状态
• 工作流参数以及步骤/工作流的返回值必须可由 Jackson 序列化为 JSON
• 在工作流中使用 dbos.sleep，而不是 Thread.sleep

使用方法

请阅读各个规则文件，了解详细说明和示例：

references/lifecycle-config.md
references/workflow-registration.md
references/queue-concurrency.md

参考资料

• https://docs.dbos.dev/
• https://github.com/dbos-inc/dbos-transact-java