09 · 公司开发规范与六大模式(需求进来先对照本卡)
0. 30 秒决策:这个需求该用哪个模式?
改标准流程/校验? ── 有 released 扩展点 ──→ F 标准增强(简单逻辑也可门① Custom Logic)
读数据出报表? ── 简单清单 ──→ 门① Analytical Query / Custom CDS
复杂(分桶/多源拼装/参数联动/算价)──→ B 查询报表
新建业务对象? ── 轻量维护 ──→ 门① CBO
正式维护 App(草稿/按钮/权限/传输)──→ A 维护类应用
把数据推出 SAP? ── 新接口 ──→ C 出站接口(优先通信场景版)
定时/批量 ──→ E 定时任务(内部再调 C)
被外部调用/过账? ──→ D 入站/编排(HTTP Service、EML、金税)
口诀:A 管页面、B 管报表、C 管出去、D 管进来、E 管定时、F 管增强。一个需求通常是一个主模式 + 若干辅助模式,先定主模式再拆对象。
1. 六大模式总卡
模式 |
形态 |
对象链(从底到顶) |
工作量量级 |
抄谁 |
|---|---|---|---|---|
A 维护类应用 |
带草稿的表格维护 Fiori App |
表→ |
2–5 天/应用 |
|
B 查询报表 |
只读列表+按钮(发 WMS/导 Excel) |
custom entity→投影 BDEF(unmanaged)→ |
1–3 天/报表 |
|
C 出站接口 |
推外部/回环调标准 API |
|
1–2 天/接口 |
|
D 入站/编排 |
被外部调或调标准 BO |
HTTP Service / 自建 OData / RFM;凭证走 EML |
1–3 天/接口 |
|
E 定时任务 |
Application Job 增量推送 |
|
0.5–1 天/作业 |
|
F 标准增强 |
BAdI 实现类 |
扩展点(enho)→实现类(只实现 released) |
0.5–2 天/增强 |
|
2. 模式 A:维护类应用(最高频,标准样板)
对象链(按此顺序建,缺一不可):
# |
对象 |
命名示例 |
验收 |
|---|---|---|---|
1 |
数据库表 + 草稿表( |
|
表激活、字段与草稿表同步 |
2 |
CDS 根视图( |
|
Data Preview 有数、关联正确 |
3 |
CDS 消费视图 |
|
|
4 |
BDEF(managed + |
|
|
5 |
行为池 |
|
determination/validation/action 全部实现 |
6 |
Service Definition/Binding(O4) |
|
Publish 成功、Preview 能增删改/草稿 |
7 |
IAM App / Catalog / Role |
见 08 章 |
业务用户(非开发者)能打开并保存 |
关键约定(与 04 章示例的差异):
公司维护类 App 必须带草稿(
with draft)和smbc(Fiori Elements 表格维护配置),否则业务用户不接受;编号用
early numbering(创建时即显示单号,PP 包注释原话"这样主键值就会在BO创建前显示");草稿表结构 = 业务表 + 草稿管理字段,必须手建,且与业务表字段同步(漏字段 = 激活报错);
验收必须用业务用户在 Fiori 里走一遍增删改 + 草稿 Activate/Discard,不能只看 Preview。
3. 模式 B:查询报表(custom entity + 三件套)
对象链:
# |
对象 |
命名 |
要点 |
|---|---|---|---|
1 |
custom entity( |
|
|
2 |
实现类( |
|
抄 |
3 |
投影 BDEF(unmanaged,readonly + 业务 action) |
|
按钮动作在行为池实现 |
4 |
Service Definition/Binding(O4) |
|
发布后 Preview 验证筛选/排序/分页 |
5 |
IAM 链 |
见 08 章 |
— |
实现类骨架(从 zzcl_query_mm004 提炼):
METHOD if_rap_query_provider~select.
" 1) 取请求:paging / filter / sort / requested elements / parameters
DATA(lv_top) = io_request->get_paging( )->get_page_size( ).
DATA(lv_skip) = io_request->get_paging( )->get_offset( ).
DATA(lt_filter) = io_request->get_filter( )->get_as_ranges( ).
DATA(lt_sort) = io_request->get_sort_elements( ).
" 2) 取数(只碰 released I_* 与自表 ZZT_*)
SELECT ... FROM i_materialstock_2
WHERE ... INTO TABLE @DATA(lt_data).
" 3) 业务计算(账龄分桶、价格、金额…)
" 4) 统一处理排序/分页(勿自己手写 OFFSET 逻辑)
zzcl_query_utils=>apply_sorting( EXPORTING it_sort = lt_sort CHANGING ct_data = lt_data ).
zzcl_query_utils=>apply_paging( EXPORTING iv_top = lv_top iv_skip = lv_skip CHANGING ct_data = lt_data ).
" 5) 回填
io_response->set_total_number_of_records( lines( lt_data ) ).
io_response->set_data( lt_data ).
ENDMETHOD.
⚠️ 不要自己写
OFFSET/UP TO拼字符串;分页交给三件套。筛选值必须从get_filter( )解析,不要假设前端一定传值。
4. 模式 C:出站接口(配置表 + CSRF + 结果表)
对象链:领号 → REQ/RESP 结构(ZZS_<模块>I<NNN>_REQ/RESP)→ FM 壳(ZZFM_API_xNN)→ 实现(ZZFM_PUB_xNN)→ ZZT_REST_SYSID 配目标系统 → ZZS_REST_OUT 回消息 → 结果表落库(补推/审计)。
实现要点(从 zzfm_pub_sdtodn 提炼,完整代码见 05 章):
" 1) 读目标系统配置(不要硬编码 URL)
SELECT SINGLE * FROM zzt_rest_sysid
WHERE zztsysid = @self_sysid
INTO @DATA(ls_sys).
" 2) 取 CSRF token(回环调用 S/4 自己要带 x-csrf-token)
lo_http_client = cl_web_http_client_manager=>create_by_http_destination( ... ).
lo_http_client->get_http_request( )->set_header_fields( VALUE #( ( name = 'x-csrf-token' value = 'Fetch' ) ) ).
lo_response = lo_http_client->execute( if_web_http_client=>get ).
DATA(lv_token) = lo_response->get_header_field( 'x-csrf-token' ).
" 3) /ui2/cl_json 序列化(name_mappings 集中维护,禁止手拼 JSON)
lv_json = /ui2/cl_json=>serialize( data = ls_req pretty_name = /ui2/cl_json=>pretty_mode-camel_case
name_mappings = lt_name_mapping ).
" 4) POST → 解析 → 落结果表 → 返回 ZZS_REST_OUT(msgty/msgtx/uuid)
易错点:URL 带 https:// 直接填 Hostname(要去协议头);CSRF cookie 忘了带;name_mappings 与结构字段漂移;失败不落结果表导致"不知道哪条没推成功"。
5. 模式 D:入站/编排(HTTP Service、EML、金税)
场景 |
做法 |
命名 |
验收 |
|---|---|---|---|
外部调 SAP(轻量) |
ADT 建 HTTP Service + handler 类 |
|
Postman 用通信用户 Basic 调通 200 + JSON |
外部调 SAP(标准业务) |
通信场景 + 通信安排暴露 released API |
标准 API 名 |
API URL + 通信用户调通 |
SAP 内部过账/改单 |
EML 调 released BO( |
|
单据创建/修改成功、结果表有记录 |
金税/第三方 |
HMAC 签名 + 代理类 |
|
联调环境签名校验通过 |
红线:不直改标准表;过账/改单必须走 BO/API。接口凭证不得写死在代码里,走通信用户/安全参数。
6. 模式 E:定时任务(Application Job)
对象链:ZZCL_JOB_xNN(实现 if_apj_dt_exec_object + if_apj_rt_exec_object)→ Fiori「Application Jobs」建 Job Template(ZAJT_*)→ 排期 → 业务目录授权 → 成功后更新基线表(ZTJOB_LOG 类)。
增量窗口标准写法(修正旧代码的硬编码时区):
" 时间窗口:用用户时区,不写 +8h
DATA(lv_tz) = cl_abap_context_info=>get_user_time_zone( ).
GET TIME STAMP FIELD DATA(lv_end).
SELECT SINGLE FROM ztjob_log
FIELDS * WHERE jobname = @c_jobname
INTO @DATA(ls_log).
IF ls_log IS INITIAL.
" 首次:按业务定义的初始范围
ELSE.
CONVERT DATE ls_log-jobdate TIME ls_log-jobtime
INTO TIME STAMP DATA(lv_start) TIME ZONE lv_tz.
ENDIF.
验收:手动 Schedule 一次 → Instances 成功 → 日志有可读消息 → 基线表更新 → 第二次运行只增量不重复 → 时区/DST 场景不丢数。
7. 模式 F:标准增强(BAdI)
只实现 released BAdI(ADT 里能搜到、语法检查通过才是 released);公有云不提供任意位置增强。
实现类命名
ZCL_<扩展点语义>,一个增强点一个类;逻辑简单优先门① Custom Logic(可运维、无需传输开发对象)。验收:走一遍真实业务触发扩展点 → 断言新逻辑生效 → 回归原逻辑不受影响。
8. 命名规范(四包统一,新增必须遵守)
类型 |
规范 |
例 |
|---|---|---|
表/草稿表 |
|
|
API 结构/表类型 |
|
|
CDS |
|
— |
行为池 |
|
— |
服务 |
定义与绑定 |
|
API/Job/Query 类 |
|
— |
函数组/模块 |
|
|
编号对象 |
模块语义名( |
— |
IAM |
|
— |
Key User 产物 |
系统自动 |
— |
模块编号即"接口台账":同编号贯穿 结构/表/FM/类/服务(如 MM005 = 外向交货单推送全家桶)。新接口先领号再建对象。
9. 通用实现规约(代码库提炼,评审逐条打勾)
JSON 一律
/ui2/cl_json+ name_mappings(ABAP 蛇形 ↔ JSON 驼峰);映射表集中维护在 FM 头部。返回消息统一
ZZS_REST_OUT(msgty/msgtx/uuid),接口结果必落结果表供补推与审计。数据读取只碰 released CDS(
I_*)与自表ZZT_*;未发布对象语法即红。写自定义表走 RAP/EML 或 FM 内 MODIFY;修改标准单据一律调 API/EML,不直改标准表。
锁:跨系统幂等用 SD 的
ZZFM_LOCK_DATA/UNLOCK_DATA(表ZZT_CUST_LOCK)模式。时区:新代码用
cl_abap_context_info=>get_user_time_zone( );禁抄旧 Job 的 +8h 硬编码。BAdI 只实现 released 扩展点;实现类命名
ZCL_<扩展点名语义>。代理对象(zzfi001 目录)与 sush 记录禁止手改;IAM 变更走 Fiori 应用。
每个对象必须挂传输请求;gCTS 提交前"激活 + ATC 检查"。
错误信息:技术异常进日志(
APPL_LOG),业务错误用REPORTED/返回消息给前端,不向用户抛原始异常文本。
10. 代码评审清单(提 PR / 交接前自查)
检查项 |
判据 |
|---|---|
对象命名/编号符合第 8 节 |
一眼能看出模块与用途 |
无 |
ATC 无 error、代码评审通过 |
无硬编码 URL/密码/时区 |
配置表/通信用户/ |
接口有结果表 + 可补推 |
失败记录能查到并重推 |
错误消息可读(中文/业务语言) |
前端能看到 msgty/msgtx |
权限:DCL + BDEF authorization master |
业务用户访问符合预期 |
传输请求对象清单干净、描述含工单号 |
Release 前核对 |
文档:05/06/07 对应章节的写法能对上 |
— |
11. 已知风险与债务(改动前必读)
# |
事项 |
影响 |
动作 |
|---|---|---|---|
1 |
PP 包导出缺全部 |
PP 二开无参考源码 |
向顾问索要完整导出 |
2 |
公共包未导出: |
动出站配置/Job 前拿不到定义 |
同上 |
3 |
|
安全审计 |
新接口走通信安排;存量登记台账逐步迁移 |
4 |
Job 时区硬编码 + 基线时机 |
增量漏数风险 |
新 Job 按 06 章改进 |
5 |
name_mappings 手写漂移 |
字段变更易漏 |
改接口时 diff 映射表 |
6 |
行为池类缺失导致 BDEF 无法激活 |
无法交付 |
用 abapGit 拉完整包再改 |
12. 与环境相关的三条铁律
连接审批制:任何对 GQN 生产/开发租户的连接(哪怕测试)先经负责人;
开发只在 D 租户,练习自建包,不碰他人对象;
传输:D→TEST→PROD 走 gCTS,勿本地发布越级。