03 · 事务性发件箱(Transactional Outbox):完整教程
目标:用 RAP + bgPF 实现 Transactional Outbox,理解“先落库、再异步投递”的生产级做法。 预计:2–3 小时 | 难度:中 | 前置课程:S4D426、S4D401(Application Job 部分)
关于图片:本案例官方仓库只有 README 与 ABAP 源码,没有附带步骤截图,assets/ 下也没有对应图片资产。因此本篇不插入任何图片——既不伪造本地截图,也不引用远程图片——改用界面示意(ASCII)、对象地图、完整源码和验收清单把每一步讲到可离线照做。文中的“界面示意图”是根据操作逻辑画的结构示意,不是截图,实际界面以你的系统为准。
你会做出什么
一个「订单 → 发货请求」的小型 RAP 应用:
用户在 Fiori 预览里新建并保存一张订单(草稿激活);
订单提交成功之后,系统通过后台处理框架(bgPF)异步生成一条“发货请求”,模拟向外部系统(发货/物流平台)下单;
外部投递失败时,订单照样保存成功,事件不会丢,可以观察失败状态并重试;
修复/恢复后,事件最终一致地投递成功。
最终效果清单
# |
你会看到什么 |
说明 |
|---|---|---|
1 |
订单预览能新建、保存订单 |
列表页出现一条非草稿状态的订单 |
2 |
保存后几秒内,发货请求预览多出一条记录 |
|
3 |
发货请求的 |
投递类里写死的业务值 |
4 |
发货请求的 |
由 determination 计算 |
5 |
注入失败后保存订单:订单在、发货请求不在 |
外部失败不影响业务落库 |
6 |
后台进程单元停在错误状态,可重启 |
事件没丢、可重试 |
7 |
修复后重启/重新触发,发货请求最终出现 |
最终一致性 |
你不需要自建“发件箱表”。在 ABAP Cloud 里,bgPF 的队列本身就是发件箱:它把“待执行的业务操作”和订单数据在同一个数据库事务里持久化,提交之后再由后台任务执行。这是本案例最值得带走的认知。
架构与原理
1. 要解决的问题:一次数据库提交 + 一次外部调用,无法原子化
订单落库是本地数据库事务,可以 COMMIT / ROLLBACK;调用外部系统是网络请求,无法参与本地事务。二者组合时,任何“先后顺序”都有漏洞:
做法 |
正常时 |
外部系统故障 |
进程在两步之间崩溃 |
结论 |
|---|---|---|---|---|
先调外部,再提交数据库 |
看起来都对 |
外部已受理,本地回滚 → 外部多了一单 |
外部已受理,本地未提交 → 数据不一致 |
不可用 |
先提交数据库,再调外部 |
看起来都对 |
订单已提交,事件丢失 |
提交后崩溃 → 事件永久丢失 |
会丢事件 |
把外部调用塞进业务事务里 |
看起来都对 |
外部失败导致业务事务回滚 |
长事务、锁等待,不可接受 |
业务被拖垮 |
事务性发件箱(本案例) |
正常 |
事件保留、可重试 |
提交即意味着事件已持久化 |
生产级 |
根本矛盾在于:“写数据库”和“调外部接口”是两个不同资源,没有共同的事务管理器。跨组织、跨公网的分布式事务基本不可行,所以业界统一退一步,用“本地事务 + 可靠异步投递”来逼近一致性。
2. 发件箱模式的三条规则
同事务落库:业务数据(订单)和“待发送事件/待执行操作”必须在同一个数据库事务里写入。要么都成功,要么都失败,不存在“订单有了但事件没有”。
独立投递:提交之后,由独立的后台机制读取发件箱、执行外部调用,与用户请求/业务事务解耦。
至少一次 + 幂等:投递失败可重试,因此会出现重复投递(at-least-once);消费端(外部系统或本地后续处理)必须按业务键做幂等,才能达到“效果上恰好一次”。
┌──────────────── 同一个数据库事务(LUW)────────────────┐
用户保存 │ ① 写业务表 zorder │
订单 │ ② 写发件箱(bgPF 队列条目) │
└───────────────────────────┬──────────────────────────┘
│ COMMIT WORK
▼
┌──────────────────────┐
│ bgPF 后台工作进程 │ 独立会话,与用户请求无关
└──────────┬───────────┘
│ 读取队列条目
▼
┌──────────────────────┐
│ 执行投递(外部调用) │
└───┬──────────────┬───┘
成功 │ │ 失败
▼ ▼
标记完成/成功 单元标记错误、保留在队列
│ 监控 / 重启(重试)
▼
直到成功或人工介入
3. ABAP Cloud 里,bgPF 就是内置的发件箱
bgPF(background processing framework,后台处理框架) 是 ABAP Cloud 提供的后台处理基础设施,用来把“当前会话里登记的任务”延迟到提交之后在后台执行。它对外暴露一套很小的 API,常见调用骨架如下:
" ① 创建进程(进程 = 一次后台执行的容器)
DATA(lo_process) = cl_bgmc_process_factory=>get_default( )->create( ).
" ② 给进程起名(监控里能看到)
lo_process->set_name( 'Request shipping' ).
" ③ 挂上要执行的操作对象(实现 if_bgmc_op_single 接口的类实例)
lo_process->set_operation( zcl_rap_bgpf_request_shipping=>create_instance( is_order = ls_order ) ).
" ④ 持久化到队列(此时还没有执行,也不会执行)
lo_process->save_for_execution( ).
" 之后由业务事务的 COMMIT WORK 触发执行
它提供两种操作接口,对应两种执行模型:
接口 |
变体 |
适用场景 |
关键约束 |
|---|---|---|---|
|
受控(controlled) |
RAP 场景,本案例使用 |
框架会走 RAP 的事务阶段;方法里不能 |
|
非受控(uncontrolled) |
非 RAP 的普通后台处理 |
自己负责 |
bgPF 的生命周期有三个关键不变量,正是发件箱语义的来源:
save_for_execution( )只登记、不执行:它把操作对象(含构造时传入的订单数据)序列化进 bgPF 队列,属于当前数据库事务的一部分。只有
COMMIT WORK之后才可能执行:事务提交,队列条目才被调度;事务回滚(ROLLBACK WORK),条目随之消失,后台任务根本不会启动。执行在独立的后台单元里完成:用户会话已经结束也无妨;失败时单元保留错误状态,可以监控、可以重启(重试)。
因此,“在 RAP 保存序列里调用 save_for_execution( )”天然满足发件箱规则 1 和 2。规则 3(幂等)需要你自己设计,示例没有做。源码是怎么落到这些机制上的,在步骤 4 逐段读。
监控提示:bgPF 的底层单元基于 bgRFC(队列化 RFC),失败单元通常要在后台处理/bgRFC 监控里查看和重启。云环境的入口是 Fiori 应用(后台处理、Application Jobs/bgRFC 监控类应用),本地 S/4HANA 2023+ 常见入口是 bgRFC 监控器;具体名称与权限随版本和角色而异,以你系统实际为准。拿不到监控权限也不影响:用“订单是否保存 + 发货请求是否生成”这一对现象就能完成全部验证。
准备工作
1. 系统环境
要求 |
说明 |
|---|---|
ABAP Cloud 开发系统 |
优先使用 SAP BTP ABAP Environment;或 S/4HANA Cloud Public Edition 的 developer extensibility 系统。仓库代码面向 ABAP Cloud |
本地 S/4HANA(可选) |
bgPF 自 S/4HANA 2023 起随本地版本交付,但需要管理员先完成配置; |
允许访问 GitHub |
abapGit 克隆需要 |
2. 账号与权限
云环境:开发用户 +
SAP_BR_DEVELOPER业务角色(仓库 README 明确要求);本地环境:
S_DEVELOP开发权限;需要能创建/修改包(Package)与传输请求(如果系统启用了传输);
如需查看后台处理监控:另外的后台处理/bgRFC 监控权限(没有也不影响主流程验证)。
3. 工具
工具 |
用途 |
安装方式 |
|---|---|---|
Eclipse IDE for Enterprise Java and Web Developers |
运行 ADT 的宿主 |
从 Eclipse 官网下载,建议较新的 2023-09 及以上版本 |
ABAP Development Tools(ADT) |
连接 ABAP 系统、开发/激活对象 |
Eclipse → |
abapGit ADT 插件 |
从 GitHub 拉取示例仓库 |
Eclipse → |
4. 开始前检查清单
Eclipse 已安装 ADT,能登录并打开你的 ABAP 系统(
File → New → ABAP Project);已安装 abapGit ADT 插件,视图
abapGit Repositories能打开;你的用户在系统里能创建开发包,且知道该把包放在哪个软件组件下(云环境常见是
ZLOCAL);已确认系统版本支持 bgPF(能激活
cl_bgmc_process_factory相关代码);预留 2–3 小时连续操作时间(后台任务的验证需要等待与刷新)。
操作步骤
每一步都按「做什么(为什么)→ 怎么做(菜单/字段/代码)→ 验证(看到什么算成功)」写。菜单名以你当前的 ADT/abapGit 版本为准,叫法不同时认准关键词即可。
步骤 1:准备并验证 ADT + abapGit 环境
做什么:准备好开发工具,确认能连系统、能看到 abapGit 视图。这一步没有写代码,但环境不对后面每一步都会卡住。
怎么做:
启动 Eclipse,
File → New → ABAP Project,选择你的 ABAP 系统,用开发用户登录。Window → Show View → Other…,在搜索框输入abapGit,选中abapGit Repositories,点击Open。视图打开后,右上角应出现一个
+(Link abapGit Repository)图标。
┌─ Project Explorer ───────────────────────────────┐
│ ▾ <你的 ABAP 系统> ← 步骤 1 要能登录到这里 │
│ ▾ $TMP / 你的包 │
│ ▾ abapGit Repositories ← 本步打开这个视图 │
│ (空) │
└───────────────────────────────────────────────────┘
验证:Project Explorer 里能看到你的系统节点;abapGit Repositories 视图能正常打开、不报连接错误。视图里暂时没有仓库是正常的(下一步才链接)。
卡点:
Show View里搜不到 abapGit → 插件没装成功,回到“准备工作”的更新站点步骤,装完必须重启 Eclipse。登录失败 → 先确认系统可达、用户未被锁定。
步骤 2:创建你自己的开发包
做什么:abapGit 需要把仓库对象放进一个 ABAP 包,所以先准备一个有权限的包。不要直接使用仓库作者原始的 ZFEL_ 前缀包(你的系统不一定允许创建)。
怎么做:
在 Project Explorer 的系统节点上右键 →
New → ABAP Package(或File → New → Other… → ABAP → ABAP Package)。按下面字段填写:
字段 |
示例值 |
说明 |
|---|---|---|
|
|
名字自定,全大写, |
|
|
会显示在包列表里 |
|
|
云环境通常选 |
传输请求 |
按系统提示选择/新建 |
系统启用传输时必填;本地开发系统可能无需传输 |
Finish保存。
验证:包创建成功,Project Explorer 里能看到 ZRAP_BGPF,右键能新建对象。
卡点:报“没有权限创建包” → 父包/软件组件受限,换一个你有开发权限的父包,或按管理员给的命名空间建包。后面的对象都会落在你刚建的包里。
步骤 3:用 abapGit 克隆示例仓库
做什么:把官方仓库的 ABAP 对象拉到你的系统里。仓库只有 main 一个分支,abapGit 元数据声明 STARTING_FOLDER=/src/、FOLDER_LOGIC=FULL。
怎么做:
在
abapGit Repositories视图里点右上角+(Link abapGit Repository)。按下面的示意填写链接信息(
Next/Finish,不同插件版本按钮文案略有差异):
+ Link abapGit Repository ─────────────────────────────────────────+
| Repository URL : https://github.com/SAP-samples/abap-platform- |
| rap-transactional-outbox-with-bgpf |
| Branch : main ← 点输入框右侧 … 选择 |
| Package : ZRAP_BGPF ← 步骤 2 建的包 |
| [Next] [Finish] |
+------------------------------------------------------------------+
链接成功后,在视图里选中该仓库,右键 →
Pull。首次Pull等同于克隆:abapGit 下载对象并创建src下的子包。拉取结束如弹出激活确认,选择激活;也可以在仓库节点右键找
Activate。
验证:
abapGit Repositories视图里仓库状态正常,没有红色错误提示;Project Explorer 的
ZRAP_BGPF下出现ZORDER、ZCL_RAP_BGPF_REQUEST_SHIPPING、ZSHIPPINGREQUEST_SERVICE_UI等对象;仓库里的
src/zfel_rap_bgpf_shipping/成为子包ZFEL_RAP_BGPF_SHIPPING(发货请求对象都在里面)。
卡点一:提示子包不存在或无权创建 → 先在
ZRAP_BGPF下手动创建子包ZFEL_RAP_BGPF_SHIPPING,再重新Pull。 卡点二:提示本地有未提交修改/冲突 → 你动过仓库文件;本案例只在拉取后再改代码,遇到冲突先取消本地修改再 Pull。 卡点三:网络无法访问 GitHub → 先在能上网的机器上git clone该仓库,推送到团队的 Git 镜像(GitLab/Gitea 等),在 abapGit 里把Repository URL换成镜像地址即可。仓库很小(几十个文件、两个包),镜像成本很低。 说明:src/zfel_rap_bgpf_order/只有包元数据、没有对象,订单对象直接放在仓库根目录,所以落在你克隆时选定的ZRAP_BGPF里。这是仓库本身的结构,不是拉取出错。
步骤 4:激活对象、核对对象地图、读懂关键源码
做什么:确保所有对象都已激活;对照对象地图确认没有缺件;并把下面几段关键源码读明白——后面每一步的现象都由这些代码决定。
怎么做:
打开 ADT 的未激活对象视图:
Window → Show View → Other… → ABAP → Inactive Objects(名称随 ADT 版本略有差异)。若有未激活对象:全选 → 右键Activate。打开包
ZRAP_BGPF,对照下表的对象地图核对:
位置 / 包 |
对象 |
类型 |
作用 |
|---|---|---|---|
|
|
数据库表 |
订单主数据 + 草稿表 |
|
数据库表 |
订单行项目 + 草稿表 |
|
|
CDS root view |
RAP 根实体 / 子实体视图 |
|
|
CDS projection view |
消费层视图(Fiori 用) |
|
|
CDS 元数据扩展 |
列表/对象页字段标签与布局 |
|
|
Behavior Definition |
|
|
|
Behavior Definition(投影层) |
消费层投影视图的行为定义 |
|
|
Behavior Pool |
行为实现 + 保存序列扩展(写发件箱的地方) |
|
|
Behavior Pool(投影层) |
消费层投影的行为实现(示例未添加自定义逻辑) |
|
|
Service Definition / Binding |
OData V4 UI 服务,可预览 |
|
|
ABAP 类 |
bgPF 操作类(投递动作),实现 |
|
|
|
数据库表 |
发货请求(模拟外部系统落地结果)+ 草稿 |
|
CDS 视图 |
发货请求视图, |
|
|
CDS 元数据扩展 |
发货请求界面布局 |
|
|
Behavior Definition |
managed + draft + 一个 on save determination |
|
|
Behavior Definition(投影层) |
消费层投影视图的行为定义 |
|
|
Behavior Pool |
行为实现(含交货日期 determination) |
|
|
Behavior Pool(投影层) |
消费层投影的行为实现 |
|
|
Service Definition / Binding |
OData V4 UI 服务,可预览 |
仓库里没有
ZOUTBOX之类的表——发件箱用的是 bgPF 自己的队列表,这是本案例的关键设计。
两个 BO 的关系,以及服务对外暴露的实体集:
ZR_ORDER000(订单根实体,managed + draft)
└─ _OrderItem ─────────────→ ZR_ORDERITEM(订单行项目)
ZR_SHIPPINGREQUEST(发货请求根实体,managed + draft)
└─ OrderReference ──引用────→ ZORDER.UUID(订单主键)
消费层 ZC_SHIPPINGREQUEST 里定义了 _Order 关联,界面上可以从发货请求跳到订单
服务绑定对外暴露的实体集(以服务绑定编辑器显示为准):
ZORDER_SERVICE_UI → 实体集 ZC_ORDER000、ZC_ORDERITEM
ZSHIPPINGREQUEST_SERVICE_UI → 实体集 ZC_SHIPPINGREQUEST
读第一段:订单行为定义(双击
ZR_ORDER000的 Behavior Definition,确认第一行):
managed with additional save implementation in class ZBP_R_ORDER000 unique;
strict ( 2 );
with draft;
extensible;
define behavior for ZR_ORDER000 alias Order000
persistent table zorder
extensible
draft table zorder_d
etag master LocalLastChangedAt
lock master total etag LastChangedAt
authorization master ( global )
{
field ( readonly ) UUID, LocalCreatedBy, LocalCreatedAt,
LocalLastChangedBy, LocalLastChangedAt, LastChangedAt;
field ( numbering : managed ) UUID;
create;
update;
delete;
draft action Activate optimized;
...
}
with additional save 是能插入保存序列逻辑的前提;with draft 决定了 Fiori 上先存草稿、Save 时激活的交互。
读第二段:保存序列里写发件箱(打开
ZBP_R_ORDER000,展开局部类lsc_zr_order000):
class lsc_zr_order000 definition inheriting from cl_abap_behavior_saver.
protected section.
methods save_modified redefinition.
endclass.
class lsc_zr_order000 implementation.
method save_modified.
if create-order000 is not initial.
loop at create-order000 assigning field-symbol(<ls_order>).
try.
data(lo_factory) = cl_bgmc_process_factory=>get_default( ).
data(lo_process) = lo_factory->create( ).
lo_process->set_name( 'Request shipping' )->set_operation(
zcl_rap_bgpf_request_shipping=>create_instance(
is_order = corresponding #( <ls_order> )
)
).
lo_process->save_for_execution( ).
catch cx_bgmc into data(lx_previous).
"handle exception
endtry.
endloop.
endif.
endmethod.
endclass.
三个必须读懂的细节:
为什么放在
save_modified,而不是 determination / action / 行为实现里? RAP 行为实现跑在交互阶段,之后还可能因校验、草稿、锁等失败而回滚;只有保存序列(save sequence)阶段的重定义才和“最终写入业务表”处在同一个数据库事务里。放在这里,发件箱条目才能与订单同生共死。只处理
create-order000:示例只对“新建订单”投递事件;更新、删除不会触发(步骤 11 练习补齐)。catch cx_bgmc里是空的:登记发件箱失败时,示例会吞掉异常,订单照样保存、事件却丢了——这是反模式。生产上应抛出去让保存回滚(宁可订单不落库,也不丢事件),或落补偿记录。
读第三段:投递动作(打开类
ZCL_RAP_BGPF_REQUEST_SHIPPING):
class zcl_rap_bgpf_request_shipping definition
public
final
create private .
public section.
class-methods create_instance
importing
is_order type zr_order000
returning
value(ro_instance) type ref to if_bgmc_op_single.
interfaces if_bgmc_op_single.
protected section.
private section.
methods constructor
importing
is_order type zr_order000.
data ms_order type zr_order000.
endclass.
class zcl_rap_bgpf_request_shipping implementation.
method if_bgmc_op_single~execute.
assert 1 = 2.
"implement outbound call or system local processing
modify entity zr_shippingrequest
create
set fields auto fill cid
with value #(
( ( %data = value #d(
OrderReference = ms_order-uuid
ShippingStatus = 'Ordered'
)
)
)
)
mapped data(mapped)
failed data(failed)
reported data(reported).
endmethod.
method create_instance.
return new zcl_rap_bgpf_request_shipping( is_order ).
endmethod.
method constructor.
ms_order = is_order.
endmethod.
endclass.
这段是全文的核心:
类实现
if_bgmc_op_single(受控变体),所以 bgPF 会把它当作 RAP 事务里的操作来执行;方法里不能COMMIT WORK。构造时把订单数据(
ms_order)存进对象,操作对象会被序列化进队列,后台执行时不需要再回查订单。execute里用 EML 在本地创建一条发货请求,模拟“外部系统受理了发货事件”;真实项目把这段换成对 Destination 的 HTTP 调用即可(步骤 11 练习 A)。assert 1 = 2.是仓库原样带的一行:按原样运行,后台进程必然失败。它既是“停在这里、把外部调用换成你自己的实现”的占位,也正好是现成的失败注入开关:删掉它 = 正常投递;加回它 = 制造外部失败。后面步骤 6 与步骤 8 会各用一次。
读第四段(可选,但能解释验收值):打开
ZBP_R_SHIPPINGREQUEST的局部类,determineEstDeliveryDate把交货日期设为系统日期 + 14 天:
METHOD determineEstDeliveryDate.
READ ENTITIES OF zr_shippingrequest IN LOCAL MODE
ENTITY ShippingRequest
FIELDS ( EstimatedDeliveryDate )
WITH CORRESPONDING #( keys )
RESULT DATA(entities).
LOOP AT entities INTO DATA(entity).
DATA(lv_estimated_delivery_date) = cl_abap_context_info=>get_system_date( ) + 14.
MODIFY ENTITIES OF zr_shippingrequest IN LOCAL MODE
ENTITY ShippingRequest
UPDATE FIELDS ( EstimatedDeliveryDate )
WITH VALUE #( (
%tky = entity-%tky
EstimatedDeliveryDate = lv_estimated_delivery_date
) ).
ENDLOOP.
ENDMETHOD.
验证:未激活对象列表为空;对象地图中的对象都能双开;你已能在源码里指出“登记发件箱”的那一行 lo_process->save_for_execution( ).,并知道 assert 1 = 2. 在哪个类里。
步骤 5:发布服务绑定并打开两个预览
做什么:把两个 OData V4 UI 服务发布出来,得到可操作的 Fiori 预览界面。
怎么做:
双击服务绑定
ZORDER_SERVICE_UI,在编辑器里点击Publish(仓库元数据里已标记 published,但新克隆到你系统后建议重新发布一次)。发布后,在同一编辑器或右键菜单里打开预览:
Open Fiori Elements App Preview/Preview(ADT 版本不同叫法不同)。浏览器打开订单列表页;对
ZSHIPPINGREQUEST_SERVICE_UI重复同样的发布 + 预览操作。两个标签页都留着,后面要在它们之间来回对照。
Service Binding: ZORDER_SERVICE_UI
Binding Type : OData V4 - UI
Service Def. : ZORDER_SERVICE
[Publish] ← 发布后状态变为 Published
Service URL : /sap/opu/odata4/sap/zorder_service/srvd/sap/zorder_service/0001/
Preview : ▸ ZC_ORDER000 ← 点实体集打开 Fiori Elements 预览
订单预览对应实体集 ZC_ORDER000,发货请求预览对应实体集 ZC_SHIPPINGREQUEST;实体集名称以你服务绑定编辑器里显示的为准。
发布是否成功的判定:编辑器里绑定状态为 Published、Service URL 可复制;预览页能正常加载列表(哪怕列表是空的)。如果 Publish 报错,先看 ADT 的 Problem 视图,最常见原因是服务定义/视图没激活,或当前用户缺少该服务的访问权限。
验证:订单预览页出现列表和 Create 按钮;发货请求预览页出现空列表(此时还没有任何发货请求)。浏览器若拦截弹窗,允许 Eclipse 打开浏览器。
卡点:预览打不开 → 先确认服务绑定已激活、已
Publish、当前用户有服务访问权限;再检查浏览器弹窗拦截。仍不行就看 ADT 的Problem视图里的错误。
步骤 6:删掉断言,跑通正常投递
做什么:先让官方示例跑通成功链路:删掉 execute 里的 assert 1 = 2.,保存订单,观察异步生成发货请求。
怎么做:
打开
ZCL_RAP_BGPF_REQUEST_SHIPPING,进入if_bgmc_op_single~execute方法,把第一行assert 1 = 2.用*"注释掉或直接删除(后面还要加回来,建议先注释,保留现场)。Ctrl+S保存,然后右键Activate(或工具栏 Activate)激活。必须先激活再保存订单,否则运行的还是旧版本。回到订单预览页,点
Create,按下面示例填写:
字段 |
示例值 |
说明 |
|---|---|---|
|
|
10 位以内 |
|
今天 |
日期选择器 |
|
|
最长 40 位 |
|
|
状态字段自由文本 |
行项目(可选) |
|
不填也能保存 |
订单列表(Fiori Elements List Report,示意)
┌──────────────────────────────────────────────────────────┐
│ [Create] 🔍 Search ⚙ Filter │
├──────────┬────────────┬────────────────┬─────────────────┤
│ Order ID │ Order Date │ Customer Name │ Status Draft? │
│ SO-1001 │ 今天 │ Demo Customer │ New (空) │
└──────────┴────────────┴────────────────┴─────────────────┘
点 Create → 弹出对象页(草稿)→ 按上表填写 → 点 Save
点
Save。由于订单是草稿式 BO(with draft),Save会执行草稿激活,从而触发保存序列。这里有一个容易混淆的点:
Create之后你在对象页里编辑的是草稿(Draft),此时订单还没有真正落到ZORDER,也不会登记发件箱;只有点Save让草稿激活(draft actionActivate)时,才走保存序列、写业务表并登记 bgPF。列表上如果还显示草稿标记,说明链路没走完,不要急着查后台。等 10–30 秒,切到发货请求预览页刷新(bgPF 后台执行有排队延迟,通常几秒钟)。
验证:
订单列表出现
SO-1001,且不在草稿状态(列表上不再显示草稿标记);发货请求列表新增一条记录:
OrderReference与订单的 UUID 一致,ShippingStatus=Ordered,EstimatedDeliveryDate= 今天 + 14 天;两条记录的创建时间不同(发货请求晚几秒),说明投递发生在独立后台单元里,不在用户请求内部。
发货请求列表(成功后,示意)
┌───────────────────────┬──────────────────────┬──────────────┬──────────────┐
│ Shipping Request ID │ Order Reference │ Status │ Est. Delivery│
│ <自动编号> │ <订单 UUID> │ Ordered │ 今天 + 14 天 │
└───────────────────────┴──────────────────────┴──────────────┴──────────────┘
卡点:订单保存了但 60 秒后仍无发货请求 → 依次检查:①
assert是否真的注释并激活;② 订单是否为草稿状态(未激活不会跑保存序列);③ 后台监控里是否有失败单元(错误信息通常直接指向execute这一行)。
步骤 7:核对“事务边界”与“延迟投递”
做什么:确认你观察到的是发件箱语义,不是“保存后顺手同步调用了一下”。这一步是阅读 + 对照,不改代码。
怎么做:
打开
ZBP_R_ORDER000的save_modified,确认它只在create-order000时登记进程,且没有COMMIT WORK;打开
ZCL_RAP_BGPF_REQUEST_SHIPPING的execute,确认里面没有COMMIT WORK(受控变体由框架负责提交);对着下表逐项确认证据:
要证明的结论 |
在哪里看 |
本案例的证据 |
|---|---|---|
发件箱登记与业务写库同事务 |
|
登记语句位于 RAP 保存序列的 saver 类中;这里没有独立提交 |
提交之前不会执行 |
源码 + 现象 |
|
回滚则事件消失 |
语义(可推理) |
保存序列失败 → 登记随之回滚 → 队列里不会留下条目 |
外部调用不在业务事务里 |
时间戳 |
订单与发货请求的 |
用自己的话把“为什么订单保存失败时不会产生发货请求,而外部投递失败时订单不会回滚”说一遍。说不清就回看“架构与原理”第 2、3 节。
验证:你能指出上面 4 条各自对应的源码位置或现象,并解释 save_for_execution( ) 与 COMMIT WORK 的分工。
步骤 8:注入失败——把断言加回去
做什么:模拟“外部系统不可用”。最干净的方式就是把 assert 1 = 2. 恢复回去,让后台投递每次执行都失败。
怎么做:
回到
ZCL_RAP_BGPF_REQUEST_SHIPPING,把assert 1 = 2.取消注释(恢复原样),保存并激活。回到订单预览页,再新建一张订单:
OrderID=SO-1002,其余字段同步骤 6,Save(激活草稿)。等 10–30 秒,刷新两个预览页。
验证(本步的关键对照):
注入失败后的预期状态
┌───────────────────────────────┬────────────────────────────────────┐
│ 订单 SO-1002 │ 发货请求(OrderReference = 该订单)│
├───────────────────────────────┼────────────────────────────────────┤
│ ✅ 保存成功,出现在订单列表 │ ❌ 没有新增记录 │
│ ✅ 业务数据已提交(刷新仍在) │ ❌ 外部投递失败 │
└───────────────────────────────┴────────────────────────────────────┘
结论:外部调用失败没有回滚业务数据 —— 这正是发件箱要保证的行为。
也可以换其他失败方式(任选,效果等价,但推荐用仓库自带的断言):
注入方式 |
做法 |
适用 |
|---|---|---|
断言失败(推荐) |
保留 |
不依赖外部环境,最稳定 |
抛异常 |
在 |
想验证“异常被 bgPF 捕获并标记错误” |
外部不可达 |
把 EML 换成 HTTP 调用并配一个错误 URL |
练习真实外部集成时 |
卡点:刷新后发现订单也没保存 → 说明你误改了业务代码或保存失败,回滚看
Problem视图;如果订单保存成功但发货请求也出现了,说明assert没生效(没激活,或注释没删干净)。
步骤 9:确认事件没丢,观察失败状态与重试
做什么:验证失败的事件仍被持久化在后台队列里,并且可以被重启(重试)。
怎么做:
打开后台处理/bgRFC 监控(入口见“架构与原理”第 3 节;云环境是 Fiori 监控类应用,本地常见是 bgRFC 监控器)。
按进程名
Request shipping、时间范围(最近 15 分钟)、状态(错误)筛选,找到刚才的失败单元。打开单元详情,查看状态、尝试次数、出错时间与错误信息。应能看到断言失败(
ASSERTION_FAILED/ 运行时错误)以及调用栈停在ZCL_RAP_BGPF_REQUEST_SHIPPING~EXECUTE。对该单元执行
Restart(重启/重试)一次,然后刷新监控与发货请求预览。
找不到目标单元时:先按进程名
Request shipping过滤(这是代码里set_name设置的名字,不是类名),再按最近时间范围与状态筛选;单元详情里的错误文本和调用栈是最直接的线索。Restart不可用(没有权限、或该状态不允许重启)时,请管理员在监控里操作;也可以用步骤 10 的路线 B 继续验证,但别忘了事后清理这个失败单元。
后台处理监控(示意)
┌──────────────────┬──────────┬────────┬──────┬──────────────────────┐
│ 进程名 │ 时间 │ 状态 │ 尝试 │ 错误信息 │
├──────────────────┼──────────┼────────┼──────┼──────────────────────┤
│ Request shipping │ 10:21:03 │ 错误 │ 1 │ ASSERTION_FAILED │
│ │ │ │ │ [重启] [删除] │
└──────────────────┴──────────┴────────┴──────┴──────────────────────┘
状态含义(不同版本叫法略有差异):排队/新建(还没轮到执行)→ 执行中 → 成功(successful)或错误(erroneous)。错误单元不会被自动丢弃。
重试的三种常见情形(观察时对号入座):
情形 |
监控里看到什么 |
你要做什么 |
|---|---|---|
手动重启 |
单元从错误 → 排队/执行 → 再次错误或成功;尝试次数/时间戳更新 |
代码没修好时重启只会再失败一次;修好后再重启才会成功 |
系统配置了自动重启策略 |
单元在错误与重试之间反复往返,错误时间/次数增加 |
先修代码,否则只是把失败重复若干次;没有配置时不会自动重放 |
同队列后续单元被阻塞 |
后续登记的任务迟迟不执行,队列头是那个错误单元 |
优先处理/删除队列头部的错误单元,再让后续任务跑起来 |
读错误信息的技巧:先看错误文本(断言失败会显示 ASSERTION_FAILED 之类),再看调用栈最上面那个你自己的方法(通常是 ZCL_RAP_BGPF_REQUEST_SHIPPING~EXECUTE),最后才看框架层——绝大多数问题都在你自己的那一行。
验证:
监控里能看到该后台单元的失败状态与错误信息;
重启会让单元重新执行一次(这就是一次“重试”);因为
assert 1 = 2.还在,所以仍旧失败,尝试次数/时间戳更新;发货请求列表始终没有
SO-1002;订单
SO-1002一直在。
这说明什么:bgPF/bgRFC 对失败单元的默认处理是“保留 + 标记错误”,通常需要监控器里手动重启(或由系统配置的自动重启策略处理),不是无限制自动重放;这也是生产上必须配监控告警的原因。你的系统如果没有暴露监控入口,记录下“订单在、发货请求不在”这一对证据,并在步骤 10 用修复后的成功来反证事件仍可投递。
步骤 10:修复后验证最终一致
做什么:删除断言(恢复成功版本),让失败单元重试成功或触发新事件,证明最终一致性。
怎么做(二选一,推荐先 A 后 B):
A. 重启失败单元
打开
ZCL_RAP_BGPF_REQUEST_SHIPPING,再次注释/删除assert 1 = 2.,保存并激活;回到监控,对步骤 9 里的失败单元点
Restart;等几秒刷新发货请求预览。
B. 触发新事件
新建订单 SO-1003 并保存,等后台执行。
怎么选:有监控权限、想证明“失败的事件仍能原样重放” → 走 A;没有监控权限、只想验证新事件能通 → 走 B。A 的证据更强(同一个单元从错误变成功),B 更省事。
验证:
路线 |
预期现象 |
|---|---|
A(重启旧单元) |
发货请求列表出现 |
B(新事件) |
新订单 |
两条路线共同点 |
|
一致性核对:任选一种方式确认“订单 ↔ 发货请求”确实对得上:
在订单预览里复制订单的
UUID,到发货请求列表按OrderReference过滤,应该恰好一条;在发货请求的对象页里通过
_Order关联跳回订单,确认是同一条订单;在 ADT 里对
ZSHIPPINGREQUEST打开数据预览,按ORDER_REFERENCE查,确认没有重复/孤儿记录(数据预览是只读的,适合核对)。
补充:失败的 bgPF 单元里保存的是“操作对象 + 订单数据”的序列化快照,执行时加载的是当前代码。所以修复代码后重启旧单元通常可以直接成功;但若期间改动了操作类的结构(例如给
is_order换类型/字段),旧单元可能反序列化失败,这时应清理旧单元,用新事件验证。
步骤 11(选做):改造练习
做什么:把示例改造成更接近生产的实现。任选 1–2 个完成即可,每个都能独立验证。
练习 A:把本地 EML 换成真正的外部调用
在 execute 里改为通过 Destination 发 HTTP POST(Destination 由管理员在通信场景/目标配置里预先建好)。思路(伪代码,签名以你系统 API 版本为准):
" 伪代码:把本地 EML 换成外部 HTTP 调用
TRY.
DATA(lo_destination) = cl_http_destination_provider=>create_by_cloud_destination(
i_name = 'ZSHIPPING_API' ).
DATA(lo_client) = cl_web_http_client_manager=>create_by_http_destination( lo_destination ).
lo_client->set_method( if_web_http_client=>post ).
lo_client->set_text( |{ ms_order-uuid }| ).
lo_client->execute( ).
CATCH cx_web_http_client_error cx_http_dest_provider_error INTO DATA(lx_error).
" 关键:不要吞异常,抛出去让 bgPF 标记失败并保留单元
RAISE EXCEPTION lx_error.
ENDTRY.
练习 B:给事件加业务字段
除了 OrderReference,再写一个“事件类型”字段(需先给 ZSHIPPINGREQUEST 加字段、改 CDS 视图与 BDEF 映射)。练习的是“发件箱里的操作对象要携带足够上下文”——注意这会影响已入队单元的反序列化(见步骤 10 补充)。
练习 C:给投递加幂等
发件箱是至少一次投递,重复执行会重复创建发货请求。做法:在 execute 里先查是否已投递,存在就直接返回:
" 幂等:同一订单只投递一次
SELECT SINGLE @abap_true FROM zshippingrequest
WHERE order_reference = @ms_order-uuid
INTO @DATA(lv_already_delivered).
IF lv_already_delivered = abap_true.
RETURN.
ENDIF.
然后在 ZSHIPPINGREQUEST 上给 ORDER_REFERENCE 加唯一约束(或在保存时检查)。验证方式:故意让同一订单登记两次进程(例如在 save_modified 里临时循环两次),观察没有幂等时出现两条记录、有幂等时只有一条。
练习 D:把登记失败改成“宁可失败也不丢事件”
把 save_modified 里空的 catch cx_bgmc 改成把异常抛出去,让订单保存回滚,而不是丢事件:
CATCH cx_bgmc INTO DATA(lx_previous).
" 生产建议:宁可保存失败,也不要丢事件
RAISE EXCEPTION lx_previous.
练习 E:把后台进程的监控 ID 存下来,按状态查询
save_for_execution( ) 会返回一个监控对象,示例里把它丢掉了。改造 save_modified 可以拿到监控 ID(一段 XML 字符串),存进自建日志表后就能在 ADT 里按状态查询:
" save_modified 里:登记进程并拿到监控对象
data(lo_monitor) = lo_process->save_for_execution( ).
" 监控 ID 是一段 XML 字符串;写入你自建的日志表(示例字段:order_uuid、monitor_id、created_at)
data(lv_monitor_id) = lo_monitor->to_string( ).
" 另建一个控制台类(实现 if_oo_adt_classrun),按 ID 查状态
class zcl_bgpf_check_monitor definition public final create public.
public section.
interfaces if_oo_adt_classrun.
endclass.
class zcl_bgpf_check_monitor implementation.
method if_oo_adt_classrun~main.
data(lo_monitor) = cl_bgmc_process_factory=>create_monitor_from_string(
'<从日志表读出的监控 ID>' ).
out->write( lo_monitor->get_state( ) ).
endmethod.
endclass.
get_state( ) 返回的状态常量在 if_bgmc_process_monitor=>gcs_state-*(如 gcs_state-successful、gcs_state-erroneous,不同版本还可能有运行中等状态)。验证方式:正常投递后查询应得到 successful,注入失败后查询应得到 erroneous——这样即使没有监控应用权限,也能在 ADT 里自证“事件没丢”。
日志表用 ADT 新建一个普通数据库表即可(
New → Other… → ABAP Dictionary → Database Table,字段如order_uuid(sysuuid_x16)、monitor_id(abap.char(255))、created_at(abap.utclong),主键用order_uuid),在save_modified里INSERT一行。注意save_modified也在业务事务里,写日志同样与订单同生共死,别在这里做耗时操作。
验证:每个练习都要能说出“改了什么 → 在哪个界面/表里能看到差异”,并重跑步骤 6–10 确认主链路没有被破坏。
验收与清理
验收清单
# |
验收项 |
通过标准 |
|---|---|---|
1 |
克隆与激活 |
未激活对象为空;两个服务绑定均为 OData V4 UI 且已发布 |
2 |
正常投递 |
订单保存后 30 秒内发货请求生成,字段值正确(状态 Ordered、日期 +14 天) |
3 |
事务边界 |
订单保存失败不会产生发货请求;发货请求创建时间晚于订单 |
4 |
失败隔离 |
注入失败后订单仍在、发货请求不生成 |
5 |
事件不丢 |
失败单元保留在后台队列,可监控、可重启 |
6 |
最终一致 |
修复后重启或新事件能成功投递 |
7 |
理解 |
能解释“为什么同步调用不可靠”“受控变体为什么不能 COMMIT”“为什么需要幂等” |
清理
清测试数据:在两个预览里删除
SO-1001/1002/1003及对应发货请求(列表选中 →Delete;如有草稿,先用Discard丢弃)。删除是物理删除,做之前确认不是共享系统。清理监控里的失败单元:步骤 9 留下的失败单元在监控里删除,避免它反复告警或阻塞同队列后续单元。
停用/删除服务绑定:只是本地练习可以保留;如需还原,先
Unpublish再删除绑定(服务定义、CDS 视图可保留)。删除仓库对象:在
abapGit Repositories视图里右键仓库 →Unlink解绑(只解除关联,不删对象);确认不再需要后,再在 Project Explorer 里删除包ZRAP_BGPF及其内容(删除包时勾选删除其中对象)。注意:如果同一系统有其他人引用这些Z*对象,先确认再删。回收资源:如果在 BTP 试用/临时租户里练习,结束后按管理员流程清理不用的子账户/服务实例;不要长期保留无人值守的后台失败任务。
常见问题
# |
现象 |
原因 |
处理 |
|---|---|---|---|
1 |
保存订单后,发货请求始终不出现 |
仓库原样带 |
打开 |
2 |
订单保存了,但后台没有登记记录 |
只保存了草稿,没有触发激活(保存序列只在激活/最终保存时执行) |
在 Fiori 里点 |
3 |
更新/删除订单不会产生发货请求 |
|
按需在保存序列里增加 update/delete 分支(先想清楚事件语义:是“订单变更事件”还是“下单事件”) |
4 |
拉取仓库报“包不存在/没有权限” |
abapGit 需要按 |
手动创建子包 |
5 |
代码里找不到 |
系统不是 ABAP Cloud,或本地版本低于 S/4HANA 2023、或 bgPF 未配置 |
换 ABAP Cloud 环境(BTP ABAP Environment);本地环境请管理员确认版本与配置;注意别把受控 |
6 |
后台进程失败,但找不到监控入口 |
云/本地监控入口和权限不同 |
找管理员确认后台处理/bgRFC 监控的 Fiori 应用或事务码及权限;没有监控权限时,用“订单在、发货请求不在”作为主证据,并在修复后验证成功 |
7 |
重启失败单元后仍然失败 |
断言/异常代码还在;或旧单元里序列化的数据结构已与当前类不兼容 |
确认修复已激活、代码是新版本;若改过操作类结构,删除旧单元,用新订单验证 |
8 |
发货请求出现两条(或更多)重复记录 |
至少一次投递:重复登记或重试会重复执行;示例没有幂等 |
这是预期语义;按 |
9 |
预览页打不开 / 没有 Fiori 元素界面 |
服务绑定未激活或未发布;用户缺服务权限;ADT/浏览器弹窗拦截 |
重新激活并发布服务绑定,检查绑定 |
10 |
改了 |
本地修改与远端冲突 |
abapGit 拉取前先确保没有本地未提交修改;练习时尽量只改 |
官方原文(参考)
本地原始文档(仓库 README 中文整理版,含对象与许可说明):99-03-transactional-outbox.md
官方仓库:SAP-samples/abap-platform-rap-transactional-outbox-with-bgpf
模式背景博客(SAP Community):Cloud Native with ABAP Cloud: The Transactional Outbox Pattern
ADT 安装教程(SAP Developers):Installing ABAP Development Tools for Eclipse
abapGit ADT 插件更新站点:abapGit Repositories ADT Plug-In
bgPF 机制与监控资料:Introducing the Background Processing Framework、ABAP Cloud – Background processing(含监控对象与状态示例)、SAP Help:Using the bgRFC Monitor
本教程与原版的关系:官方仓库以源码作为参考实现,README 只提供环境要求、安装入口与许可信息,没有逐步截图和操作说明。本篇按“对象地图 → 调用链 → 逐步操作 → 失败实验 → 验收清理”的路径,把仓库源码逐行还原成可离线照做的教程;文中所有对象名、代码、字段均取自仓库 main 分支(提交 8cd3f64)的实际内容,未编造 SAP 标准对象。仓库代码版权归 SAP SE,遵循 Apache-2.0 许可。