一、Apex 中平台事件发布的故障排查
本模块要求进阶的 Apex 编程技能。本单元跟随零售商 Cloud Kicks 用平台事件处理订单，理解发布的中间结果与最终结果、检查立即错误，并了解 Apex 发布回调如何捕获异步错误。
学完本单元，你将能够：解释发布调用的两种结果、获取同步错误、在调试日志中记录并检查错误、解释 Apex 发布回调。
Cloud Kicks 订单处理、发布结果与立即错误
Cloud Kicks 是一家接收个性化运动鞋订单的零售商。开发者 Vijay Lahiri 负责写一个处理运动鞋订单的应用，为顾客下单发布平台事件。订单处理的第一步是发布一个平台事件（本模块示例用 Order Event 事件，含 Amount Number(16, 2) 和 Order Id Text(18) 必填字段），让订阅应用异步接收并处理订单，从而支撑高并发订单处理。
中间结果与最终结果：用 EventBus.publish 发布事件是异步的——事件入队到 Salesforce，稍后在系统资源可用时发布。发布调用执行后立即返回的是入队的中间结果；若有问题（如缺少必填字段），你会立即收到同步错误。中间结果在 Database.SaveResult 中返回：isSuccess() 为 true 表示发布请求已入队、事件将异步发布；为 false 表示发布出错，错误在 Database.Error 对象中。
检查立即错误：在 Developer Console 的 Execute Anonymous Window 里运行一段发布缺少 Order_Id 必填字段事件的代码，打开日志即可看到同步错误。
用 Apex 发布回调捕获异步错误
同步错误能直接拿到，但异步发布错误（由罕见的内系统错误导致）不会在发布调用结果中返回。Cloud Kicks 想保证高质量客户服务、不漏处理任何订单事件，于是用 Apex 发布回调来捕获异步发布错误。
没有回调时，EventBus.publish 的 Database.SaveResult 只返回中间入队结果，而非最终结果；有回调就能跟踪最终结果。做法是实现 EventBus.EventPublishFailureCallback 接口的 onFailure 方法：若异步发布失败，onFailure 被调用，参数是含各失败事件 EventUuid 字段值的 EventBus.FailureResult（用 getEventUuids 方法获取事件的 UUID，但不含事件数据）。也可实现 onSuccess 跟踪成功结果（多数发布都会成功，本模块不展开）。
注意：发布回调仅适用于 Apex；若不需要在平台上发布，可用 Pub/Sub API，其发布结果是最终结果。
二、用发布回调获取异步发布结果
本单元实现一个 Apex 发布回调类、用 EventUuid 关联事件与结果、用回调实例发布事件、测试回调类，并应用最佳实践。
学完本单元，你将能够：编写处理失败事件的回调类、用回调实例发布事件、为回调类写测试。
发布回调的实现、测试与最佳实践
Vijay 实现 EventBus.EventPublishFailureCallback 接口，在 onFailure 方法里获取发布失败的事件并重新发布，限制重试两次（若不在自定义代码里限制，系统默认用回调实例最多重发 10 次）。用一个 map 保存每个已发布事件的 UUID 到订单记录 ID 的映射，用来填充事件 Order_Id__c 字段。
创建带 EventUuid 的事件：发布前用 SObjectType.newSObject(recordTypeId, loadDefaults) 方法创建事件对象，让系统为每个事件生成唯一的 EventUuid 字段值，用于把回调返回的事件与发布调用中的事件对应起来。
用回调实例发布：创建两个事件后用 EventBus.publish(events, new FailureCallbackWithCorrelation()) 发布，并检查立即错误；异步错误会触发 onFailure。回调在 Automated Process 用户下运行，需为其添加 trace flag 收集调试日志。
测试回调类：在 Apex 测试中，Test.getEventBus().fail() 使事件发布立即失败、事件消息从测试事件总线移除，从而触发 onFailure；Test.getEventBus().deliver() 或 Test.stopTest() 则模拟成功投递、触发 onSuccess。测试可验证回调按预期重试两次（检查 retryCounter 变量）。
最佳实践：不要重新发布用 newSObject 创建的同一事件对象；用回调发布事件列表而非单个事件；列表用具体平台事件类型而非 SObject 泛型；让 map 保持小以减小回调实例大小、避免命中累计使用限额；谨慎用 onSuccess 跟踪成功发布（大事件量时会影响性能和限额）。
三、编写平台事件触发器的最佳实践
本单元学习如何让平台事件触发器健壮：用检查点在限额异常后恢复、用重试处理瞬时错误、使用触发器模板、编写能在意外失败后恢复的触发器。
学完本单元，你将能够：写出遇到限额异常能恢复、遇到瞬时错误能重试的触发器，并用触发器模板作为基础。
用检查点、重试与模板让触发器更健壮
平台事件触发器相比普通对象触发器的优势是异步在后台运行，可更高效地处理大事件量。
用检查点让触发器更健壮：Apex 限额异常（如 DML/SOQL 查询异常）无法用 try-catch 捕获，会失败并丢失当前批次。用 setResumeCheckpoint 方法在事件流中设置检查点，新调用从检查点之后恢复。触发器恢复时，新批次从 setResumeCheckpoint 设置的那个事件之后开始，事件按 ReplayId 原始顺序重发，且新调用中 Apex 限额被重置。
用重试处理瞬时错误：抛出 EventBus.RetryableException 可让触发器用整个事件批次重试，给瞬时错误一个处理机会。事件稍作延迟后重发，顺序不变。触发器最多可运行 10 次（首次 + 9 次重试），之后进入错误状态停止处理新事件。重试前触发器里做的 DML 操作会回滚。
使用触发器模板：模板结合检查点与可重试异常——调用 setResumeCheckpoint() 处理异常、用 try-catch 捕获非限额异常、必要时抛 EventBus.RetryableException。限额异常时在新调用中恢复（重置限额）；非限额异常时，若发生在处理第一个事件前（processedEventsCounter==0），捕获并抛 RetryableException 重试，若异常反复且重试耗尽则跳过第一个事件继续；若发生在已成功处理至少一个事件后，记录日志并重新抛出，靠之前设置的检查点启动新调用。
测试触发器恢复：在测试中用 Test.getEventBus().deliver() 按需多次投递事件批次，验证触发器在部分处理后能恢复；用 EventBusSubscriber.Position 验证已处理事件数。
四、调整平台事件触发器批大小
本单元学习如何配置平台事件触发器的批大小，以及如何为工作负载选择合适的值。
学完本单元，你将能够：列出大小批次的优缺点，并用 PlatformEventSubscriberConfig（Tooling API）配置批大小。
触发器批大小与用 Tooling API 设置
默认情况下，平台事件触发器每次调用最多投递 2,000 条事件消息，比普通对象触发器的 200 条大得多，让触发器能更快处理大量事件。副作用是若触发器做 DML/SOQL 操作，更可能命中 Apex 限额。
选择哪个批大小：批大小取决于事件发布速率。减小批大小可能减慢处理；事件量大时小批可能导致积压（事件在事件总线保留 72 小时）。不建议把批大小设得过小或等于 1。要综合考虑事件量与触发器处理速度——若触发器经常命中限额，减小批大小可帮助避免。
设置批大小：用 Tooling API 或 Metadata API 的 PlatformEventSubscriberConfig 覆盖默认值。先用 SOQL（SELECT Id FROM ApexTrigger WHERE Name='...'）拿到触发器 ID，再向 PlatformEventSubscriberConfig POST 配置（含触发器 ID 和 batchSize），得到 201 Created 即成功。触发器运行中时，需在平台事件详情页的 Subscriptions 相关列表里挂起再恢复触发器，新配置才生效。另外也可指定用户覆盖默认的 Automated Process 运行用户。
延伸学习与总结
恭喜完成平台事件调试模块！你现在知道如何用 SaveResult 检查立即错误、用 Apex 发布回调捕获异步失败、用 setResumeCheckpoint 与 EventBus.RetryableException 编写健壮的触发器，以及用 PlatformEventSubscriberConfig 调整批大小优化性能。
继续学习可参考：Platform Events Developer Guide、Apex Developer Guide（EventBus 类）、Tooling API 的 PlatformEventChannel，以及 Trailhead 的 Platform Events Basics 模块。掌握这些调试与优化技巧，你就能自信地构建生产级的事件驱动应用。