# ttm

**Repository Path**: gzcltech/ttm

## Basic Information

- **Project Name**: ttm
- **Description**: 多线程事务
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-23
- **Last Updated**: 2026-06-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# TTM（Transactional Transaction Manager）

多线程、进程内分布式事务协调框架，语义对齐 [DTM](https://github.com/dtm-labs/dtm)，支持 **TCC**、**Saga**、**Msg**（二阶段消息），存储可选 **SQL** / **Redis**。

## 技术栈

- Java 25
- Spring Boot 4.0.6
- Spring Integration 7.0.4（Client ↔ Server 通信）
- Gson、JobRunr 8.6.0
- Maven 多模块

## 模块

| 模块 | 说明 |
|------|------|
| `parent` | 父 POM，统一依赖版本（Boot / SI / Gson / JobRunr 等） |
| `ttm-core` | 领域模型、Channel 常量、`SagaStep` 等 |
| `ttm-storage-api` / `ttm-storage-jdbc` / `ttm-storage-redis` | 协调器与屏障存储 |
| `ttm-barrier` | 分支幂等屏障 |
| `ttm-server` | 协调器（Msg/Saga/TCC Processor） |
| `ttm-client` | 客户端 API、注解 |
| `ttm-client-processor` | 编译期分支注册表 APT |
| `ttm-spring-boot-starter` | 自动配置，Server 与 Client 同 JVM 嵌入 |
| `ttm-examples-transfer` | 转账示例（TCC / Saga / Msg） |

## 快速开始

```bash
# 构建
mvn -Dspotless.check.skip=true verify

# 运行转账示例
mvn -pl ttm-examples-transfer -Dspotless.check.skip=true spring-boot:run
```

### Maven APT（分支注解）

应用模块需声明 `ttm-client-processor`，并启用父 POM 的 **`ttm-apt` Maven Profile**（示例模块默认已激活）：

```xml
<dependency>
  <groupId>io.gitee.gzcltech.ttm</groupId>
  <artifactId>ttm-client-processor</artifactId>
  <scope>provided</scope>
</dependency>
```

```xml
<!-- ttm-examples-transfer/pom.xml -->
<profiles>
  <profile>
    <id>ttm-apt</id>
    <activation><activeByDefault>true</activeByDefault></activation>
  </profile>
</profiles>
```

或命令行：`mvn -Pttm-apt compile`

`@EnableTtm` 启动后，`TtmHandlerRegistrar` 会自动加载 APT 生成的 `GeneratedTtmBranchRegistry`。

### 配置示例（`application.yml`）

```yaml
ttm:
  enabled: true
  store:
    type: sql          # 或 redis
    redis-url: redis://127.0.0.1:6379
    pool:              # Redis 时 Lettuce 连接池（ttm-storage-redis）
      max-total: 8
      max-idle: 8
      min-idle: 0
    skip-locked: true  # MySQL / PostgreSQL 恢复抢锁 FOR UPDATE SKIP LOCKED
  dispatch:
    receive-timeout: 30s
    direct: true          # 同 JVM 直调 Registry，绕过 SI（嵌入式推荐，默认开启）
  recovery:
    enabled: true      # 需 JobRunr background-job-server
    lease: 30s
    scan-batch: 32     # Redis LOCK_ONE 每轮扫描上限
  scheduler:
    poll-interval: 1s
    worker-threads: 8  # 每 tick 并行抢锁条数
  strict-options: false  # true 时损坏的 options JSON 启动/加载即失败
  client:              # 注入 TtmTemplate 的默认 TransOptions
    wait-result: true
    timeout-to-fail: 0
    request-timeout: 0 # 0 表示沿用 dispatch.receive-timeout
  branch-core-size: 4   # Saga 同层并发线程池 core
  branch-max-size: 16   # Saga 同层并发线程池 max

jobrunr:
  background-job-server:
    enabled: true
```

Starter 会在 `TtmAutoConfiguration` 中注册 `jobRunrJsonMapper`（`GsonJsonMapper`），JobRunr 任务序列化与 TTM 一致使用 Gson（覆盖 classpath 上 Jackson 的自动探测）。

`submit` / `submitSaga` / `abort` 经 Spring Integration **sendAndReceive** 同步返回 `CoordinatorResult`（`gid` + `status`）。`TtmTemplate.tcc/saga/msg` 同样返回该类型，可用 `requireSucceed()` 断言成功。

## 使用示例

```java
@EnableTtm
@SpringBootApplication
public class App { }

@TransCatalog(value = "TransferBranches", prefix = "transfer")
@Service
public class AccountService {

    @DefineTcc(name = "FREEZE")
    public void freeze(TransferReq req) { ... }

    public void confirmFreeze(TransferReq req) { ... }

    public void cancelFreeze(TransferReq req) { ... }
}

// APT 生成 TransferBranches.FREEZE
CoordinatorResult result = ttmTemplate.tcc(tx -> TransferBranches.FREEZE.call(tx, req));
result.requireSucceed();
```

Saga（推荐 `TtmTemplate.saga` + APT 常量）：

```java
ttmTemplate.saga(builder -> builder
    .add(TransferBranches.TRANS_OUT, req)
    .add(TransferBranches.TRANS_IN, req)
    .addBranchOrder("02", List.of("01"))
    .setConcurrent()
    .submit());
```

Saga 同层并行见 `TransferSagaService.transferConcurrent()`。

**并行层语义**：同层并行时，一个分支失败可能导致同层其它分支已 SUCCESS，协调器会对已完成 action 执行 compensate（非层内 2PC）。默认 `failFastOnBranchFailure` 会取消同层未完成任务；若要求「任一分支失败则同层不得执行」，请用串行 Saga 或 `addBranchOrder` 拆层。详见 [Saga 并行层语义](docs/saga-parallel-semantics.md)。

### TransOptions

| 字段 | 说明 |
|------|------|
| `waitResult` | 默认 `true`：submit 后同步跑完 Processor；`false` 则仅置 `submitted` 由 JobRunr 恢复 |
| `timeoutToFail` | 全局失败截止时间（毫秒） |
| `concurrent` | Saga 层内并行（也可 `SagaBuilder.setConcurrent()`） |
| `requestTimeout` | 单分支派发超时（毫秒），0 用 `ttm.dispatch.receive-timeout` |
| `failFastOnBranchFailure` | TCC/Msg 标全局 `failed`；Saga 并行层取消未完成任务（已成功 action 靠补偿，见 [文档](docs/saga-parallel-semantics.md)） |

全局默认可通过 `ttm.client.*` 配置；也可链式覆盖：

```java
ttmTemplate.options(new TransOptions(false, 0, false, 0, 0, Map.of(), null))
    .tcc(tx -> tx.callBranch(...));  // waitResult=false → 异步由 JobRunr 推进
```

TCC **Try** 与 Msg 本地业务走 `BranchBarrier`（需 `BarrierStore`），重复 Try 幂等跳过业务。

完整示例见 `ttm-examples-transfer`。

## 数据库 DDL

| 方言 | 脚本路径 |
|------|----------|
| MySQL | `ttm-storage-jdbc/src/main/resources/sql/mysql/schema.sql` |
| PostgreSQL | `ttm-storage-jdbc/src/main/resources/sql/postgresql/schema.sql` |

配置 Spring DataSource 指向对应库后，Starter 会根据 JDBC URL 自动选择方言（`jdbc:postgresql:` / `jdbc:postgres:`）。

```yaml
spring:
  datasource:
    url: jdbc:postgresql://127.0.0.1:5432/ttm
    driver-class-name: org.postgresql.Driver
    username: ttm
    password: ttm
```

## 初始化 JobRunr

JobRunr 的 `jobrunr_backgroundjobservers.firstHeartbeat` / `lastHeartbeat` 等字段类型为 **DATETIME(6)**，驱动层用 **UTC** 读写（见 JobRunr `Dialect#setTimestamp`）。请让 Spring DataSource 的 MySQL 连接使用 **UTC 会话**，与 [JobRunr 文档](https://www.jobrunr.io/en/documentation/installation/storage/) 一致，例如：

```yaml
spring:
  datasource:
    url: jdbc:mysql://127.0.0.1:3306/ttm?connectionTimeZone=UTC&forceConnectionTimeZoneToSession=true&...
```

若 URL 使用 `serverTimezone=Asia/Shanghai` 等非 UTC 时区，库里心跳时间会与本地墙钟相差约 8 小时，或引发超时误判。表中时间为 **UTC 墙上时钟**；在 SQL 客户端按东八区展示可用：

```sql
SELECT id,
       CONVERT_TZ(firstHeartbeat, '+00:00', '+08:00') AS firstHeartbeat_cst,
       CONVERT_TZ(lastHeartbeat, '+00:00', '+08:00') AS lastHeartbeat_cst
FROM jobrunr_backgroundjobservers;
```

```shell
# MySQL
java -cp jobrunr-8.6.0.jar org.jobrunr.storage.sql.common.DatabaseCreator \
  "jdbc:mysql://127.0.0.1:3306/ttm?connectionTimeZone=UTC&forceConnectionTimeZoneToSession=true&..." root password

# PostgreSQL
java -cp jobrunr-8.6.0.jar org.jobrunr.storage.sql.common.DatabaseCreator \
  "jdbc:postgresql://127.0.0.1:5432/ttm" ttm ttm
```

## 设计文档

- [分支派发：直调与 SI 共存](docs/dispatch-modes.md)
- [运维 API（人工介入）](docs/ops-api.md)
- [Saga 并行层语义](docs/saga-parallel-semantics.md)
- [设计规格](docs/superpowers/specs/2026-05-23-ttm-distributed-transaction-design.md)
- [实现计划](docs/superpowers/plans/2026-05-23-ttm-distributed-transaction.md)

## 作者

gzcltech