REA业务事件建模：用资源、事件、参与者解决对账难题

看到 rea 这个标题，估计不少人和我一样，第一反应是“少写了个 c 的 react”，或者“又是个 reactive 的缩写”。但在我最近折腾业务模型时，rea 代表的是 Resource-Event-Agent，也就是资源、事件、参与者三元组。这个不起眼的组合，确实治好了我一直头疼的问题：为什么订单、库存、财务经常对不上账？为什么加一个需求要改十几张表？如果你也在做后端开发、架构设计，或者正打算研究事件溯源和 DDD，这篇文章值得花十分钟看完。我不会讲太多虚的，直接用一套能跑通的事件建模思路把它拆开，顺便把建模过程中踩过的坑也一并列出来。

1. 内容整体设计与思路拆解

1.1 rea 到底在说什么

简单说，任何业务都可以描述成一句话：某个参与者（Agent）对某项资源（Resource）执行了某个经济事件（Economic Event）。

资源是业务里有价值的东西，比如物料、产品、钱、工时；事件是资源的流入或流出，比如“原材料出库”“成品入库”“客户付款”；参与者是人、部门、系统或者一个抽象角色，比如仓库管理员、生产订单、财务专员。举个例子：仓库管理员把一箱物料发给生产线，这就是一个事件，它让“库存物料”这个资源流出，而参与者是仓库管理员和生产线。

REA 最早来自会计信息系统领域，被设计用来替代借贷记账法。但放到今天的微服务和事件溯源场景里，它反而像一种天然的业务事件建模语言。注意，和传统表结构设计不同，REA 不要求先设计表和状态机，而是先写业务事件。订单、库存、支付这些模块都可以被统一表达成事件流。这样有个巨大的好处：业务变化时，通常意味着新增事件类型，而不是去修改历史事件和各类关联表。

1.2 传统表建模为什么容易翻车

传统建模方式是这样的：先建用户表、订单表、订单明细表，然后给订单加一个 status 字段，用状态机去描述业务流转。看起来合理吧？但需求一多就出问题。

首先是订单状态机越画越复杂。待支付、已支付、备货中、已发货、已完成、已取消、售后中……状态之间还有各种非法流转，每个流转都要写校验逻辑。其次是多个模块都在改同一张订单表，仓储要更新物流状态，财务要更新付款状态，客服要更新售后状态，最后这张表变成了所有人来踢的皮球。更麻烦的是口径不一致，仓库看的是“出库数量”，财务看的是“应收数量”，两边从同一张表里读字段，却算出不一样的结果。

本质原因是什么？表建模把“当前状态”当成了唯一真相，而状态只是事件累积的结果。rea 的思路反过来：状态是投影，事件才是真相。一旦数据对不上，不需要拿着 Excel 找人对账，直接回溯事件流，看看到底发生了什么。具体怎么操作，我放到后面案例里讲。

1.3 为什么做成轻量级核心，而不是一个大平台

我见过不少团队一上来就引入事件总线、消息队列、分布式事务，最后架构比业务还复杂。rea 的定位是一个“建模核心”，不是基础设施。它只负责三件事：定义事件、存储事件、通过投影还原状态。至于队列、异步通知、分布式最终一致，那是后面可以按需接入的能力，不是第一步就要上的重量级组件。

核心价值是理清业务，不是为了炫技。轻量级意味着学习成本低，可以在已有系统里挑一个模块试点，而不是推倒重来。所以下面代码里我不会堆一堆框架，尽量用纯 Java 的注解和接口来完成整套链路，方便你迁移到自己的项目里。

2. 核心细节解析与实操要点

2.1 Resource、Event、Agent 各自的职责边界

这三类对象最容易混淆，我先把每个人的职责边界讲清楚。

Resource 是资源，是系统中被管理和被追踪的对象。资源不一定是有形的库存，也可以是无形的额度、积分、协议份额。重要的是，资源需要有一个唯一标识，并且它的变化只能由事件触发。

Event 是经济事件，是资源流入或流出的记录。比如“物料出库”“成品入库”“客户支付”“退单冲正”。每个事件必须回答三个问题：什么时间发生、涉及哪些资源、参与者是谁。事件一旦写入，就不能修改，这是 so 重要的一条纪律。

Agent 是参与者，是动作的发出者或受益者。参与者可以是内部的人或部门，也可以是外部的客户、供应商、合作伙伴，甚至可以是另一个系统模块。实际建模时，我建议用 role 来标记参与者在事件中的角色，而不是直接绑某一个具体账号或者用户 ID。比如“仓库管理员向订单发货”，操作者是仓库管理员，受益者是订单，一个 Event 记录里可以有多个 Agent。

在 REA 中，事件之间还有两种关系常被提到：交换（duality）和转换（conversion）。交换是指两个事件配对产生业务闭环，比如“发货”和“收款”是一个交换，你付出资源也得到资源；转换是指一个或多个资源经过某个过程变成新资源，比如原材料经过“生产”变成产品。刚开始做建模时，不建议把交换和转换玩得太复杂，先让所有状态变化都有唯一对应的事件，关系以后可以慢慢补。

2.2 事件记录必须携带哪些字段

事件日志不是普通的应用日志，它是业务事实。事件结构设计得好不好，直接决定回溯能力和系统演进空间。我建议每个事件至少包含这些字段：

• eventId：全局唯一的事件 ID，建议用 UUID，不要用数据库自增主键。自增主键在分布式环境容易乱，而且不满足幂等要求。
• eventType：事件类型，比如 MaterialIssued、PaymentReceived。建议用稳定的枚举值，而不是随意写的字符串。
• occurredAt：业务发生时间，不是系统收到请求的时间。这两个时间一定要区分，跨日对账靠这个字段。
• agents：参与者集合，用 Map 存储，key 是角色，value 是参与者 ID。因为一个事件有多个参与者，不能只放一个 userId。
• changes：资源变更列表，每个变更至少包含 resourceId、delta。delta 是正负变化量，正值表示资源流入，负值表示资源流出。
• eventVersion：事件版本号。这个字段前面可能被忽略，但一旦你想升级事件结构，版本号是救命稻草。
• metadata：兜底字段，用来放业务追踪信息，比如请求 ID、操作终端、备注。不推荐把业务流程字段全塞进去，metadata 是冗余的补充，不是主数据。

你可能觉得这么多字段很重，但相信我，事件一旦上线，后面想加水印就难了。宁可先用一个宽一点的结构跑起来，也不要一开始就省得只剩 eventType 和 data，到时候回放数据的时候会非常痛苦。

2.3 命令、事件和投影是什么关系

很多人一开始学事件溯源都会被几个名词绕晕：命令、事件、投影、CQRS。我换个说法帮助理解。

命令（Command）是用户意图，表达的是“我想做什么”。比如“提交订单”“发货”“退款”。命令需要被校验，它关心的是能不能做，检查库存、检查权限、检查状态。

事件（Event）是已经发生的事实，表达的是“发生了什么”。它是命令校验通过后产生的结果，不可变。比如 MaterialIssued，事件里没有“成功”或“失败”的说法，写进去就等于发生了。

投影（Projection）是当前状态的视图，表达的是“现在长什么样”。比如库存快照、订单状态、对账报表。投影可以理解为把 EventStore 里的事件通过一个 reducer 函数累加出来的结果。

这三者的关键转变在于：写入路径和读取路径分离。命令写事件，投影读事件并更新状态。查询请求永远只走投影，不直接扫事件表。这样再加新需求时，通常只是加一个新事件类型和一个新投影方法，旧数据不需要迁移。

3. 实操过程与核心环节实现

3.1 工程结构怎么组织

我用一个纯 Java 的 Gradle 工程来演示，不依赖任何重量级框架，方便你把它移植到现有系统里。核心代码分成四块：

• annotation：定义 @Resource、@Agent、@EconomicEvent 注解。
• event：定义 EventRecord、ResourceChange 等公共结构。
• store：定义 EventStore 接口，并提供内存实现 DefaultEventStore。
• projection：定义投影接口和库存投影实现。

实际上，你不需要一上来就建这么多包。最简单的起步方式是一个 service 类 + 一个内存 List 都能跑通，但为了让思路更清晰，我建议保留这四个目录，因为后面扩展时会舒服很多。

3.2 核心注解与事件对象的代码落地

先定义几个注解，通过注解把领域语义标记在类上。这不是必需的，但能让代码里的业务含义更明显。

public @interface Resource { String name(); } public @interface Agent { String role(); } public @interface EconomicEvent { String type(); }

然后定义一个 ResourceChange，用来记录一次资源变化。

public record ResourceChange( String resourceId, long delta ) { public static ResourceChange inflow(String resourceId, long quantity) { return new ResourceChange(resourceId, quantity); } public static ResourceChange outflow(String resourceId, long quantity) { return new ResourceChange(resourceId, -quantity); } }

接下来是 EventRecord，这是整个 rea 建模里最核心的公共结构。

public record EventRecord( String eventId, String eventType, Instant occurredAt, Map<String, String> agents, List<ResourceChange> changes, long eventVersion, Map<String, String> metadata ) { public static EventRecord create( String eventType, Map<String, String> agents, List<ResourceChange> changes) { return new EventRecord( UUID.randomUUID().toString(), eventType, Instant.now(), agents, changes, 1L, Map.of() ); } }

注意，eventId 用 UUID.randomUUID()，这样每次生成的事件天然具备唯一性。agents 用 Map 是因为一个事件可能有多个参与者，例如发货事件里既有操作者，又有受益订单。

EventStore 接口保持简单，只提供两个方法：append 和 readAll。

public interface EventStore { void append(EventRecord event); List<EventRecord> readAll(String resourceId); }

内存实现也很直接：

public class DefaultEventStore implements EventStore { private final List<EventRecord> events = new ArrayList<>(); @Override public synchronized void append(EventRecord event) { events.add(event); } @Override public List<EventRecord> readAll(String resourceId) { return events.stream() .filter(e -> e.changes().stream() .anyMatch(c -> c.resourceId().equals(resourceId))) .toList(); } }

这里我加了 synchronized，防止并发 append 导致数据丢失。真实项目里你可能会换成数据库表，用唯一索引约束 eventId。事件表的核心字段就是 event_id、event_type、occurred_at、agents_json、changes_json、event_version、metadata_json。表结构可以简单，但唯一索引一定要加。

3.3 库存发料案例：从命令到事件到投影

业务场景是：仓库管理员向生产订单发 10 个物料。我用一个 InventoryService 来演示完整链路。

流程分三步：先构造命令并做业务校验，再把命令转成事件写入 EventStore，最后通过投影更新库存快照。

public class InventoryService { private final EventStore eventStore; private final InventoryProjector projector; public InventoryService(EventStore eventStore, InventoryProjector projector) { this.eventStore = eventStore; this.projector = projector; } public void issueMaterial(IssueMaterialCommand cmd) { long available = projector.getQuantity(cmd.materialId()); if (available < cmd.quantity()) { throw new IllegalStateException("库存不足，当前可用: " + available); } EventRecord event = EventRecord.create( "MaterialIssued", Map.of( "operator", cmd.operatorId(), "order", cmd.orderId() ), List.of(ResourceChange.outflow(cmd.materialId(), cmd.quantity())) ); eventStore.append(event); projector.project(event); } }

IsssueMaterialCommand 是一个普通 record：

public record IssueMaterialCommand( String operatorId, String orderId, String materialId, long quantity ) {}

这个例子看起来简单，但它包含了 rea 建模的所有关键点：

第一，命令和事件是分开的。命令是“想”做的事情，事件是“已经发生”的事实。有了这个区分，你才能在没有歧义的情况下对账和回溯。第二，校验和写事件之间不要插入状态修改。你可能会习惯先 update 库存表，再 append 事件，但这就违背了事件溯源的初衷。正确顺序是写事件，事件成功后再投影更新状态。如果事件写入失败，库存不应该变。第三，校验读取的是投影数据。投影数据可能比实时数据稍微滞后一点，但这是可接受的。在单机事务里，可以把 EventStore 和投影放在同一个事务里，保证一致性；在分布式环境，则要靠事件表作为可靠来源，异步投影。

3.4 投影怎么还原资源状态

投影是这个链路里最接地气的部分。InventoryProjector 只需要一个 ConcurrentHashMap 存快照，然后针对每个事件累加 delta。

public class InventoryProjector { private final Map<String, Long> snapshot = new ConcurrentHashMap<>(); public void project(EventRecord event) { for (ResourceChange change : event.changes()) { snapshot.merge(change.resourceId(), change.delta(), Long::sum); } } public long getQuantity(String resourceId) { return snapshot.getOrDefault(resourceId, 0L); } }

这里有一个特别重要的细节：投影必须幂等。如果同一个事件被投影两次，库存会被重复扣减或增加。我第一次实现时没考虑幂等，测试时手动重发了一条事件，结果库存直接翻倍，排查了好一会儿。后来我在投影表里加一个 processed_event_id 字段，每次投影前先查这个 ID 是否已经处理过。如果是，直接跳过。

如果要支持历史报表，还可以把事件按 occurredAt 排序，从某个快照开始分批重放。这就是事件溯源的灵活之处。你不用再设计一大堆“流水表”和“余额表”去对账，只需要保证事件全量和时序正确。

4. 常见问题与排查技巧实录

4.1 事件结构升级了，旧事件怎么处理

这是我踩得最深的一个坑。第一个版本的事件里只有 quantity，后来业务要求支持小数和单位，我图省事直接改了字段类型，结果一重放历史数据全部报错。正确做法是给事件加 eventVersion，每个事件一旦写入就永远不可变。新版本的事件用更高的 version，旧版本的事件交给升级器转换后再投影。

我通常这样设计升级器：

public class EventUpgradeRegistry { private final Map<String, Function<EventRecord, EventRecord>> upgraders = new HashMap<>(); public EventRecord upgrade(EventRecord event) { String key = event.eventType() + ":" + event.eventVersion(); Function<EventRecord, EventRecord> upgrader = upgraders.get(key); if (upgrader == null) { return event; } return upgrader.apply(event); } }

具体转换逻辑写在某个 lambda 里，按照旧版本事件结构读出数据，再转换成新结构，并返回 version + 1 的事件。这样历史数据始终保持可重放，新代码也只认最新版本。这个思路和接口版本升级是一样的逻辑：新版本向前兼容，旧版本不原地改。

4.2 库存快照和实际库存不一致，怎么排查

遇到这种问题不要急着“手动补数”，先对照事件流。做法很简单：把该资源在 EventStore 里的所有事件都读出来，把 delta 全部累加一遍，和当前投影值比对。如果不一致，无外乎三种原因：

• 漏写了事件：某次操作直接改了库存表，但没生成事件。
• 投影被重复执行：没有做幂等控制。
• 事件被直接修改：有人为了修数据直接 UPDATE 了事件表。

我的排查套路是：先在事件表外面套一层只读保护，禁止手改；再给事件表加 event_id 唯一索引；最后在每个投影方法里加 processed_event_id 记录。做完这三件事，一致性问题的面会小很多。如果还是对不上，就看事件表里某个资源的最早发生时间，从那个点开始一步一步重放，很快能定位到是哪条事件异常。

4.3 查询列表性能差，怎么优化

纯事件溯源在数据量小的时候很爽，但事件一多，每次取列表都要遍历几百上千条记录，查询体验就会崩塌。rea 的思路是 CQRS：查询全部走投影表，不直接扫事件表。

投影表不是把事件表复制一份，而是按查询需求生成一个专门的数据形态。比如订单列表，需要展示订单编号、客户名、状态、最新事件时间，那投影表就只存这几个字段。这样查询只需要走一次主键索引，不再是全表扫描。

当并发写入很高时，快照也会成为瓶颈。我建议做“分区快照”：每天生成一个截至当天结束的累计快照，重放时只从最近一个快照开始，而不是从头扫所有事件。这样历史事件保留完整，查询速度也不会随数据量线性下降。

4.4 常见问题排查速查表

我把实际操作中遇到的几个高频问题整理成了表格，方便你参考：

还有一个隐蔽的坑：不要用业务字符串直接拼接当 eventId。比如用 orderId + type 拼主键，一旦同一订单重复提交，容易冲突。更合理的做法是用 UUID，配合命令里的幂等键保证“同一个命令只能生成一个事件”。幂等键可以单独放在 metadata 里，并建唯一索引。

结尾

用 rea 这套思路折腾完几个内部模块之后，我感受最深的一点是：业务扯皮变少了。以前产品提一个需求，开发要讨论改哪些表、哪些状态机，现在大家先坐下来对齐“这个操作对应什么事件？资源是谁？参与者是谁？”想清楚这三件事，代码通常不会太乱。

如果你正准备在旧系统里做重构，我的建议是先挑订单或库存这种状态变化很明显的模块，只把变更接成事件，投影继续复用老表。跑顺之后，再把报表、审计、对账慢慢迁到事件流上。最开始写第一个事件时也别贪复杂，从“库存发料”这种单资源事件入手，比直接挑战“多资源兑换”要稳得多。

最后再分享一个小技巧：团队协作时，把 Resource / Agent / Event 整理成一张词汇表，我们内部叫它“事件字典”。新同事看代码之前先看事件字典，比看几十张表结构图有效得多。你可以从今天开始，挑一个模块，试着写下最近十个业务事件，感受一下视角切换后的变化。rea 这套模型后续还能扩展出事件订阅通知、实时风控、全链路对账，但第一步永远是：先把第一个事件写对。