该技能面向使用 spatie/laravel-event-sourcing 7.x 的 Laravel 项目,说明如何以事件溯源方式建模:聚合(aggregate)是模型的状态机,操作的合法性由当前状态决定,操作记录事件,事件推动状态变化;投影器(projector)把事件写入应用查询用的 Eloquent 读模型,反应器(reactor)处理其他副作用。技能只记录已确定的决策,未覆盖之处遵循项目自身约定。
规则要点:
- 聚合即状态机,位置由私有 backed enum $state 表示,初始为 Uninitialised;该状态仅用于写侧,创世事件的 apply() 设定第一个真实状态。
- 只有 apply{Event}() 能设置 $state,每个折叠以其事件为唯一类型参数,Spatie 按类型查找方法。
- 每个公开操作通过可重复的 #[OperationAllowedFrom] 声明合法起始状态,可传单个 case、列表或带键映射(所有键都需满足);重复属性可允许两种整体条件。
- 操作第一行直接调用 $this->ensure(),它从调用栈读取调用方法的属性,包装方法或闭包会导致读错方法,并在记录前抛出 IllegalTransition。
- 能力判断放在枚举上,如 OrderState 的 isTerminal()。
- 命令做决定、事件记录事实、apply() 只折叠状态;不要在 apply() 内做判断,否则重放会用今天的规则改写历史。
- 事件携带普通值,不携带模型或 DTO;事件继承 ShouldBeStored。默认序列化器可重建标量、CarbonImmutable 日期、只读载荷类及其列表(@var Line[]),backed enum 需把 Symfony 的 BackedEnumNormalizer 放入 event_normalizers 且位于 ObjectNormalizer 之前。
- 动作不做守卫:权限放在路由(->can()),合法性在聚合中;动作取聚合、调操作并持久化,例如 OrderAggregate::retrieve($order->uuid)->cancel($reason)->persist()。
- 投影器维护读模型,模型状态列转换为与聚合相同的枚举。
- 反应器承载副作用;Spatie 只重放投影器、不重放反应器,因此邮件或任务只在事件首次存储时执行一次。
- 聚合的 uuid 即模型公开 id,可与 laravel-models 的 HasUuid 共用。
- 事件溯源模型不使用 spatie/laravel-model-states;同一应用中普通模型仍可使用。
- 项目缺少 trait、属性和异常时,可复制 references/ProtectsInvariants.php、references/OperationAllowedFrom.php 与 references/IllegalTransition.php。
示例展示了 OrderState 枚举、OrderAggregate 的 place 与 cancel 操作及 applyOrderPlaced/applyOrderCancelled 折叠、OrderPlaced 与 OrderCancelled 事件、OrderProjector 写入和更新读模型的方式。反模式包括:在 apply{Event}() 之外设置 $state;在 apply() 中用 match/if 从事件数据推算状态;从 helper 或闭包调用 ensure();事件属性放模型、DTO 或 laravel-data 对象;在动作中对事件溯源模型做 guard() 或 canTransitionTo();在投影器或动作中产生副作用;投影器中使用 now()(应用 $event->createdAt());在事件溯源模型上使用 HasStates 或状态类转换。
适用场景为采用 Laravel 与 spatie/laravel-event-sourcing 的领域模型、订单等需要审计与重放的系统。限制与前提:需 Laravel 项目环境及该包 7.x;枚举重建需额外配置 Symfony 规范化器;未提供安装命令、具体版本兼容范围与收费信息。