跳到正文

参考

Command

Command 接口与 Meta:命令类型、主聚合 id、租户与 Idempotency 字段、AuditOf 审计快照,以及 Validate 钩子。

Command

包:command

Command 表示「想改系统」的意图:有类型名、可选的主聚合 id,以及 Meta。命令从 CommandService.Execute 进入,先过中间件、AuthZ 和可选校验,再交给 Handler。

接口

type Command interface {
    CommandType() string
    AggregateID() (uuid.UUID, bool)
    Meta() *Meta
}
  • CommandType() 返回稳定名称,例如 bank.Deposit。路由和 AuthZ 白名单都靠它。
  • AggregateID() 返回主聚合 id,以及是否已设置;会随命令记录一起落库。
  • Meta() 返回命令元数据。

嵌入 command.Base 就能拿到 Meta():

type Deposit struct {
    command.Base
    AccountID uuid.UUID   `json:"account_id"`
    Amount    types.Money `json:"amount"`
}

func (c *Deposit) CommandType() string { return "bank.Deposit" }
func (c *Deposit) AggregateID() (uuid.UUID, bool) {
    return c.AccountID, c.AccountID != uuid.Nil
}

Base 把 Meta 存在字段 M 里。Base.Meta() 会调用 EnsureMeta,第一次用时补上默认值。

Meta

字段 用途
CommandID 命令唯一 id。用于审计,也是幂等记录外键的指向。
IdempotencyKey 可选。租户内 Idempotency 键(同一业务键重复提交只生效一次);需要同时有 TenantID。
TenantID 租户隔离单元,一般由多租户中间件从 context 抄过来。
UserID 发起命令的操作者。
CorrelationID 业务会话分组。
CausationID 指向引起本命令的命令或事件。
CausedByAggregate、CausedBySequence Workflow 触发命令时写入。
IssuedAt 命令发出时间。
Source 审计标签,如 api、workflow、admin。
AuthContext 不透明的鉴权声明,不一定持久化。

EnsureMeta(m) 的规则:CommandID 为空就生成新 UUID;IssuedAt 为空填当前 UTC;CorrelationID 为空则取 CommandID。

不要只信客户端传来的 UserID。认证归宿主应用;把已验证的声明放进 AuthContext,再交给 Authorizer 检查。

校验

实现 Validate() error,在 Handler 之前检查输入形状:

func (c *Deposit) Validate() error {
    if c.AccountID == uuid.Nil {
        return fmt.Errorf("account_id required")
    }
    if c.Amount.IsZero() || c.Amount.IsNegative() {
        return fmt.Errorf("amount must be positive")
    }
    return nil
}

CommandService 识别 command.Validator,在过滤器之后、分发之前调用。依赖聚合状态的规则写在聚合方法里,不要写在这里。

审计快照

command.AuditOf(cmd) 返回适合落库的 AuditSnapshot:

audit := command.AuditOf(cmd)
// audit.CommandID、CommandType、TenantID、UserID、
// IdempotencyKey、CorrelationID、CausationID、Source、IssuedAt

命令成功后,store 还会通过 command.RecordOf 写一条命令记录(commands 表),包含 id、类型、聚合 id、租户、用户、Idempotency 键、发出时间,以及 JSON 形式的命令载荷。

命令里的金额

金额字段一律用 types.Money。命令或事件里一旦出现 float64 金额,testkit.BanFloat64Money(cmd) 与 types.AssertNoFloatMoney(cmd) 都会报错——测试或启动时跑其中一个即可。见 Money。

一次执行多条命令

err := svc.Execute(ctx, cmd1, cmd2) // 一个事务、一个 UnitOfWork

命令按顺序执行。Workflow 可用 command.Enqueue 追加命令,它们在同一事务里排在已入队命令之后。见 Workflow。

相关

文档随 go-sequent 源码更新;若与 API 不一致,以源码为准。