03 · 事务性发件箱(Transactional Outbox):完整教程

目标:用 RAP + bgPF 实现 Transactional Outbox,理解“先落库、再异步投递”的生产级做法。 预计:2–3 小时 | 难度:中 | 前置课程:S4D426、S4D401(Application Job 部分)

关于图片:本案例官方仓库只有 README 与 ABAP 源码,没有附带步骤截图,assets/ 下也没有对应图片资产。因此本篇不插入任何图片——既不伪造本地截图,也不引用远程图片——改用界面示意(ASCII)、对象地图、完整源码和验收清单把每一步讲到可离线照做。文中的“界面示意图”是根据操作逻辑画的结构示意,不是截图,实际界面以你的系统为准。


你会做出什么

一个「订单 → 发货请求」的小型 RAP 应用:

  • 用户在 Fiori 预览里新建并保存一张订单(草稿激活);

  • 订单提交成功之后,系统通过后台处理框架(bgPF)异步生成一条“发货请求”,模拟向外部系统(发货/物流平台)下单;

  • 外部投递失败时,订单照样保存成功,事件不会丢,可以观察失败状态并重试;

  • 修复/恢复后,事件最终一致地投递成功。

最终效果清单

#

你会看到什么

说明

1

订单预览能新建、保存订单

列表页出现一条非草稿状态的订单

2

保存后几秒内,发货请求预览多出一条记录

OrderReference = 订单的 UUID

3

发货请求的 ShippingStatus = Ordered

投递类里写死的业务值

4

发货请求的 EstimatedDeliveryDate = 保存当天 + 14 天

由 determination 计算

5

注入失败后保存订单:订单在、发货请求不在

外部失败不影响业务落库

6

后台进程单元停在错误状态,可重启

事件没丢、可重试

7

修复后重启/重新触发,发货请求最终出现

最终一致性

你不需要自建“发件箱表”。在 ABAP Cloud 里,bgPF 的队列本身就是发件箱:它把“待执行的业务操作”和订单数据在同一个数据库事务里持久化,提交之后再由后台任务执行。这是本案例最值得带走的认知。


架构与原理

1. 要解决的问题:一次数据库提交 + 一次外部调用,无法原子化

订单落库是本地数据库事务,可以 COMMIT / ROLLBACK;调用外部系统是网络请求,无法参与本地事务。二者组合时,任何“先后顺序”都有漏洞:

做法

正常时

外部系统故障

进程在两步之间崩溃

结论

先调外部,再提交数据库

看起来都对

外部已受理,本地回滚 → 外部多了一单

外部已受理,本地未提交 → 数据不一致

不可用

先提交数据库,再调外部

看起来都对

订单已提交,事件丢失

提交后崩溃 → 事件永久丢失

会丢事件

把外部调用塞进业务事务里

看起来都对

外部失败导致业务事务回滚

长事务、锁等待,不可接受

业务被拖垮

事务性发件箱(本案例)

正常

事件保留、可重试

提交即意味着事件已持久化

生产级

根本矛盾在于:“写数据库”和“调外部接口”是两个不同资源,没有共同的事务管理器。跨组织、跨公网的分布式事务基本不可行,所以业界统一退一步,用“本地事务 + 可靠异步投递”来逼近一致性。

2. 发件箱模式的三条规则

  1. 同事务落库:业务数据(订单)和“待发送事件/待执行操作”必须在同一个数据库事务里写入。要么都成功,要么都失败,不存在“订单有了但事件没有”。

  2. 独立投递:提交之后,由独立的后台机制读取发件箱、执行外部调用,与用户请求/业务事务解耦。

  3. 至少一次 + 幂等:投递失败可重试,因此会出现重复投递(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 触发执行

它提供两种操作接口,对应两种执行模型:

接口

变体

适用场景

关键约束

if_bgmc_op_single

受控(controlled)

RAP 场景,本案例使用

框架会走 RAP 的事务阶段;方法里不能 COMMIT WORK

if_bgmc_op_single_tx_uncontr

非受控(uncontrolled)

非 RAP 的普通后台处理

自己负责 COMMIT WORK

bgPF 的生命周期有三个关键不变量,正是发件箱语义的来源:

  1. save_for_execution( ) 只登记、不执行:它把操作对象(含构造时传入的订单数据)序列化进 bgPF 队列,属于当前数据库事务的一部分。

  2. 只有 COMMIT WORK 之后才可能执行:事务提交,队列条目才被调度;事务回滚(ROLLBACK WORK),条目随之消失,后台任务根本不会启动。

  3. 执行在独立的后台单元里完成:用户会话已经结束也无妨;失败时单元保留错误状态,可以监控、可以重启(重试)。

因此,“在 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 起随本地版本交付,但需要管理员先完成配置;cl_bgmc_process_factory 等 API 的可用性以你系统版本为准。建议先在 ABAP Cloud 环境完成本案例

允许访问 GitHub

abapGit 克隆需要 github.com 出站访问;若网络受限,先让管理员放行或使用镜像

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 → Help → Install New Software…,使用 SAP 官方 ADT 更新站点(见文末参考)

abapGit ADT 插件

从 GitHub 拉取示例仓库

Eclipse → Help → Install New Software… → Add… → 位置填 abapGit 官方更新站点(见文末参考)→ 勾选 abapGit Repositories ADT Plug-In → 安装并重启 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 视图。这一步没有写代码,但环境不对后面每一步都会卡住。

怎么做:

  1. 启动 Eclipse,File → New → ABAP Project,选择你的 ABAP 系统,用开发用户登录。

  2. Window → Show View → Other…,在搜索框输入 abapGit,选中 abapGit Repositories,点击 Open。

  3. 视图打开后,右上角应出现一个 +(Link abapGit Repository)图标。

┌─ Project Explorer ───────────────────────────────┐
│ ▾ <你的 ABAP 系统>          ← 步骤 1 要能登录到这里 │
│    ▾ $TMP / 你的包                                │
│ ▾ abapGit Repositories      ← 本步打开这个视图     │
│    (空)                                           │
└───────────────────────────────────────────────────┘

验证:Project Explorer 里能看到你的系统节点;abapGit Repositories 视图能正常打开、不报连接错误。视图里暂时没有仓库是正常的(下一步才链接)。

卡点:Show View 里搜不到 abapGit → 插件没装成功,回到“准备工作”的更新站点步骤,装完必须重启 Eclipse。登录失败 → 先确认系统可达、用户未被锁定。

步骤 2:创建你自己的开发包

做什么:abapGit 需要把仓库对象放进一个 ABAP 包,所以先准备一个有权限的包。不要直接使用仓库作者原始的 ZFEL_ 前缀包(你的系统不一定允许创建)。

怎么做:

  1. 在 Project Explorer 的系统节点上右键 → New → ABAP Package(或 File → New → Other… → ABAP → ABAP Package)。

  2. 按下面字段填写:

字段

示例值

说明

Name

ZRAP_BGPF

名字自定,全大写,Z 开头

Description

Transactional outbox demo

会显示在包列表里

Superpackage

ZLOCAL 或你被授权的父包

云环境通常选 ZLOCAL;有自定义软件组件时选对应包

传输请求

按系统提示选择/新建

系统启用传输时必填;本地开发系统可能无需传输

  1. Finish 保存。

验证:包创建成功,Project Explorer 里能看到 ZRAP_BGPF,右键能新建对象。

卡点:报“没有权限创建包” → 父包/软件组件受限,换一个你有开发权限的父包,或按管理员给的命名空间建包。后面的对象都会落在你刚建的包里。

步骤 3:用 abapGit 克隆示例仓库

做什么:把官方仓库的 ABAP 对象拉到你的系统里。仓库只有 main 一个分支,abapGit 元数据声明 STARTING_FOLDER=/src/、FOLDER_LOGIC=FULL。

怎么做:

  1. 在 abapGit Repositories 视图里点右上角 +(Link abapGit Repository)。

  2. 按下面的示意填写链接信息(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]       |
+------------------------------------------------------------------+
  1. 链接成功后,在视图里选中该仓库,右键 → Pull。首次 Pull 等同于克隆:abapGit 下载对象并创建 src 下的子包。

  2. 拉取结束如弹出激活确认,选择激活;也可以在仓库节点右键找 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:激活对象、核对对象地图、读懂关键源码

做什么:确保所有对象都已激活;对照对象地图确认没有缺件;并把下面几段关键源码读明白——后面每一步的现象都由这些代码决定。

怎么做:

  1. 打开 ADT 的未激活对象视图:Window → Show View → Other… → ABAP → Inactive Objects(名称随 ADT 版本略有差异)。若有未激活对象:全选 → 右键 Activate。

  2. 打开包 ZRAP_BGPF,对照下表的对象地图核对:

位置 / 包

对象

类型

作用

ZRAP_BGPF(仓库根目录)

ZORDER、ZORDER_D

数据库表

订单主数据 + 草稿表

ZORDERITEM、ZORDERITEM_D

数据库表

订单行项目 + 草稿表

ZR_ORDER000、ZR_ORDERITEM

CDS root view

RAP 根实体 / 子实体视图

ZC_ORDER000、ZC_ORDERITEM

CDS projection view

消费层视图(Fiori 用)

ZC_ORDER000(metadata extension)

CDS 元数据扩展

列表/对象页字段标签与布局

ZR_ORDER000(bdef)

Behavior Definition

managed with additional save + with draft

ZC_ORDER000(bdef)

Behavior Definition(投影层)

消费层投影视图的行为定义

ZBP_R_ORDER000

Behavior Pool

行为实现 + 保存序列扩展(写发件箱的地方)

ZBP_C_ORDER000

Behavior Pool(投影层)

消费层投影的行为实现(示例未添加自定义逻辑)

ZORDER_SERVICE / ZORDER_SERVICE_UI

Service Definition / Binding

OData V4 UI 服务,可预览

ZCL_RAP_BGPF_REQUEST_SHIPPING

ABAP 类

bgPF 操作类(投递动作),实现 if_bgmc_op_single

ZFEL_RAP_BGPF_SHIPPING(仓库子目录)

ZSHIPPINGREQUEST、ZSHPPNGREQUEST_D

数据库表

发货请求(模拟外部系统落地结果)+ 草稿

ZR_SHIPPINGREQUEST、ZC_SHIPPINGREQUEST

CDS 视图

发货请求视图,ZC_... 通过 _Order 关联订单

ZC_SHIPPINGREQUEST(metadata extension)

CDS 元数据扩展

发货请求界面布局

ZR_SHIPPINGREQUEST(bdef)

Behavior Definition

managed + draft + 一个 on save determination

ZC_SHIPPINGREQUEST(bdef)

Behavior Definition(投影层)

消费层投影视图的行为定义

ZBP_R_SHIPPINGREQUEST

Behavior Pool

行为实现(含交货日期 determination)

ZBP_C_SHIPPINGREQUEST

Behavior Pool(投影层)

消费层投影的行为实现

ZSHIPPINGREQUEST_SERVICE / ..._UI

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
  1. 读第一段:订单行为定义(双击 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 时激活的交互。

  1. 读第二段:保存序列里写发件箱(打开 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 里是空的:登记发件箱失败时,示例会吞掉异常,订单照样保存、事件却丢了——这是反模式。生产上应抛出去让保存回滚(宁可订单不落库,也不丢事件),或落补偿记录。

  1. 读第三段:投递动作(打开类 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 会各用一次。

  1. 读第四段(可选,但能解释验收值):打开 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 预览界面。

怎么做:

  1. 双击服务绑定 ZORDER_SERVICE_UI,在编辑器里点击 Publish(仓库元数据里已标记 published,但新克隆到你系统后建议重新发布一次)。

  2. 发布后,在同一编辑器或右键菜单里打开预览:Open Fiori Elements App Preview / Preview(ADT 版本不同叫法不同)。

  3. 浏览器打开订单列表页;对 ZSHIPPINGREQUEST_SERVICE_UI 重复同样的发布 + 预览操作。

  4. 两个标签页都留着,后面要在它们之间来回对照。

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.,保存订单,观察异步生成发货请求。

怎么做:

  1. 打开 ZCL_RAP_BGPF_REQUEST_SHIPPING,进入 if_bgmc_op_single~execute 方法,把第一行 assert 1 = 2. 用 *" 注释掉或直接删除(后面还要加回来,建议先注释,保留现场)。

  2. Ctrl+S 保存,然后右键 Activate(或工具栏 Activate)激活。必须先激活再保存订单,否则运行的还是旧版本。

  3. 回到订单预览页,点 Create,按下面示例填写:

字段

示例值

说明

OrderID

SO-1001

10 位以内

OrderDate

今天

日期选择器

CustomerName

Demo Customer

最长 40 位

Status

New

状态字段自由文本

行项目(可选)

OrderItemID、ProductName、Quantity、UnitPrice、CurrencyCode

不填也能保存

订单列表(Fiori Elements List Report,示意)
┌──────────────────────────────────────────────────────────┐
│ [Create]                          🔍 Search   ⚙ Filter    │
├──────────┬────────────┬────────────────┬─────────────────┤
│ Order ID │ Order Date │ Customer Name  │ Status  Draft?  │
│ SO-1001  │ 今天       │ Demo Customer  │ New     (空)     │
└──────────┴────────────┴────────────────┴─────────────────┘
点 Create → 弹出对象页(草稿)→ 按上表填写 → 点 Save
  1. 点 Save。由于订单是草稿式 BO(with draft),Save 会执行草稿激活,从而触发保存序列。

    这里有一个容易混淆的点:Create 之后你在对象页里编辑的是草稿(Draft),此时订单还没有真正落到 ZORDER,也不会登记发件箱;只有点 Save 让草稿激活(draft action Activate)时,才走保存序列、写业务表并登记 bgPF。列表上如果还显示草稿标记,说明链路没走完,不要急着查后台。

  2. 等 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:核对“事务边界”与“延迟投递”

做什么:确认你观察到的是发件箱语义,不是“保存后顺手同步调用了一下”。这一步是阅读 + 对照,不改代码。

怎么做:

  1. 打开 ZBP_R_ORDER000 的 save_modified,确认它只在 create-order000 时登记进程,且没有 COMMIT WORK;

  2. 打开 ZCL_RAP_BGPF_REQUEST_SHIPPING 的 execute,确认里面没有 COMMIT WORK(受控变体由框架负责提交);

  3. 对着下表逐项确认证据:

要证明的结论

在哪里看

本案例的证据

发件箱登记与业务写库同事务

save_modified 源码

登记语句位于 RAP 保存序列的 saver 类中;这里没有独立提交

提交之前不会执行

源码 + 现象

save_for_execution 之后并没有立即调用 execute;发货请求是稍后才出现的

回滚则事件消失

语义(可推理)

保存序列失败 → 登记随之回滚 → 队列里不会留下条目

外部调用不在业务事务里

时间戳

订单与发货请求的 LocalCreatedAt 不同,发货请求更晚

  1. 用自己的话把“为什么订单保存失败时不会产生发货请求,而外部投递失败时订单不会回滚”说一遍。说不清就回看“架构与原理”第 2、3 节。

验证:你能指出上面 4 条各自对应的源码位置或现象,并解释 save_for_execution( ) 与 COMMIT WORK 的分工。

步骤 8:注入失败——把断言加回去

做什么:模拟“外部系统不可用”。最干净的方式就是把 assert 1 = 2. 恢复回去,让后台投递每次执行都失败。

怎么做:

  1. 回到 ZCL_RAP_BGPF_REQUEST_SHIPPING,把 assert 1 = 2. 取消注释(恢复原样),保存并激活。

  2. 回到订单预览页,再新建一张订单:OrderID = SO-1002,其余字段同步骤 6,Save(激活草稿)。

  3. 等 10–30 秒,刷新两个预览页。

验证(本步的关键对照):

注入失败后的预期状态
┌───────────────────────────────┬────────────────────────────────────┐
│ 订单 SO-1002                  │ 发货请求(OrderReference = 该订单)│
├───────────────────────────────┼────────────────────────────────────┤
│ ✅ 保存成功,出现在订单列表    │ ❌ 没有新增记录                     │
│ ✅ 业务数据已提交(刷新仍在)  │ ❌ 外部投递失败                     │
└───────────────────────────────┴────────────────────────────────────┘
结论:外部调用失败没有回滚业务数据 —— 这正是发件箱要保证的行为。

也可以换其他失败方式(任选,效果等价,但推荐用仓库自带的断言):

注入方式

做法

适用

断言失败(推荐)

保留 assert 1 = 2.

不依赖外部环境,最稳定

抛异常

在 execute 开头 RAISE EXCEPTION NEW cx_...(或 ASSERT 其他条件)

想验证“异常被 bgPF 捕获并标记错误”

外部不可达

把 EML 换成 HTTP 调用并配一个错误 URL

练习真实外部集成时

卡点:刷新后发现订单也没保存 → 说明你误改了业务代码或保存失败,回滚看 Problem 视图;如果订单保存成功但发货请求也出现了,说明 assert 没生效(没激活,或注释没删干净)。

步骤 9:确认事件没丢,观察失败状态与重试

做什么:验证失败的事件仍被持久化在后台队列里,并且可以被重启(重试)。

怎么做:

  1. 打开后台处理/bgRFC 监控(入口见“架构与原理”第 3 节;云环境是 Fiori 监控类应用,本地常见是 bgRFC 监控器)。

  2. 按进程名 Request shipping、时间范围(最近 15 分钟)、状态(错误)筛选,找到刚才的失败单元。

  3. 打开单元详情,查看状态、尝试次数、出错时间与错误信息。应能看到断言失败(ASSERTION_FAILED / 运行时错误)以及调用栈停在 ZCL_RAP_BGPF_REQUEST_SHIPPING~EXECUTE。

  4. 对该单元执行 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. 重启失败单元

  1. 打开 ZCL_RAP_BGPF_REQUEST_SHIPPING,再次注释/删除 assert 1 = 2.,保存并激活;

  2. 回到监控,对步骤 9 里的失败单元点 Restart;

  3. 等几秒刷新发货请求预览。

B. 触发新事件

新建订单 SO-1003 并保存,等后台执行。

怎么选:有监控权限、想证明“失败的事件仍能原样重放” → 走 A;没有监控权限、只想验证新事件能通 → 走 B。A 的证据更强(同一个单元从错误变成功),B 更省事。

验证:

路线

预期现象

A(重启旧单元)

发货请求列表出现 SO-1002 对应记录;监控里该单元变为成功

B(新事件)

新订单 SO-1003 对应的发货请求出现;旧失败单元仍在监控里(可再重启)

两条路线共同点

ShippingStatus = Ordered、EstimatedDeliveryDate = 今天 + 14 天;订单与发货请求一一对应,订单没有因之前的失败丢数据

一致性核对:任选一种方式确认“订单 ↔ 发货请求”确实对得上:

  1. 在订单预览里复制订单的 UUID,到发货请求列表按 OrderReference 过滤,应该恰好一条;

  2. 在发货请求的对象页里通过 _Order 关联跳回订单,确认是同一条订单;

  3. 在 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”“为什么需要幂等”

清理

  1. 清测试数据:在两个预览里删除 SO-1001/1002/1003 及对应发货请求(列表选中 → Delete;如有草稿,先用 Discard 丢弃)。删除是物理删除,做之前确认不是共享系统。

  2. 清理监控里的失败单元:步骤 9 留下的失败单元在监控里删除,避免它反复告警或阻塞同队列后续单元。

  3. 停用/删除服务绑定:只是本地练习可以保留;如需还原,先 Unpublish 再删除绑定(服务定义、CDS 视图可保留)。

  4. 删除仓库对象:在 abapGit Repositories 视图里右键仓库 → Unlink 解绑(只解除关联,不删对象);确认不再需要后,再在 Project Explorer 里删除包 ZRAP_BGPF 及其内容(删除包时勾选删除其中对象)。注意:如果同一系统有其他人引用这些 Z* 对象,先确认再删。

  5. 回收资源:如果在 BTP 试用/临时租户里练习,结束后按管理员流程清理不用的子账户/服务实例;不要长期保留无人值守的后台失败任务。


常见问题

#

现象

原因

处理

1

保存订单后,发货请求始终不出现

仓库原样带 assert 1 = 2.,后台进程必然失败

打开 ZCL_RAP_BGPF_REQUEST_SHIPPING,注释/删除该行,保存并激活;确认后台失败单元已重启

2

订单保存了,但后台没有登记记录

只保存了草稿,没有触发激活(保存序列只在激活/最终保存时执行)

在 Fiori 里点 Save(激活草稿);到订单列表确认记录不是 Draft 状态

3

更新/删除订单不会产生发货请求

save_modified 里只处理 create-order000

按需在保存序列里增加 update/delete 分支(先想清楚事件语义:是“订单变更事件”还是“下单事件”)

4

拉取仓库报“包不存在/没有权限”

abapGit 需要按 FOLDER_LOGIC=FULL 创建子包,或你没有父包/软件组件权限

手动创建子包 ZFEL_RAP_BGPF_SHIPPING(放在你克隆用的包下)后重新 Pull;或换一个有权限的父包/软件组件

5

代码里找不到 cl_bgmc_process_factory / if_bgmc_op_single

系统不是 ABAP Cloud,或本地版本低于 S/4HANA 2023、或 bgPF 未配置

换 ABAP Cloud 环境(BTP ABAP Environment);本地环境请管理员确认版本与配置;注意别把受控 if_bgmc_op_single 和非受控 if_bgmc_op_single_tx_uncontr 混用

6

后台进程失败,但找不到监控入口

云/本地监控入口和权限不同

找管理员确认后台处理/bgRFC 监控的 Fiori 应用或事务码及权限;没有监控权限时,用“订单在、发货请求不在”作为主证据,并在修复后验证成功

7

重启失败单元后仍然失败

断言/异常代码还在;或旧单元里序列化的数据结构已与当前类不兼容

确认修复已激活、代码是新版本;若改过操作类结构,删除旧单元,用新订单验证

8

发货请求出现两条(或更多)重复记录

至少一次投递:重复登记或重试会重复执行;示例没有幂等

这是预期语义;按 OrderReference 做存在性检查或加唯一约束(练习 C),消费端按业务键幂等

9

预览页打不开 / 没有 Fiori 元素界面

服务绑定未激活或未发布;用户缺服务权限;ADT/浏览器弹窗拦截

重新激活并发布服务绑定,检查绑定 Published 状态;换浏览器或允许弹窗

10

改了 package.devc.xml 或删了文件后 Pull 冲突

本地修改与远端冲突

abapGit 拉取前先确保没有本地未提交修改;练习时尽量只改 ZCL_RAP_BGPF_REQUEST_SHIPPING 这类可回退的对象


官方原文(参考)

本教程与原版的关系:官方仓库以源码作为参考实现,README 只提供环境要求、安装入口与许可信息,没有逐步截图和操作说明。本篇按“对象地图 → 调用链 → 逐步操作 → 失败实验 → 验收清理”的路径,把仓库源码逐行还原成可离线照做的教程;文中所有对象名、代码、字段均取自仓库 main 分支(提交 8cd3f64)的实际内容,未编造 SAP 标准对象。仓库代码版权归 SAP SE,遵循 Apache-2.0 许可。