109 lines
5.9 KiB
Go
109 lines
5.9 KiB
Go
// Package transaction 实现服务端更新请求的事务状态机与持久化层。
|
||
//
|
||
// 该包负责把一次单机更新请求建模为一个持久化的事务记录，并通过严格的
|
||
// 状态机约束其生命周期：从 CREATED 一路推进到 COMMITTED，或进入
|
||
// ROLLING_BACK/ROLLED_BACK/FAILED 等终态。事务的执行遵循“先记录意图、
|
||
// 再执行外部副作用、最后 inspect 核对”的协议，以保证进程崩溃后能够安全恢复。
|
||
//
|
||
// 包内数据统一存储在单个本地 SQLite 数据库中（见 store.go），Coordinator
|
||
// 负责在进程内串行化执行并驱动外部步骤，其余类型则定义了贯穿全局的数据模型、
|
||
// 状态、事件与错误约定。
|
||
package transaction
|
||
|
||
import (
|
||
"encoding/json"
|
||
"time"
|
||
)
|
||
|
||
// Transaction 一次更新请求的服务端持久化快照。
|
||
//
|
||
// 它同时承担幂等控制与状态推进两个职责：IdempotencyKey 唯一标识一次客户端
|
||
// 重试，Version 用于乐观锁防止并发覆盖，State 记录当前状态机位置。除终态外，
|
||
// 数据库中同时最多只允许存在一条未结束的事务（由单活动事务索引保证）。
|
||
type Transaction struct {
|
||
ID string // 事务唯一标识，为空时由存储层自动生成。
|
||
IdempotencyKey string // 幂等键，重复请求据此返回同一事务。
|
||
Source string // 请求来源，如 ymsctl 或守护进程。
|
||
Service string // 目标服务名，如 backend。
|
||
Request json.RawMessage // 原始请求载荷，仅作快照保存。
|
||
State State // 当前状态机状态。
|
||
Version int64 // 乐观锁版本号，每次状态变化自增。
|
||
CreatedAt time.Time // 事务首次创建时间（UTC）。
|
||
UpdatedAt time.Time // 最近一次变更时间（UTC）。
|
||
}
|
||
|
||
// ListFilter ymsctl list 命令查询历史记录时使用的过滤条件。
|
||
//
|
||
// 所有字段均按精确值匹配，服务端不会对过滤条件做任何推断或模糊处理。
|
||
type ListFilter struct {
|
||
Limit int // 最多返回的记录条数，必须在 1 到 1000 之间。
|
||
Service string // 按服务名精确过滤，为空表示不过滤。
|
||
State State // 按状态精确过滤，为空表示不过滤。
|
||
}
|
||
|
||
// CreateRequest 包含创建事务所需的不可变请求信息。
|
||
//
|
||
// 该结构体是 CreateTransaction 的入参，其中的 Request 必须是合法的 JSON，
|
||
// 否则创建会被拒绝；空请求会被规范化为空对象 {}。
|
||
type CreateRequest struct {
|
||
ID string // 事务唯一标识，允许留空由存储层生成。
|
||
IdempotencyKey string // 幂等键，必填且不能为空白。
|
||
Source string // 请求来源，必填且不能为空白。
|
||
Service string // 目标服务名，必填且不能为空白。
|
||
Request json.RawMessage // 原始请求载荷，必须是合法 JSON。
|
||
}
|
||
|
||
// StepStatus 外部步骤的持久化执行状态。
|
||
//
|
||
// 它描述了单个外部副作用在“记录意图 -> 执行 -> 核对”协议中所处的阶段，
|
||
// 只有 SUCCEEDED 与 FAILED 是最终状态，INTENT_RECORDED 表示仍需执行或核对。
|
||
type StepStatus string
|
||
|
||
const (
|
||
StepIntentRecorded StepStatus = "INTENT_RECORDED" // 已记录意图，尚未确定最终结果。
|
||
StepSucceeded StepStatus = "SUCCEEDED" // 外部副作用已确认成功发生。
|
||
StepFailed StepStatus = "FAILED" // 外部副作用已确认未成功发生。
|
||
)
|
||
|
||
// Step 记录一次外部副作用的意图和最终核对结果。
|
||
//
|
||
// 一条步骤在事务生命周期内由 step_key 唯一标识，意图（Intent）在副作用执行前
|
||
// 必须已经落库，结果（Result）则在 inspect 核对后写入，用于崩溃恢复时判断
|
||
// 副作用是否真实发生，从而避免重复执行或丢失执行。
|
||
type Step struct {
|
||
TransactionID string // 所属事务的 ID。
|
||
Key string // 步骤在事务内的唯一键。
|
||
Name string // 步骤的语义名称，用于日志与事件展示。
|
||
Status StepStatus // 步骤当前状态。
|
||
Intent json.RawMessage // 执行前持久化的意图载荷。
|
||
Result json.RawMessage // 核对后持久化的结果载荷，可为空。
|
||
Error string // 步骤失败时的错误信息，成功时为空字符串。
|
||
CreatedAt time.Time // 步骤意图首次记录时间（UTC）。
|
||
UpdatedAt time.Time // 步骤最近一次变更时间（UTC）。
|
||
}
|
||
|
||
// StepIntent 执行外部操作前必须先持久化的内容。
|
||
//
|
||
// 它描述了将要执行的外部副作用，只有先把它成功写入数据库，Coordinator 才会
|
||
// 真正调用 Operation.Apply，从而保证任何时刻都能回答“这一步是否已执行过”。
|
||
type StepIntent struct {
|
||
Key string // 步骤在事务内的唯一键，用于去重与恢复定位。
|
||
Name string // 步骤的语义名称。
|
||
Intent json.RawMessage // 执行该步骤所需的参数载荷。
|
||
}
|
||
|
||
// Event 供查询和 WSS 断联恢复使用的顺序事件。
|
||
//
|
||
// 每个事务状态变化或步骤意图/结果变化都会追加一条有序事件，Sequence 在事务
|
||
// 内单调递增。客户端据此实现断线后的增量拉取（EventsAfter），重放遗漏的事件。
|
||
type Event struct {
|
||
Sequence int64 // 全局递增的事件顺序号。
|
||
TransactionID string // 事件所属事务的 ID。
|
||
StepKey string // 关联的步骤键，事务级事件为空字符串。
|
||
Kind string // 事件类型，如 TRANSACTION_CREATED、STEP_SUCCEEDED。
|
||
FromState State // 变化前的状态，非状态类事件为空。
|
||
ToState State // 变化后的状态，非状态类事件为空。
|
||
Message string // 附加的人类可读信息。
|
||
CreatedAt time.Time // 事件产生时间（UTC）。
|
||
}
|