07 · SAP Cloud SDK for JavaScript:从 BTP 调 S/4HANA 完整教程

目标:用 Cloud SDK 打通一条 BTP → S/4HANA 的 OData 调用,理解 Destination、认证、重试/分页。 预计:2–3 小时 | 难度:中 | 前置课程:CLD200、BAS400、C4H45B

你会做出什么

跟着本教程走完,你会得到一个能本地运行、也能部署到 SAP BTP Cloud Foundry 的 Node.js/TypeScript 应用,并且亲手把下面这条链路跑通一次:

Cloud Foundry 应用 → XSUAA(令牌)→ Destination 服务(按名取目标)→ HTTP/OData → S/4HANA(或本地 mock)

具体交付物如下:

交付物

验收标志

一份官方示例代码

从 SAP-samples/cloud-sdk-js 稀疏检出主示例 samples/cds-sample-application

一个可用的 Destination

BTP Cockpit 里 Check Connection 通过,应用代码只用 Destination 名称、不出现账号密码

一段可复用的调用代码

类型安全 OData 客户端 + 分页 + 错误分类日志 + 超时/重试/熔断中间件

一个本地可运行的应用

npm run start:dev 启动成功,验证脚本能打印出业务伙伴列表

一个云端可验证的应用

cf app 显示 1/1 running,cf logs --recent 能看到 OData 调用的 200 记录

一份可回收的资源清单

「验收与清理」一节给出 cf delete / cf delete-service / 删除 Destination 的完整清理命令

跑通后,控制台里最有代表性的一段输出是这样的(字段以你系统实际返回为准):

{
  "d": {
    "results": [
      { "BusinessPartner": "1000000", "FirstName": "Peter", "LastName": "Pan" },
      { "BusinessPartner": "1000001", "FirstName": "Alice", "LastName": "Smith" }
    ]
  }
}

SAP Cloud SDK for JavaScript 示例项目标识

图:本教程主线代码来自 SAP Cloud SDK for JavaScript 官方示例项目(Sample Projects),图中标识即示例仓的封面。

说明:本案例的原始资料是一份示例集 README(示例清单 + 命令),几乎没有操作截图。因此本教程以「文字 + 完整代码 + 表格」为主,本案例仓库仅 2 张真实图片;另配 6 张 SAP 官方课程同类界面截图作示意(图注注明非本案例截图,界面以你的系统实际版本为准);凡是需要看界面的地方,都写清菜单路径和字段值。

架构与原理

Cloud SDK 到底替你做了什么

SAP Cloud SDK for JavaScript 是 SAP 官方维护的一组 Node.js/TypeScript 库。它不负责业务逻辑,而是把「在 BTP 上访问后端服务」时反复出现的脏活封装掉:

  • 按名字查找 Destination(目标),而不是在代码里写死 URL;

  • 自动向 XSUAA 换取令牌,再向 Destination 服务出示令牌;

  • 按 Destination 里配置的认证方式(Basic、OAuth2、PrincipalPropagation 等)自动加认证头;

  • 目标在本地(on-premise)时,自动经 Connectivity 服务 + Cloud Connector 转发;

  • 根据 EDMX/OpenAPI 规格生成类型安全客户端,自动拼 OData 查询、序列化/反序列化;

  • 提供韧性中间件(超时、重试、熔断)、错误根因包装、CSRF token、日志等。

一句话:业务代码只保留「调哪个服务、查什么、怎么处理结果」,其余交给 SDK。

对比项

手写 axios/fetch

用 Cloud SDK

目标地址

写死在代码或环境变量里

按 Destination 名称解析,可随环境切换

认证

自己拼 Basic/OAuth/令牌刷新

按 Destination 配置自动处理

on-premise

自己对接 Cloud Connector 代理

配置好 connectivity 后透明转发

类型安全

自己维护接口类型

从 EDMX 生成实体与请求构造器

韧性

自己写重试/超时/熔断

一行 resilience() 中间件

多租户

自己解析 JWT 里的租户

传 jwt 即可按租户取 Destination

核心包与分工

npm 包

作用

本教程用在哪

@sap-cloud-sdk/connectivity

Destination/XSUAA/Connectivity/服务绑定的读取与转换

理解“目标从哪来”;registerDestination、服务绑定解析

@sap-cloud-sdk/http-client

通用 HTTP 客户端 executeHttpRequest,自动带 Destination 能力

步骤 8 的最小验证脚本

@sap-cloud-sdk/odata-v2 / @sap-cloud-sdk/odata-v4

OData V2/V4 运行时基础库(实体、序列化、请求构造基类)

生成客户端时的运行时依赖

@sap-cloud-sdk/generator

读 EDMX 生成 TypeScript 客户端(CLI:generate-odata-client)

步骤 7 生成业务伙伴客户端

@sap-cloud-sdk/resilience

resilience() / timeout() / retry() / circuitBreaker()

步骤 11 加超时与重试

@sap-cloud-sdk/openapi / openapi-generator

同理,面向 OpenAPI 服务

本教程不展开

一次调用的完整链路

以「应用在 Cloud Foundry 上,经 Destination 调用 S/4HANA 的 Business Partner API」为例:

  1. 应用启动,环境变量 VCAP_SERVICES 里已经有 destination、xsuaa 两个服务绑定(由 manifest.yml 自动绑定)。

  2. 业务代码执行 businessPartnerApi.requestBuilder().getAll().execute({ destinationName: 'S4HANA_BUSINESS_PARTNER' })。

  3. SDK 向 XSUAA 用服务绑定的 client id/secret 换一个 access token。

  4. SDK 拿 token 调 Destination 服务,请求名为 S4HANA_BUSINESS_PARTNER 的目标配置(URL、认证方式、附加属性)。

  5. Destination 服务返回解析好的目标;SDK 按认证方式准备请求头(Basic 直接加,OAuth2 再换目标系统令牌)。

  6. SDK 拼接 URL:目标 URL + 服务路径(如 /sap/opu/odata/sap/API_BUSINESS_PARTNER)+ 实体集与查询参数,发出请求。

  7. 若目标是公网 S/4HANA,直连;若目标是内网 on-premise,请求经 Connectivity 服务、Cloud Connector 到达后端。

  8. 响应被反序列化成实体数组返回;异常被包装成带 cause / rootCause 的错误,供你分类处理。

Destination 服务在一次调用中的角色:用户操作业务应用,应用不直连远端系统,而是先按名称向 Destination 服务换取连接信息(URL、认证方式等),再用这份信息访问远端 Web 资源;Cloud SDK 替你做的就是第 2~4 步(SAP 官方课程 BTP200 截图,非本案例截图)

组件

职责

出问题时通常表现为

XSUAA

给应用签发访问 Destination 服务的令牌

401/403,日志提示取不到 token

Destination 服务

保存并下发目标配置

Destination with name ... not found

Connectivity 服务

为 on-premise 目标建立到 Cloud Connector 的隧道

云端超时、502/504,本地却正常

Cloud Connector

部署在客户网络,把内网系统映射给 BTP

云端 404/连接被拒;Check Connection 失败

S/4HANA 通信安排

定义通信用户、启用的 OData 服务与认证方式

401(认证失败)/403(权限不足)

Destination、XSUAA、服务绑定是什么关系

  • Destination(目标):一条“怎么访问某个系统”的配置,包含 URL、Proxy Type(Internet / OnPremise)、认证方式、用户/密码或 OAuth 客户端、附加属性(如 sap-client)。它保存在 BTP 的 Destination 服务里,应用运行时按名读取。

  • XSUAA:BTP 的授权与信任管理服务。应用必须先有 XSUAA 绑定,SDK 才能取到访问 Destination 服务的令牌。

  • 服务绑定(Service Binding):把服务实例“挂”到应用上,凭据通过环境变量 VCAP_SERVICES 注入。manifest.yml 的 services: 列表让 cf push 在部署时自动完成绑定。

SDK 查找 Destination 的顺序(命中即停止):

  1. 进程的环境变量 destinations(本地开发时最方便,不要用于生产);

  2. 代码里用 registerDestination() 注册的目标;

  3. 服务绑定环境变量(VCAP_SERVICES);

  4. BTP Destination 服务(生产环境的主要来源)。

理解这个顺序很重要:本地能跑、云端找不到目标,十有八九是第 4 步没配好或服务实例没绑定。

Destination 的认证方式怎么选

场景

Proxy Type

Authentication

说明

公网可达的 S/4HANA Cloud

Internet

BasicAuthentication

最简单,用通信用户账号密码;教程主线用这个

公网可达的 S/4HANA Cloud

Internet

OAuth2ClientCredentials

通信安排里创建 OAuth 2.0 客户端,Destination 填 Token Service URL、Client ID/Secret

内网 S/4HANA(on-premise)

OnPremise

BasicAuthentication

必须创建 connectivity 服务实例 + 配好 Cloud Connector

需要把登录用户身份传到后端

OnPremise

PrincipalPropagation

还要求 Cloud Connector 开启主体传播、后端信任配置;比 Basic 复杂

本地 mock / 沙箱演练

Internet

NoAuthentication

无认证最省事,仅供联调

安全底线:URL、用户名、密码、Client Secret 一律不写进代码和 Git。用 Destination、服务绑定或环境变量注入;本教程所有代码都只引用 Destination 名称。

OData V2 与 V4 的差异

SDK 对两个版本都提供类型安全客户端,日常写法几乎一样,差别集中在“协议细节 + 生成器用哪个包”:

对比项

OData V2

OData V4

典型后端

S/4HANA 大量标准 API,如 Business Partner(API_BUSINESS_PARTNER)

CAP 服务、部分云服务/新 API

元数据

$metadata 返回 EDMX

同样 $metadata,但模型版本为 V4

运行时包

@sap-cloud-sdk/odata-v2

@sap-cloud-sdk/odata-v4

服务路径

常见 /sap/opu/odata/sap/<SERVICE>

常见 /odata/v4/<service>(CAP)或后端实际路径

集合返回

JSON 里常见 { "d": { "results": [...] } }

JSON 里常见 { "value": [...] }

分页

$top / $skip(S/4HANA 还可能用 $skiptoken)

$top / $skip / @odata.nextLink

生成器

generate-odata-client 同一 CLI,按 EDMX 自动选包

同上

本教程主线用 V2 的 Business Partner 演示;步骤 12 会给出 V4 的差异写法和验证要点。

部署形态:Cloud Foundry 与 Kubernetes

本教程主线部署到 Cloud Foundry(BTP 试用账户即可)。示例仓里还有 Kubernetes/Helm 形态(需要 SAP BTP Operator、Connectivity Proxy 等),其架构如下图:应用 Pod 读取 XSUAA / Destination / Connectivity 三个服务绑定(Secret),云端目标直连,本地目标经 Connectivity Proxy + Cloud Connector 到达;服务实例本身由 SAP BTP Operator 在 CF 中创建再同步到集群。

SAP Cloud SDK 示例应用在 Kubernetes 上的架构与依赖组件

图:Kubernetes/Helm 形态下 SDK 应用的组件关系(来自官方示例仓的架构图)。本教程只走 CF 主线;这张图用于理解「服务绑定 → 目标/认证/连通性」在另一种运行环境里的对应物。

准备工作

本机环境

工具

建议版本

检查命令

说明

Node.js

22 LTS(最低 22)

node -v

Cloud SDK v4 要求 Node 22+;若示例仓锁定 v3,可用 18/20,以 package.json 的 engines 为准

npm

随 Node 附带(10+)

npm -v

用于安装依赖、跑脚本

Git

2.30+

git --version

稀疏检出示例仓

Cloud Foundry CLI

8.x

cf -v

登录、创建服务实例、部署、看日志

编辑器/IDE

任意

—

VS Code 等,能装 TypeScript 插件更好

curl / jq

可选

curl --version

验证 OData 与 CF 路由

node -v      # 期望 v22.x 或更高
npm -v
git --version
cf -v
curl --version | head -n 1

cf CLI 登录示意:上方是 BTP Cockpit 子账户的 Cloud Foundry Environment 页(API Endpoint 从这里复制),下方在本机执行 cf login --sso,按提示用浏览器取一次性验证码完成登录;本教程步骤 6 的 cf api、cf login、cf target 三条命令就是这套流程,org/space 换成你自己的即可(SAP 官方课程 BTP200 截图,非本案例截图)

注意:原始示例仓 README 里写的 “node 14 / npm 6” 是多年前的历史最低要求,不要照抄。SDK v4 的最低 Node 版本是 22,Node 版本过低会在 npm install 或运行时报 EBADENGINE、语法错误或 structuredClone is not defined 一类问题。

BTP 与 S/4HANA 侧准备

资源

用途

是否必需

BTP 子账户 + Cloud Foundry 空间

部署应用、创建服务实例

必需

Application Runtime 配额

运行应用,建议 ≥1 GB 内存

必需

Destination 服务实例

保存并下发目标配置

必需(计划 lite 即可)

XSUAA 实例

应用访问 Destination 服务的令牌

必需(计划 application)

Connectivity 服务实例

仅 on-premise 目标需要

按场景

Cloud Connector

仅 on-premise 目标需要,部署在客户内网

按场景

S/4HANA 系统 + 通信用户/通信安排

提供 OData 服务

必需(可用 mock/沙箱替代)

业务伙伴读权限

通信用户能读取 API_BUSINESS_PARTNER

必需

没有 S/4HANA 系统也能练:官方入门教程提供了本地 mock OData 服务(模拟 Business Partner V2 服务,跑在 http://localhost:3000),也可以用 SAP Business Accelerator Hub 的沙箱(需要 API Key,通过请求头 APIKey 传)。本教程在“步骤 4”给出 mock 分支说明,主线仍按真实系统的写法讲。

开始前的检查清单

  • node -v、npm -v、git --version、cf -v 四条命令都能输出版本号。

  • 已能登录 BTP Cockpit,并确认目标子账户里 Cloud Foundry 环境已启用。

  • 已确认 cf login 能进入目标 org/space(或知道要用的 cf api 地址)。

  • 有一个可访问的 S/4HANA 系统与通信用户,或已准备好本地 mock 服务。

  • 知道目标系统的 OData 服务路径(如 /sap/opu/odata/sap/API_BUSINESS_PARTNER)。

  • 本机磁盘有 ≥1 GB 可用空间(示例仓 + node_modules)。

  • 明白验证顺序:先生成客户端 → 再用最小脚本验证 Destination → 最后跑完整应用,不要一上来就 cf push。

操作步骤

这 16 步按“先打通、再写代码、最后上云”的顺序组织,前一步的验证不通过就不要进下一步。整体路线:

阶段

步骤

完成后你拥有的东西

准备

1–3

工具链就绪,示例代码已在本地,知道每个目录/脚本干什么

打通后端

4–5

S/4HANA 通信安排 Active,BTP 里 Destination 的 Check Connection 通过

打通平台

6–7

destination/xsuaa(可选 connectivity)实例已创建并绑定,OData 客户端已生成

写调用代码

8–12

最小 HTTP 调用、类型安全查询与分页、错误分类、韧性中间件、V4 差异

运行与上线

13–16

本地跑通、部署到 CF、云端验证、可选多端点与主体传播

步骤 1:校验并准备本地工具链

做什么:先保证 Node/npm/Git/cf CLI 四件套可用,避免后面把“环境问题”误判成“代码问题”。

node -v
npm -v
git --version
cf -v

如果 Node 不是 22.x,用 nvm 之类的版本管理器切换(命令以你本机安装方式为准):

nvm install 22
nvm use 22
node -v          # 应显示 v22.x

验证:四条命令都输出版本号;node -v 主版本 ≥ 22(或与示例仓 engines 要求一致)。后续如遇 npm ERR! engine 报错,回到这一步处理。

顺手准备一张“命名小抄”,后面会反复用到,写错一个字符都要折腾半天:

变量

本教程示例值

用在哪

应用名

cloud-sdk-js-demo

cf push / cf app / cf logs

Destination 名

S4HANA_BUSINESS_PARTNER

代码、destinations 环境变量

Destination 实例

destination-service

manifest.yml、cf create-service

XSUAA 实例

xsuaa-service

同上

本地端口

8080(mock 用 3000)

curl、PORT 环境变量

另外,nvm 切换的是 Node 版本,不影响 cf CLI;切换 Node 后如果终端还显示旧版本,重开一个终端再试。cf CLI 只用于部署和运维,与 Node 版本无关。

建议现在就把上表的名称写进一个临时记事本:代码、CF 命令、Destination 配置三处必须逐字一致,后面每遇到“找不到/未授权”,先回来核对这张表。

步骤 2:拉取示例仓库(只取需要的那一个示例)

做什么:官方示例仓有多个示例,全量克隆较大。用 git sparse-checkout 只拉主线示例 samples/cds-sample-application,省时省流量。

git clone \
  --depth 1 \
  --filter=blob:none \
  --sparse \
  https://github.com/SAP-samples/cloud-sdk-js.git
cd cloud-sdk-js
git sparse-checkout set samples/cds-sample-application

三条参数各管一件事:--depth 1 只取最近一次提交(不拉历史,快);--filter=blob:none 先不下文件内容、按需再取;--sparse 允许只检出部分目录。git sparse-checkout set 才真正把示例目录写进工作区,所以这几条命令要按顺序执行。如果所在网络对 Git 代理有要求,先把代理配好再执行;拉取失败时不要反复重试,先看报错里的主机名与证书提示。后面想再加别的示例时不用重新 clone,在仓库根目录执行 git sparse-checkout add <示例目录> 即可增量检出。

不想用稀疏检出时,用浅克隆代替(体积更大,但行为直观):

git clone --depth 1 https://github.com/SAP-samples/cloud-sdk-js.git

怎么选示例:不同示例对应不同目标,先对照下表选,再执行对应 git sparse-checkout set ...。

示例目录

适合谁

特点

samples/cds-sample-application

本教程主线

CAP + Cloud SDK,含 srv/、db/、src/、manifest.yml,本地与 CF 两条命令链齐全

samples/cf-sample-application

想一次看全 4 种调用端点

云端、on-premise、主体传播多端点 + approuter,需 destination/xsuaa/connectivity 三个实例

samples/cf-multi-tenant-application

想做多租户 SaaS

配套多租户教程,含 approuter 与 service-config,部署前需替换 YOUR_* 占位符

samples/http-client-examples

只想看 HTTP Client 用法

npm ci 后 npm run test,本地起 express 服务演示请求

samples/resilience-examples

想定制韧性中间件

resilience.ts 自定义中间件 + 对应 spec 演示

samples/k8s-sample-application、samples/helm-sample-application

想部署到 Kubernetes

需要集群、SAP BTP Operator、Connectivity Proxy;本教程不展开

验证:进入示例目录能看到关键文件:

cd samples/cds-sample-application
ls -1
# 期望看到(顺序不限):
# README.md  package.json  manifest.yml  srv/  db/  src/  resources/

顺手确认稀疏检出的范围:

git sparse-checkout list
# 期望输出:samples/cds-sample-application

若 srv/、db/、manifest.yml 缺失,说明稀疏检出的路径写错了,重新执行 git sparse-checkout set samples/cds-sample-application;如果连 samples/ 目录都没有,检查当前目录是不是 cloud-sdk-js 仓库根目录(pwd 应显示 .../cloud-sdk-js)。

步骤 3:认识工程结构与关键脚本

做什么:在装依赖前先看懂“项目怎么组织、命令各自干什么”,后面每一步都知道自己在动哪个文件。

示例 README 给出的仓库结构:

  • src/:应用源代码与 CAP 服务处理器(service handler)实现;

  • srv/:CDS 服务定义与实现;

  • db/:CDS 领域模型与数据库相关内容;

  • manifest.yml:部署到 SAP BTP Cloud Foundry 的部署描述符;

  • resources/service-specs/:按 EDMX 格式保存的服务定义(Business Partner cloud 版本);

  • package.json:依赖与脚本。

把这几层对应起来看:db/ 定义持久化模型,srv/ 定义对外服务并把服务实现挂上去,src/ 放调用 Cloud SDK 的业务代码(示例里是 CAP 服务处理器),resources/ 只是生成客户端用的“输入文件”,不参与运行时。先打开 manifest.yml 记下三件事:应用名(后面所有 cf 命令都用它)、services: 列表(必须与将要创建的服务实例名逐字一致)、command(必须与 package.json 里的脚本名对得上,常见是 npm run start:prod)。

manifest.yml 里几个字段的含义:path: . 表示上传当前目录,buildpacks 指定 Node buildpack,command 决定容器里的启动命令,services: 在 push 时自动绑定实例(因此实例要先创建)。如果示例仓的 manifest 没写 services,按步骤 6 补上,否则应用启动时读不到 VCAP_SERVICES,SDK 就找不到 Destination。团队多人共用一个 space 时,给 name 加个性前缀,避免路由和应用名撞车。

# 看部署描述符前面几行
sed -n '1,40p' manifest.yml

# 看有哪些服务规格(每个 .edmx 对应一个要生成的客户端)
ls -1 resources/service-specs/

为什么强调 postinstall:npm ci 安装依赖完成后会自动执行 generate-client,所以第一次装依赖可能久一点;如果在离线环境或生成失败,生成目录会是空的,后续 import 会直接报“找不到模块”。遇到这种情况不要改 import 路径,先让生成成功。

关键 npm 脚本(以仓内实际为准,可先用下面命令打印):

node -e "const s=require('./package.json').scripts; for (const [k,v] of Object.entries(s)) console.log(k.padEnd(20), v)"

脚本

作用

什么时候用

generate-client

用 EDMX 生成 OData 客户端

npm i 后的 postinstall 会自动跑一次;改了服务规格后手动重跑

cds-deploy

部署 CDS 模型到本地数据库

首次本地运行前

start:dev

开发模式启动应用(含热重载)

本地调试

ci-build

把 TypeScript 编译为 JavaScript

部署前构建

ci-package

打包部署产物

部署前打包

deploy

串起 ci-build → ci-package → cf push

一键部署到 CF

验证:package.json 里能看到 generate-client、cds-deploy、start:dev、deploy 等脚本;resources/service-specs/ 下有 .edmx(或 .xml)服务规格文件。

许可提醒:示例仓里的 Business Partner 服务定义按 SAP API Information License 授权,仅限开发目的使用;生成出来的客户端代码也受对应服务规格许可约束。

步骤 4:在 S/4HANA 准备通信用户与通信安排

做什么:Destination 最终要访问 S/4HANA 的 OData 服务。S/4HANA 侧必须有一个“允许外部通信”的配置:通信系统 + 通信用户 + 通信安排;否则后面无论 Destination 怎么配,都会 401/403。

以 S/4HANA(Cloud 或较新 on-premise 版本)的 Fiori 通信管理为例:

  1. 打开 Communication Systems(通信系统) 应用,新建一条通信系统:填写系统 ID、主机名(<your-s4-host>)、可选 SAP Client。

  2. 在通信系统里创建 Communication User(通信用户):设置用户名/密码(或客户端证书),并给它分配能读取业务伙伴的业务角色/授权。

  3. 打开 Communication Arrangements(通信安排) 应用,新建通信安排:

    • Scenario 选择业务伙伴相关场景(常见为 SAP_COM_0008,不同版本名称可能是“Business Partner, Customer and Supplier Integration”,以你系统里搜索 Business Partner 出现的场景为准);

    • 选择刚建的通信系统;

    • Inbound 认证方式选 Basic(用户/密码)或 OAuth 2.0(客户端凭据);

    • 勾选/启用 API_BUSINESS_PARTNER 相关服务,记下它显示的服务路径。

  4. 保存并确认通信安排状态为 Active。

认证通过之后还要有授权:以 BTP XSUAA 的授权模型为例,用户 → 角色集合 → 角色 → Scope 逐层展开,scope 才是应用里真正校验的权限;S/4HANA 侧的通信用户同理,必须在通信管理里分配能读业务伙伴的业务角色/授权对象,否则 OData 调用会返回 403(SAP 官方课程 CLD200 截图,非本案例截图)

创建通信系统时常用字段:System ID(如 S4H_CLOUD)、Host Name(只填主机名,不带 https://)、HTTPS Port(默认 443)、SAP Client(如 100)。通信用户建议“一个集成一个用户”命名,并在描述里写清用途与负责人;长期运行的服务间调用优先用证书或 OAuth 客户端,而不是永久密码。

这三件东西的关系:通信系统是“对方系统是谁”,通信用户是“用什么身份访问”,通信安排是“允许哪些服务、用哪种认证”。三者缺一,OData 调用都会在认证或授权阶段失败。认证方式必须与后面 Destination 的选择一致:通信安排用 Basic + 密码,Destination 就选 BasicAuthentication;通信安排用 OAuth 2.0 客户端凭据,Destination 就选 OAuth2ClientCredentials 并填 Token Service URL 与 Client ID/Secret。认证方式混用是最常见的 401 来源。

还要注意:通信用户是技术用户,只用于服务间调用,不要用个人账号的密码,也不要在多个集成间长期复用同一个技术用户(出问题时无法追溯是谁在调用)。

如果通信安排选择 OAuth 2.0:先在通信系统里维护一个 OAuth 2.0 客户端(拿到 Client ID / Client Secret),通信安排把入站认证设为 OAuth 2.0;随后 Destination 端填 Token Service URL 与这对 Client 凭据,不要填用户密码。令牌的获取与到期刷新由 SDK 自动完成,业务代码里不需要手写 token 逻辑(只有 PrincipalPropagation 等需要转发用户 JWT 的场景才要额外处理)。

字段/对象

示例值

说明

通信系统主机名

my-s4.example.com

必须是 BTP 侧可达的地址

通信用户

COMM_USER_BP

只用技术用户,不要用个人账号

认证方式

Basic(用户/密码)

后续 Destination 选 BasicAuthentication

通信场景

SAP_COM_0008

业务伙伴集成;以你系统实际场景编号为准

服务路径

/sap/opu/odata/sap/API_BUSINESS_PARTNER

服务根路径,后面拼实体集

验证(在能访问该系统的网络里执行;不要把你的密码留在 shell 历史里,建议用环境变量或交互输入):

export S4_URL="https://my-s4.example.com"
export S4_USER="COMM_USER_BP"
read -r -s -p "S/4HANA 通信用户密码: " S4_PASSWORD; echo

# 1) 元数据应返回 200 和 XML
curl -s -u "$S4_USER:$S4_PASSWORD" \
  "${S4_URL}/sap/opu/odata/sap/API_BUSINESS_PARTNER/\$metadata" \
  -o /tmp/bp-metadata.xml -w "%{http_code}\n"

# 2) 取一条业务伙伴,应返回 JSON(V2 常见结构为 d.results)
curl -s -u "$S4_USER:$S4_PASSWORD" \
  -H 'Accept: application/json' \
  "${S4_URL}/sap/opu/odata/sap/API_BUSINESS_PARTNER/A_BusinessPartner?\$top=1" \
  -w "\nHTTP %{http_code}\n"

看到 200 且返回 XML/JSON,说明通信用户与通信安排没问题。再核对元数据里的实体集名字,确认要查的集合真的存在:

grep -o 'EntitySet Name="[^"]*"' /tmp/bp-metadata.xml | head -n 5
# 期望看到 A_BusinessPartner 等实体集;HTTP 200 但实体集名不同,说明服务版本/路径不对

没有真实 S/4HANA 时:本步骤跳过,改用本地 mock OData 服务。它启动后监听 http://localhost:3000,模拟 Business Partner V2 服务;此时 Destination(或本地 destinations 环境变量)的 URL 填 http://localhost:3000、Authentication 选 NoAuthentication;服务路径优先按 /sap/opu/odata/sap/API_BUSINESS_PARTNER 尝试,若 mock 项目 README 写的是别的路径,以 mock 为准。其余代码与真实系统完全一致,仍能走完“调用 → 分页 → 错误处理 → 部署”全流程。

用 SAP Business Accelerator Hub 沙箱时:沙箱要求请求头带 API Key。做法是在代码里用 addCustomHeaders({ APIKey: '...' }) 或从环境变量注入,不要把 Key 提交进仓库;Destination 认证选 NoAuthentication。

步骤 5:在 BTP Cockpit 创建 Destination

做什么:把“怎么访问 S/4HANA”从代码里挪到 BTP 的配置里,应用只认名字。这是 Cloud SDK 安全实践的核心一步。

菜单路径:BTP Cockpit → 你的子账户 → Connectivity → Destinations → Create / New Destination。不同 Cockpit 版本按钮可能叫 “Create Destination” 或 “New Destination”,进入编辑页后按下面表格填写;Additional Properties 在页面下方的同名区域逐行添加,保存前不要漏。

BTP Cockpit 的 Create Destination 编辑页:左侧是 Connectivity → Destinations 列表,右侧依次填 Name、Type、Description、Proxy Type、URL、Authentication,Additional Properties 在表单下方同名区域逐条添加;图中示例是 Northwind 目标 + NoAuthentication,本案例要把 Name 填成 S4HANA_BUSINESS_PARTNER、Authentication 选 BasicAuthentication(SAP 官方课程 BTP200 截图,非本案例截图)

字段

示例值

必填/说明

Name

S4HANA_BUSINESS_PARTNER

必填;代码里用的就是这个名字,大小写敏感

Type

HTTP

必填

Description

S/4HANA Business Partner OData (V2)

可选,写清用途

URL

https://my-s4.example.com

必填;只填 scheme + host + port,不要带服务路径

Proxy Type

Internet(公网系统)/ OnPremise(内网经 Cloud Connector)

必填

Authentication

BasicAuthentication

与 S/4HANA 通信安排保持一致

User

COMM_USER_BP

BasicAuthentication 时出现

Password

通信用户密码

只存在 Destination 里,不落代码

Additional Properties

sap-client=100、sap-language=zh

按系统需要;client 号不对会查不到数据

如果选择 OAuth2ClientCredentials,还需要填:

字段

从哪里取

Token Service URL

通信安排的 OAuth 2.0 客户端信息里复制(形如 https://<子域>.authentication.<区域>.hana.ondemand.com/oauth/token,以实际为准)

Client ID / Client Secret

通信安排中创建的 OAuth 2.0 客户端

Token Service User / Password

通常留空或按令牌服务要求填写

填写时的三条硬规则:

  1. URL 只到 host。把 /sap/opu/odata/sap/API_BUSINESS_PARTNER 写进 URL 是最常见的错误,结果就是 404;服务路径应由生成客户端的 basePath 或请求的 url 提供。

  2. Name 一旦定下就不要改。代码、destinations 环境变量、文档全用它;大小写和连字符都算数。

  3. 认证方式与通信安排一一对应。Basic 对应通信用户的用户名/密码;OAuth2 对应 Client ID/Secret;on-premise 的 PrincipalPropagation 还需要 Cloud Connector 开启主体传播、后端配置信任,通常配合 approuter 使用,不属于本教程主线。

选 OnPremise 时,页面还会要求 Location ID(Cloud Connector 的 location 标识),必须与 Cloud Connector 上配置的一致;URL 则填 Cloud Connector 里为该系统配置的“虚拟主机:端口”,而不是内网真实地址。

on-premise 的一条完整示例(按你的环境替换值):Proxy Type = OnPremise,URL = s4-virtual-host:443,Location ID = MY_LOCATION,Authentication = BasicAuthentication,User = COMM_USER_BP,Additional Properties 里加 sap-client=100。其中“虚拟主机”必须已经在 Cloud Connector 的“Cloud To On-Premise → Mapping”里映射到内网主机,否则 Check Connection 一定失败。

验证:保存后点击该 Destination 的 Check Connection。公网系统应显示连接成功/HTTP 200;若是 on-premise,Check Connection 需要 Cloud Connector 已映射好、connectivity 服务正常,否则会报连接失败(这属于连通性问题,先把步骤 4 的网络链路打通)。Check Connection 失败时,先在能访问后端的机器上用浏览器直接打开 Destination 的 URL 确认服务活着,再回来查 BTP 侧配置,不要急着改代码。

注意:Cloud SDK v4 起 Destination 默认启用缓存。改完 Destination 后若应用仍读到旧配置,可用 useCache: false 临时绕过,或等待缓存过期后重试。

步骤 6:创建并绑定服务实例

做什么:应用运行时需要 destination 与 xsuaa 两个服务实例;目标在内网时再加 connectivity。实例名称必须与 manifest.yml 里的 services: 完全一致,否则部署后应用读不到绑定。

# 0) 登录并选中目标 org/space(CF API 地址在 Cockpit 子账户 Overview 里)
cf api https://api.cf.<region>.hana.ondemand.com
cf login
cf target -o <your-org> -s <your-space>

# 1) Destination 服务(lite 计划即可)
cf create-service destination lite destination-service

# 2) XSUAA 服务(需要 xs-security.json)
cf create-service xsuaa application xsuaa-service -c xs-security.json

# 3) 仅 on-premise 目标需要
cf create-service connectivity lite connectivity-service

在 BTP Cockpit 创建服务实例的三步向导:先选 Service 与 Plan,Runtime Environment 选 Cloud Foundry,再选 Space 并填唯一的 Instance Name,最后在 Instances and Subscriptions 列表里看到状态 Created;图中示例是 HTML5 Application Repository 的 app-host 计划,本案例对应的是 destination(lite) 与 xsuaa(application)(SAP 官方课程 BTP200 截图,非本案例截图)

三个实例的对应关系如下,创建时对照检查,避免名字/计划写错:

实例名(示例仓约定)

服务

计划

绑定到应用后提供什么

destination-service

destination

lite

Destination 服务的访问凭据,SDK 用它按名取目标

xsuaa-service

xsuaa

application

换取访问 Destination 服务令牌所需的 client id/secret

connectivity-service

connectivity

lite

on-premise 目标的隧道凭据,仅内网场景需要

如果创建时报“service plan not found”,先查你所在区域支持的计划名(不同区域/试用账户的计划可能不同):

cf marketplace | grep -E 'destination|xsuaa|connectivity'

如果示例仓自带 xs-security.json,把 -c 指向仓内文件;没有就新建一个最小配置(xsappname 必须在整个 CF 环境唯一,建议加前缀):

{
  "xsappname": "cloud-sdk-js-demo-<your-unique-suffix>",
  "tenant-mode": "shared"
}

绑定方式二选一(推荐 manifest,部署时自动绑定):

# manifest.yml(节选,示例仓已有此文件,只需确认 services 列表存在)
applications:
  - name: cloud-sdk-js-demo
    path: .
    buildpacks:
      - nodejs_buildpack
    memory: 512M
    command: npm run start:prod
    random-route: true
    services:
      - destination-service
      - xsuaa-service
      # - connectivity-service   # 仅 on-premise 目标时打开

也可以在部署后手动绑定:

cf bind-service <app-name> destination-service
cf bind-service <app-name> xsuaa-service
cf restage <app-name>     # 绑定后需要重启/重推才能生效

验证:

# 1) 实例已创建成功
cf service destination-service
cf service xsuaa-service
# 期望输出 status: create succeeded;部署后 bound apps 里会出现你的应用

# 2) 绑定关系存在(部署后执行)
cf services
# 应看到 destination-service / xsuaa-service(及可选的 connectivity-service)

# 3) 环境变量里确实注入了凭据
cf env <app-name> | grep -A 5 'VCAP_SERVICES'
# 找到 "destination" 与 "xsuaa" 两段;不要在截图/聊天里暴露其中的 clientsecret、password

绑定完成后要 restage 或重新 push 才会把 VCAP_SERVICES 注入新实例,只 cf restart 有时不够(环境变量在 staging 阶段写入)。

本地排查时还可以用服务密钥查看 Destination 实例的绑定信息(凭据只读不落盘,用完立刻删):

cf create-service-key destination-service local-debug
cf service-key destination-service local-debug     # 查看 credentials,仅用于对照排查
cf delete-service-key destination-service local-debug -f

注意:服务密钥里的 clientsecret、password 属于敏感信息,不要贴进工单、聊天或截图;排查完立即删除密钥。

常见错误:实例名写成 my-destination,而 manifest.yml 里写 destination-service,部署后报 Destination with name 'S4HANA_BUSINESS_PARTNER' not found。名字必须逐字一致。

步骤 7:生成 OData 客户端

做什么:从 EDMX 服务规格生成 TypeScript 客户端。生成物提供实体类、请求构造器、schema 字段常量,比手拼 URL 更安全。

示例仓的做法:服务规格已放在 resources/service-specs/,package.json 的 postinstall 会在 npm i / npm ci 后自动执行 npm run generate-client。所以安装依赖即可:

cd samples/cds-sample-application

# 有 package-lock.json 优先用 ci,保证可重复构建
npm ci

# 如果 postinstall 没跑成功,手动触发一次
npm run generate-client

# 看一眼生成了什么
ls -1 services/ 2>/dev/null || ls -1 src/generated/ 2>/dev/null || find . -maxdepth 3 -name '*business-partner*'

# 确认入口与 API 导出存在
find services -maxdepth 2 -name 'index.ts' 2>/dev/null | head -n 5
grep -R "businessPartnerService" services --include='*.ts' -l 2>/dev/null | head -n 5

如果多次执行 npm ci 后生成目录仍然为空,说明 postinstall 被跳过(例如用 --ignore-scripts 安装)或生成脚本失败。此时手动执行 npm run generate-client,并仔细读它打印的第一条错误:多数是 Node 版本不满足、EDMX 路径不对或网络取不到依赖。

如果项目是纯 JavaScript(不经过 TypeScript 编译)又在运行时直接 require 生成的代码,生成时需要 --transpile,让生成器同时产出 .js 与 .d.ts:

npx generate-odata-client \
  --input service-specifications \
  --outputDir services \
  --optionsPerService service-specifications/options-per-service.json \
  --transpile

如果示例仓没有现成脚本,用生成器 CLI 手动生成(输出目录按你项目实际调整):

npx generate-odata-client \
  --input service-specifications \
  --outputDir services \
  --optionsPerService service-specifications/options-per-service.json

options-per-service.json 用于固定生成目录名与服务基础路径,避免每次生成目录名漂移:

{
  "service-specifications/API_BUSINESS_PARTNER.edmx": {
    "directoryName": "business-partner-service",
    "basePath": "/sap/opu/odata/sap/API_BUSINESS_PARTNER",
    "packageName": "business-partner-service"
  }
}

生成物

用途

business-partner-service/ 目录

客户端入口(导出 businessPartnerService 与实体类)

.../request-builder 相关文件

getAll / getByKey / create / update / delete 构造器

.../*.d.ts、.../*.js

类型定义与编译产物(启用 transpile 时生成)

生成目录是产物,不要手改:服务规格更新后重新生成即可。真实项目的 EDMX 通常从 SAP Business Accelerator Hub 对应 API 页面下载(Business Partner 选 cloud 版本),下载后放进 service-specs 并在 options-per-service.json 里登记。

验证:能在生成目录里找到 business-partner-service(或 README 指定的目录名),且 package.json 的依赖里出现 @sap-cloud-sdk/odata-v2 或 @sap-cloud-sdk/odata-v4(取决于服务版本)。

注意版本差异:SDK v4 的生成客户端 API 是 businessPartnerService() 函数 + 解构;v3 及更早是静态类 BusinessPartnerService.requestBuilder()。如果示例仓锁定的是旧版本,请按仓内版本写,或者按升级指南升到 v4;本教程代码以 v4 写法为准。

步骤 8:用 HTTP Client 调通第一次 OData

做什么:先用最小的通用 HTTP 客户端验证「Destination 解析 + 认证 + 网络」三件事,再上类型安全客户端。两者都失败时,这个脚本能最快定位问题。

在项目根目录新建 scripts/verify-bp.mjs:

// scripts/verify-bp.mjs
// 最小验证脚本:只依赖 Destination 名称,不写死任何 URL/凭据
import { executeHttpRequest } from '@sap-cloud-sdk/http-client';

const DESTINATION = process.env.BP_DESTINATION ?? 'S4HANA_BUSINESS_PARTNER';
const TOP = Number(process.env.BP_TOP ?? 5);

try {
  const response = await executeHttpRequest(
    { destinationName: DESTINATION },
    {
      method: 'get',
      url: '/sap/opu/odata/sap/API_BUSINESS_PARTNER/A_BusinessPartner',
      params: {
        $top: TOP,
        $select: 'BusinessPartner,FirstName,LastName',
        $format: 'json'
      }
    }
  );

  const body = response.data;
  const partners = body?.d?.results ?? body?.value ?? body;
  console.log(`HTTP ${response.status},返回 ${Array.isArray(partners) ? partners.length : 1} 条记录`);
  console.table(partners);
} catch (error) {
  console.error('调用失败:', error.message);
  console.error('根因:', error.rootCause?.message ?? error.cause?.message);
  console.error('后端响应体:', error.rootCause?.response?.data);
  process.exitCode = 1;
}

本地运行时还要让 SDK 能找到 Destination。两种方式:

# 方式 A:显式注入本地 destinations 环境变量(仅本地测试!)
# 注意 JSON 必须写在一行;密码不要提交进 Git、也不要写进 shell 脚本后提交
export destinations='[{"name":"S4HANA_BUSINESS_PARTNER","url":"https://my-s4.example.com","authentication":"BasicAuthentication","username":"COMM_USER_BP","password":"<password>","sap-client":"100"}]'

# 方式 B:从 BTP 上已绑定该 Destination 服务的应用里导出环境变量后复用(同样只在本地临时使用)
# cf env <app-name>  # 参考 VCAP_SERVICES 中 destination 的 credentials,再按方式 A 的格式组装

还有一种更彻底的本地方案:完全不依赖环境变量,直接在代码里传一个目标对象。它同样走 SDK 的 URL 拼接与反序列化,只适合临时确认“后端服务本身能不能调通”,不要当成生产写法:

import { executeHttpRequest } from '@sap-cloud-sdk/http-client';

const response = await executeHttpRequest(
  { url: 'http://localhost:3000', authentication: 'NoAuthentication' },
  {
    method: 'get',
    url: '/sap/opu/odata/sap/API_BUSINESS_PARTNER/A_BusinessPartner',
    params: { $top: 1, $format: 'json' }
  }
);

运行并观察:

node scripts/verify-bp.mjs

成功时控制台大致如下(数值与字段以你系统实际返回为准):

HTTP 200,返回 5 条记录
┌─────────┬───────────────┬────────────┬───────────┐
│ (index) │ BusinessPartner│ FirstName  │ LastName  │
├─────────┼───────────────┼────────────┼───────────┤
│ 0       │ '1000000'     │ 'Peter'    │ 'Pan'     │
│ ...     │ ...           │ ...        │ ...       │
└─────────┴───────────────┴────────────┴───────────┘

如果脚本返回 HTTP 200 但记录数为 0,通常不是代码问题:检查 sap-client 是否指向有数据的集团、通信用户是否被行权限过滤、目标系统是否本来就没有业务伙伴数据。可以先用步骤 4 里的 curl 命令直接查同一个集合对照结果。

验证:输出 HTTP 200,返回 5 条记录 并打印表格;若失败,按错误类型分别处理(步骤 10 有分类表):

  • Destination with name ... not found → 环境变量没生效/名字拼错/服务实例没绑定;

  • 401 → Destination 认证方式或通信用户密码不对;

  • 403 → 通信用户权限不足或通信安排未启用服务;

  • 404 → URL 或服务路径拼错(URL 不要带服务路径);

  • ENOTFOUND / ETIMEDOUT → 网络不可达(公网系统查白名单;内网系统查 Cloud Connector)。

云端验证时无需 destinations 环境变量:应用绑定了 Destination 服务实例后,SDK 会自己按名查找。

步骤 9:换成类型安全客户端查询业务伙伴

做什么:把“手拼 URL + 自己解析 JSON”升级为“实体 + 请求构造器”,获得类型提示和自动反序列化。下面按 SDK v4 的生成客户端写法:

// src/business-partner.ts(示例,按你项目结构放)
import { businessPartnerService } from '../services/business-partner-service';

const { businessPartnerApi } = businessPartnerService();

export async function getTopBusinessPartners(limit = 5) {
  return businessPartnerApi
    .requestBuilder()
    .getAll()
    .top(limit)
    .select(
      businessPartnerApi.schema.BUSINESS_PARTNER,
      businessPartnerApi.schema.FIRST_NAME,
      businessPartnerApi.schema.LAST_NAME
    )
    .execute({ destinationName: 'S4HANA_BUSINESS_PARTNER' });
}

调用并打印:

const partners = await getTopBusinessPartners(5);
console.log(`共 ${partners.length} 条`);
for (const bp of partners) {
  console.log(bp.businessPartner, bp.firstName, bp.lastName);
}

条件查询同样用构造器,SDK 会自动拼成 $filter,不要自己拼字符串(避免引号/转义/注入问题):

export async function findBusinessPartnersByLastName(lastName: string) {
  return businessPartnerApi
    .requestBuilder()
    .getAll()
    .filter(businessPartnerApi.schema.LAST_NAME.equals(lastName))
    .top(10)
    .execute({ destinationName: 'S4HANA_BUSINESS_PARTNER' });
}

过滤表达式支持 and / or / not 组合,以及 equals / notEquals / greaterThan / lessThan 等比较运算符;复杂条件建议先在 API 测试工具里拼好,再翻译成构造器写法。

列表接口必须分页,不要一次拉全量。下面用 $top + $skip 循环,直到某页不足一页为止(S/4HANA 对单页大小通常有上限,50–100 是稳妥值):

const PAGE_SIZE = 50;
const MAX_PAGES = 20;   // 兜底,避免服务端异常时死循环

export async function getAllBusinessPartnersInPages() {
  const all = [];

  for (let page = 0; page < MAX_PAGES; page++) {
    const batch = await businessPartnerApi
      .requestBuilder()
      .getAll()
      .select(
        businessPartnerApi.schema.BUSINESS_PARTNER,
        businessPartnerApi.schema.FIRST_NAME,
        businessPartnerApi.schema.LAST_NAME
      )
      .withCustomQueryParameters({ $orderby: 'BusinessPartner' })  // 稳定排序,避免翻页重复/遗漏
      .top(PAGE_SIZE)
      .skip(page * PAGE_SIZE)
      .execute({ destinationName: 'S4HANA_BUSINESS_PARTNER' });

    all.push(...batch);
    if (batch.length < PAGE_SIZE) break;
  }

  return all;
}

分页要点:$orderby 要选唯一且稳定的键(业务伙伴用 BusinessPartner);$top 有上限,别设成 999999;数据量很大时改用服务端提供的 $skiptoken / @odata.nextLink 续页方式(V2/V4 的后端能力不同,以服务实际返回为准)。

要点:

  • execute() 的参数既可以是 Destination 名称对象,也可以是已取到的 Destination 对象;传名称是最安全的做法。

  • .top() / .skip() 对应 OData 的 $top / $skip;schema 上的字段常量对应实体属性,避免手写属性名拼错。

  • filter() 里只用 schema 常量组合条件;属性名写成字符串既不安全,也容易因大小写出错。

  • 同一服务里要用多个实体 API 时,一次性解构,例如 const { businessPartnerApi, businessPartnerAddressApi } = businessPartnerService();;分两次调用 businessPartnerService() 再取属性,可能丢导航属性。

  • SDK 会把 OData 的 Edm.DateTime、Edm.Decimal 等类型转换成 JavaScript 类型(如 moment、BigNumber),读取时留意类型。

  • 如果生成的是 OData V4 客户端,写法和上面几乎一致,只是服务路径与返回结构不同(见步骤 12)。

验证:与步骤 8 返回同样的业务伙伴数据;类型提示里能点出 bp.firstName 等字段。若编译报“找不到 businessPartnerService”,说明生成目录名/导入路径不对,回到步骤 7 确认。

本地失败时按层排查,别一上来就改代码:① 确认 destinations 环境变量真的在进程里(node -e "console.log(process.env.destinations)");② 确认 Destination 名称与 URL 正确;③ 直接 curl 目标 URL 看网络是否可达;④ 确认生成客户端的服务路径与后端一致。四步走完,问题一般就定位到某一层了。

步骤 10:加错误分类与可读日志

做什么:SDK 会把底层错误包成带根因的错误对象(cause / rootCause),其中的 Axios 错误还带着后端响应体。把 401/403/404/5xx 分开处理,排错时间能少一大半。

// scripts/call-with-error-handling.mjs(示例)
import { executeHttpRequest } from '@sap-cloud-sdk/http-client';

try {
  const response = await executeHttpRequest(
    { destinationName: 'S4HANA_BUSINESS_PARTNER' },
    {
      method: 'get',
      url: '/sap/opu/odata/sap/API_BUSINESS_PARTNER/A_BusinessPartner',
      params: { $top: 1, $format: 'json' }
    }
  );
  console.log('OK', response.status);
} catch (error) {
  const response = error.rootCause?.response ?? error.cause?.response;
  const status = response?.status;
  const body = response?.data;

  switch (true) {
    case status === 401:
      console.error('[401] 认证失败:检查 Destination 认证方式、通信用户密码/证书、OAuth 令牌服务配置');
      break;
    case status === 403:
      console.error('[403] 授权不足:检查通信用户的业务角色、通信安排里启用的服务');
      break;
    case status === 404:
      console.error('[404] 地址不对:检查 Destination URL(不要带服务路径)、服务路径、sap-client');
      break;
    case status >= 500:
      console.error('[5xx] 后端/网关错误:可重试;先看后端响应体,不要盲目重试');
      break;
    default:
      console.error('其他错误:', error.message);
  }

  console.error('根因:', error.rootCause?.message ?? error.cause?.message);
  console.error('后端响应体:', body);
  process.exitCode = 1;
}

现象

原因

处理

401

认证方式/密码/证书错误,通信用户被锁

在 BTP 里重测 Destination 连接;核对通信安排认证方式

403

认证成功但无权限

给通信用户补业务角色/授权,确认服务已在通信安排启用

404

URL/路径/Client 不对

Destination URL 只到 host;检查 sap-client、服务路径拼写

400

查询参数非法($select 字段不存在等)

用 $metadata 核对字段名;先去掉 $select 试

5xx

后端或网关临时故障/超时

先看响应体;配合步骤 11 的超时+重试

ECONNRESET / TLS 错误

网络、证书链、代理问题

公网查白名单/证书;on-prem 查 Cloud Connector 与信任配置

后端返回的错误体通常长这样(V2 示例,字段以实际为准),真正有用的信息在 message.value 里:

{
  "error": {
    "code": "005056A509B11EE1B9A8FEC11C21D1A0",
    "message": {
      "lang": "en",
      "value": "User COMM_USER_BP is not authorized for service API_BUSINESS_PARTNER"
    }
  }
}

所以日志里只打印 status code 是不够的,把响应体一并打出来,401/403 的具体原因一眼就能看到。另外一个容易忽略的点:如果后端返回的是 HTML 而不是 OData 的 JSON 错误体(例如 S/4HANA 前面的反向代理或 SAML 登录页),说明请求根本没到 OData 服务,要检查 Destination URL 是否指向了正确的应用服务器、该地址是否被网络代理或单点登录拦截;SDK 默认会带 Accept: application/json,服务端仍返回 HTML 时优先怀疑网络链路而不是代码。

定位问题时还有一个好用的方法:用 executeRaw() 看 SDK 实际拼出的 URL、状态码和响应头,而不是只看封装后的实体:

const raw = await businessPartnerApi
  .requestBuilder()
  .getAll()
  .top(1)
  .executeRaw({ destinationName: 'S4HANA_BUSINESS_PARTNER' });

console.log('status:', raw.status);
console.log('content-type:', raw.headers['content-type']);
console.log('实际请求 URL:', raw.request?.url);

错误对象本身是 ErrorWithCause,cause 指向直接原因、rootCause 指向最底层原因;Axios 错误的 response 里才有后端返回的正文(OData 的错误通常是 error.message.value 或 error.innererror 结构),所以日志里一定要打印它,否则只能看到一句 Request failed with status code 403。

建议日志固定打印 destinationName、status、请求 url、耗时四个字段;云端排错时用 cf logs <app> --recent | grep <destinationName> 就能快速筛出相关调用,而不必在成百上千行日志里逐条找。

验证:人为把 Destination 名称改错,脚本应打印 Destination with name ... not found;把 URL 改成不存在的主机,应打印网络错误而不是笼统的堆栈。

步骤 11:加超时、重试与熔断(韧性中间件)

做什么:跨网络调用必须有超时和针对瞬时故障的重试。SDK 提供 @sap-cloud-sdk/resilience,推荐用 resilience() 一次生成正确顺序的中间件。

import { executeHttpRequest } from '@sap-cloud-sdk/http-client';
import { resilience } from '@sap-cloud-sdk/resilience';

// timeout:10 秒;retry:2 次;circuitBreaker:默认开启
const middlewares = resilience({ timeout: 10000, retry: 2 });

const response = await executeHttpRequest(
  { destinationName: 'S4HANA_BUSINESS_PARTNER' },
  {
    method: 'get',
    url: '/sap/opu/odata/sap/API_BUSINESS_PARTNER/A_BusinessPartner',
    params: { $top: 5, $format: 'json' },
    middleware: middlewares
  }
);

生成的客户端用法相同,把中间件挂到请求构造器上:

import { retry, timeout } from '@sap-cloud-sdk/resilience';

const partners = await businessPartnerApi
  .requestBuilder()
  .getAll()
  .top(5)
  .middleware(timeout(10000), retry(2))
  .execute({ destinationName: 'S4HANA_BUSINESS_PARTNER' });

哪些错误该重试,先想清楚再配参数:

错误类型

是否重试

说明

连接超时、连接被重置、DNS 临时失败

是

典型瞬时故障,重试大概率恢复

500 / 502 / 503 / 504

是

后端或网关临时故障;结合响应体判断

429 Too Many Requests

有条件

尊重服务端限流,配合退避;不要固定高频重试

400 / 401 / 403 / 404

否

请求/认证/权限/路径错误,重试不会变好

熔断器已打开

否

直接快速失败,等恢复窗口后再试

使用要点:

  • 顺序:超时在前(防止一个请求挂太久),重试在后(覆盖所有失败路径);resilience() 会自动排好,手写 middleware() 时也要遵守这个顺序。

  • 重试只适合瞬时错误:4xx 重试没有意义,应只对网络错误/5xx 重试;retry() 默认 3 次、指数退避(约 2/4/8 秒)。

  • 熔断器按目标系统 + 租户隔离状态;4xx 不计为失败;默认滚动窗口 10 秒、错误率 50%、恢复 30 秒。

  • resilience() 不带参数时默认开启超时(10 秒)与熔断(重试默认关闭);要重试必须显式传 retry。

  • 不要把重试次数调大来“压”一个持续故障,先修根因。

验证:把 Destination URL 临时改成一个必然 5xx/不可达的地址,日志中能看到重试发生(多次请求)且最终失败;改回正确配置后一次成功。

步骤 12:OData V4 服务的差异写法

做什么:如果你要调的是 OData V4 服务(例如 CAP 服务或标注为 V4 的 API),生成器会产出 V4 客户端,写法与 V2 类似但有几处必须注意。

// 示例:从 V4 EDMX 生成的客户端(服务名/字段名按你实际生成结果替换,
// 这里用占位名说明结构,不代表某个真实服务)
import { myV4Service } from '../services/my-v4-service';

const { myEntityApi } = myV4Service();

const rows = await myEntityApi
  .requestBuilder()
  .getAll()
  .top(20)
  .skip(0)
  .execute({ destinationName: 'S4HANA_V4_SERVICE' });

注意点

V2

V4

运行时包

@sap-cloud-sdk/odata-v2

@sap-cloud-sdk/odata-v4

EDMX 来源

服务商/API Hub 下载 V2 规格

下载 V4 规格,不要混用

服务路径

/sap/opu/odata/sap/<SERVICE>

按 V4 服务的实际路径(CAP 常见 /odata/v4/<service>)

$select 与导航

V2 里 select 导航属性常隐式展开

V4 中 select 不自动展开导航属性,需要显式处理

分页续页

$top/$skip,S/4HANA 可能返回 $skiptoken

可能返回 @odata.nextLink,需要按服务端提示取下一页

日期时间类型

Edm.DateTime 转 moment

Edm.Date / Edm.Duration / Edm.TimeOfDay 有独立类型

下载规格时先确认版本:EDMX 根节点是 <edmx:Edmx Version="4.0"> 的服务才用 @sap-cloud-sdk/odata-v4,V2 规格用 odata-v2,两者混用会在运行时生成错误的 URL 或反序列化失败。V4 服务的 basePath 通常是 /odata/v4/<service>,生成前可在 options-per-service.json 里手工修正;生成目录名与 import 名对不上时,也是查这个文件的 directoryName。

验证:options-per-service.json 里该服务的 basePath 是 V4 路径;请求返回的数据在 value 数组里(而不是 d.results),且 @odata.nextLink 能被正确识别。

步骤 13:本地运行完整示例应用

做什么:先把 CAP 模型部署到本地,再启动应用。示例仓 README 给的两条命令是:

cd samples/cds-sample-application

# 1) 部署 CDS 模型(首次运行或模型变更后)
npm run cds-deploy

# 2) 启动开发服务器(默认端口以日志为准,常见 8080;若与 mock 的 3000 冲突会自动换端口)
npm run start:dev

本地 Destination 通过 destinations 环境变量注入(仅本地测试;示例见步骤 8)。如果使用 mock 服务,先启动 mock(默认 http://localhost:3000),并让 Destination 的 URL 指向它。

另开一个终端验证应用已经起来:

# 根路径能返回内容(200/302/401 都说明进程在监听;具体路由以示例 README 为准)
curl -i http://localhost:8080/ | head -n 5

# 直接验证 SDK 调用(步骤 8 的脚本)
node scripts/verify-bp.mjs

启动日志大致是“先加载 CDS 模型,再监听端口”的形态(具体文案随 CAP 版本变化,以实际输出为准):

[cds] - loaded model from 2 file(s)
[cds] - serving <service-name> { path: '/odata/v4/<service>' }
[cds] - server listening on { url: 'http://localhost:8080' }

没有 S/4HANA 时,用官方入门教程配套的本地 mock OData 服务演练,流程不变:

  1. 按该 mock 项目 README 启动服务(默认监听 http://localhost:3000);

  2. 把本地 destinations 环境变量里的 url 改成 http://localhost:3000,authentication 改成 NoAuthentication:

export destinations='[{"name":"S4HANA_BUSINESS_PARTNER","url":"http://localhost:3000","authentication":"NoAuthentication"}]'
  1. 重新执行 node scripts/verify-bp.mjs,确认能拿到模拟数据;

  2. 部署步骤仍可照做:只验证“应用能上 CF、服务绑定正确”,云端 OData 验证改为指向一个 BTP 可达的 mock 地址(或暂时跳过第 15 步的第 4 小项)。

验证:

  • 启动日志里出现 “server listening” 或 CDS 服务启动信息,进程不退出;

  • 终端无未捕获异常;

  • node scripts/verify-bp.mjs 打印 HTTP 200 和业务伙伴记录;

  • 若控制台提示端口被占用,改用 PORT=8081 npm run start:dev 之类的环境变量(以项目实际支持方式为准)。

本地常见故障先这样排除:cds-deploy 报本地数据库被占用 → 先停掉其他 start:dev 进程;destinations 变量 JSON 写错 → Node 启动即报 Unexpected token,用 node -e "JSON.parse(process.env.destinations)" 校验;改了 .env 不生效 → 确认应用真的加载了该文件(有的项目用 dotenv,有的用框架配置模块),重启进程再试。

本地跑通 ≠ 云端能跑通。本地没有 XSUAA/Destination 服务,SDK 走的是 destinations 环境变量分支;云端走的是服务绑定分支,所以步骤 14–15 必须单独验证。

步骤 14:部署到 Cloud Foundry

做什么:把应用、服务绑定、启动命令一起推上 CF,并让应用使用云端的 Destination。

先确认 manifest.yml 至少包含:应用名、path、Node buildpack、内存、启动命令、两个服务实例名。示例(节选,示例仓已有则按需补充 services):

applications:
  - name: cloud-sdk-js-demo
    path: .
    buildpacks:
      - nodejs_buildpack
    memory: 512M
    command: npm run start:prod
    random-route: true
    services:
      - destination-service
      - xsuaa-service

同时在 package.json 里声明 Node 主版本,避免 buildpack 选到旧运行时(SDK v4 需要 Node 22):

{
  "engines": {
    "node": "22.x"
  }
}

部署方式二选一:

# 方式 A:示例仓的一键脚本(内部依次执行 ci-build、ci-package、cf push)
npm run deploy

# 方式 B:手动分步,便于观察每一步
npm run ci-build
npm run ci-package
cf push

如果希望“先创建并绑定服务,再启动应用”,可用:

cf push --no-start
cf bind-service cloud-sdk-js-demo destination-service
cf bind-service cloud-sdk-js-demo xsuaa-service
cf start cloud-sdk-js-demo

cf push 成功时的输出大致如下(示意,以实际输出为准):

Waiting for app to start...
name:              cloud-sdk-js-demo
requested state:   started
routes:            cloud-sdk-js-demo.cfapps.<region>.hana.ondemand.com
last uploaded:     ...
stack:             cflinuxfs4
buildpacks:        nodejs
instances:         1/1
memory usage:      512M
start command:     npm run start:prod

部署完成后应用列表里的状态:Requested State 一列显示绿色 Started,并列出 Instances、Instance Disk、Instance Memory 等列,对应命令行 cf app 输出里的 instances 1/1;图中应用名、路由等已在课程截图里做模糊处理(SAP 官方课程 CF400 截图,非本案例截图)

几个部署期的注意点:

  • 如果 staging 日志里实际使用的 Node 版本不是 22,回去检查根目录 package.json 的 engines 是否被 buildpack 识别;改了依赖或引擎声明后必须重新 cf push(只 restart 用的是旧产物)。

  • 改了 manifest.yml 的环境变量或服务绑定后,用 cf restage 让 staging 重新执行;cf restart 只重启已 staged 的产物,VCAP_SERVICES 可能还是旧的。

  • 示例仓如果带 approuter/ 目录(如 cf-sample-application),应用与 approuter 要按各自 README 分别部署;本教程主线示例不涉及 approuter。

若 push 后一直 0/1,按顺序看三处:cf events <app-name>(最近一次崩溃/启动事件)、cf logs <app-name> --recent(第一处异常堆栈)、cf app <app-name>(实例状态与内存占用)。先解决第一处报错,不要同时改多个配置,否则无法判断是哪一项生效。

部署成功后先把路由记下来,后面 curl 和浏览器都用它:

cf app cloud-sdk-js-demo | grep -A 1 -i routes
# routes: cloud-sdk-js-demo.cfapps.<region>.hana.ondemand.com

验证:

cf app cloud-sdk-js-demo
# 期望:requested state: started;instances: 1/1;routes 里给出应用 URL

若 cf app 显示 0/1 或反复 crash,立即:

cf logs cloud-sdk-js-demo --recent | tail -n 100

常见原因:内存不足(把 memory 调到 1G)、启动命令与构建产物不匹配、package.json engines 与 buildpack 冲突、服务实例没绑定。

步骤 15:在云端验证调用链

做什么:确认云端不是“进程起来了”,而是真的能通过 Destination 调到后端。

# 1) 确认绑定环境变量存在(凭据不要复制到聊天/工单里)
cf env cloud-sdk-js-demo | grep -E 'destination|xsuaa' -A 3

# 2) 看启动日志与错误
cf logs cloud-sdk-js-demo --recent | tail -n 120

# 3) 访问应用路由,确认服务可达(200/302/401 都算应用在线;401 时检查 approuter/IdP)
curl -i "https://<your-app-route>/" | head -n 10

# 4) 在云上跑一次最小验证脚本(任务结束后看日志确认结果)
cf run-task cloud-sdk-js-demo --command "node scripts/verify-bp.mjs" --name verify-bp
cf logs cloud-sdk-js-demo --recent | grep -i -E 'verify-bp|BusinessPartner|HTTP 200' | tail -n 20

# 5) 查看任务最终状态(SUCCEEDED 才算真的跑通)
cf tasks cloud-sdk-js-demo

cf run-task 启动的是一次性任务,和 web 进程共享同一套环境变量与服务绑定,因此它是验证“云端 SDK 调用”最直接的方式:任务能打印 HTTP 200,说明 XSUAA 取令牌、Destination 解析、认证与网络都通了。任务失败时,cf logs --recent 里会带出脚本打印的 根因 和 后端响应体。

如果示例应用对外提供返回业务数据的路由,再用“业务视角”确认一次:浏览器打开 https://<your-app-route>/(或 README 里给出的数据端点),返回的 JSON 应与本地脚本一致。若返回 401,说明应用前面有 approuter 或 IdP 拦截,按示例 README 登录后再访问,不要去改应用代码。

cf logs --recent 里成功的调用通常能看到请求 URL 和 200 状态附近的记录;失败时先定位第一处 ERROR 以及它上面那条请求 URL,不要从最后一行倒着找(后面往往是一连串重试噪声)。

验证:

  • cf app 为 1/1 running;

  • cf env 能看到 destination 与 xsuaa 两组绑定;

  • cf run-task 的任务日志里出现 HTTP 200 与业务伙伴记录;

  • 应用日志里没有 401/403/连接超时;

  • 若使用 on-premise 目标,cf logs 中不应出现 Connectivity Proxy 连接失败。

想验证“换成 Destination 后仍然成功、且代码无明文凭据”,做一次反向检查:把代码里的 Destination 名改成不存在的名字,重新 cf push,应快速失败;再改回。同时执行 grep -RIn "password\|clientsecret\|Authorization" --include='*.ts' --include='*.js' --include='*.mjs' src scripts | grep -v node_modules 确认没有任何明文凭据(示例代码里的 “authentication” 字样属于正常用法)。

步骤 16(可选):体验多端点示例与主体传播

做什么:如果你的目标不止“云端直连”,还想看 on-premise 与用户身份透传(principal propagation),可再取 samples/cf-sample-application:它含 approuter、源码中的 4 个端点(分别面向云端、on-premise、主体传播场景),以及部署后跑全部端点的 Cypress e2e 测试。

# 在 cloud-sdk-js 仓库根目录执行
git sparse-checkout add samples/cf-sample-application
cd samples/cf-sample-application

它需要三个服务实例,名称必须与自身 manifest.yml 一致:

cf create-service destination lite sample-destination-service
cf create-service xsuaa application sample-xsuaa-service -c xs-security.json
cf create-service connectivity lite sample-connectivity-service

部署前还要做三件事:

  1. 把仓库里所有 <REPLACE-ME> 占位符替换成实际值(Destination 名称、子域名等)——搜索 REPLACE-ME 就能找全;

  2. 修改 approuter/xs-app.json,改用与你子账户关联的 IdP,或按 README 说明不使用 IdP;

  3. 在根目录和 approuter/ 目录分别执行 npm run deploy,最后打开 approuter 的 URL 访问应用。

想跑部署后的端点测试,在 e2e-tests/ 下按该目录 README 创建 cypress.env.json(只放测试账号,别提交进 Git):

{
  "username": "your-idp-user",
  "password": "your-idp-password",
  "url": "https://<your-approuter-route>"
}

验证:approuter URL 能打开应用;4 个端点按 README 请求均返回数据(on-premise 与主体传播端点要求 Cloud Connector 与后端信任已配好);e2e 测试全部通过。若只做主线,本步骤可跳过,不影响验收。如果 e2e 里只有 on-premise 端点失败,先检查 Cloud Connector 的映射与后端证书信任,再回看对应 Destination 的 Proxy Type 是否为 OnPremise。

验收与清理

验收清单

#

验收项

通过标准

1

示例仓能拉到

samples/cds-sample-application 下有 manifest.yml、srv/、resources/

2

依赖与客户端生成

npm ci 成功,生成目录里有 business-partner-service 客户端

3

Destination 配置正确

BTP 里 Check Connection 成功,名称与代码一致

4

服务实例已绑定

cf services 有实例;cf env 里 VCAP_SERVICES 含 destination/xsuaa

5

本地最小调用成功

node scripts/verify-bp.mjs 输出 HTTP 200 与记录

6

类型安全客户端可用

查询代码能编译/运行,返回实体数组

7

分页正确

翻页无重复、无遗漏;页大小与 $top 一致

8

错误分类有效

错误名称/URL 时能输出 401/403/404/网络错误分类日志

9

韧性中间件生效

不可达目标时能超时/重试后失败,不无限挂起

10

云端部署成功

cf app 为 1/1 running,cf logs 无异常堆栈

11

云端调用成功

cf run-task/应用端点返回业务数据,日志有 200 记录

12

无明文凭据

代码与 Git 中无 URL/账号/密码/Client Secret

资源清理

按顺序执行,避免残留计费资源:

# 1) 停止并删除应用(路由随应用一起删除)
cf stop cloud-sdk-js-demo
cf delete cloud-sdk-js-demo -f

# 2) 删除服务实例(先确认没有其他应用绑定;有绑定时先解绑)
cf unbind-service <other-app> destination-service   # 如仍有其他应用使用
cf delete-service destination-service -f
cf delete-service xsuaa-service -f
cf delete-service connectivity-service -f           # 若创建过

# 3) 本地清理
cd ..
rm -rf cloud-sdk-js
unset destinations
rm -f .env     # 若本地创建过存放 destinations 的 .env

资源

位置

清理方式

注意

CF 应用

BTP CF 空间

cf delete <app> -f

路由一并删除

Destination 实例

CF 空间

cf delete-service destination-service -f

删除前确认无绑定

XSUAA 实例

CF 空间

cf delete-service xsuaa-service -f

同上

Connectivity 实例

CF 空间

cf delete-service connectivity-service -f

未使用则不需要创建

Destination 配置

BTP Cockpit

Connectivity → Destinations → 删除

删除后本地无法再按名解析

通信用户/通信安排

S/4HANA Fiori

通信管理里删除或停用

若其他集成也在用,不要直接删,先确认影响

本地仓库与凭据

本机

删仓库、unset destinations、删 .env

检查 shell 历史里是否残留密码

常见问题

现象

原因

处理

Destination with name 'S4HANA_BUSINESS_PARTNER' not found

名称不一致;服务实例未绑定;本地未设置 destinations 环境变量

逐字核对 Destination 名称;cf env 看绑定;本地按步骤 8 注入环境变量

本地成功、云端 401

云端 Destination 认证方式与通信安排不一致;服务绑定指向了另一套 Destination 配置

在 BTP 里 Check Connection;核对 Destination 与通信用户的密码/证书;确认空间/子账户正确

401 且提示取不到令牌

XSUAA 实例缺失或 xsappname 冲突

确认 xsuaa-service 已绑定;xsappname 全局唯一;重新 cf restage

403 Forbidden(OData 返回)

通信用户权限不足;通信安排未启用该服务

补业务角色/授权;在通信安排中启用 API_BUSINESS_PARTNER;检查 sap-client

404 / “资源不存在”

Destination URL 带了服务路径;服务路径拼错;sap-client 不对

URL 只填 https://host;服务路径单独在代码/生成客户端里;核对 client 号

on-premise 目标云端超时、本地正常

缺 connectivity 实例;Cloud Connector 未映射/未信任;证书问题

创建并绑定 connectivity;Cloud Connector 添加系统映射与访问控制;检查 TLS 信任

npm ci 失败 / generate-client 报错

Node 版本不符;EDMX 缺失或路径不对;postinstall 被跳过

切到 Node 22(或仓内 engines 要求);检查 resources/service-specs;手动跑 npm run generate-client

生成客户端后编译报“找不到模块”

导入路径/生成目录名不对;OData V2/V4 包混用

看 options-per-service.json 的 directoryName;V2 服务装 @sap-cloud-sdk/odata-v2,V4 装 odata-v4

改了 Destination 但云端仍用旧配置

SDK v4 默认启用 Destination 缓存

用 useCache: false 临时禁用,或等待缓存过期后重试(重启应用也可)

分页有重复/漏数据

按页取数但没有稳定排序;分页期间数据被修改;页大小超过服务端上限

用 $orderby 指定稳定排序键;对一致性要求高的场景改为按时间窗/键范围分页

重试把 401/403 也重试了,越试越慢

未区分错误类型,盲目重试 4xx

只对网络错误和 5xx 重试;4xx 直接暴露给调用方;校准超时与熔断参数

cf push 后实例反复重启

内存不足;启动命令与产物不匹配;Node 版本被 buildpack 选错

cf logs --recent 看第一处报错;调大 memory;在 package.json 声明 engines.node;检查 command

用沙箱 API 直接 401

沙箱要求 APIKey 请求头,且 Destination 用了错误认证方式

代码里 addCustomHeaders({ APIKey: ... }) 或用环境变量注入;Destination 认证选 NoAuthentication;不要提交 Key

其他示例索引

本案例的原始资料是一批示例的合集。主线之外,其余示例按需取用:

示例目录

一句话场景

主要命令

samples/cf-sample-application

CF 上的多端点应用(云端/on-premise/主体传播),带 approuter 与 Cypress e2e

根目录与 approuter/ 分别 npm run deploy

samples/cf-multi-tenant-application

多租户参考实现(approuter + service-config),部署前替换 YOUR_* 占位符

各组件 cf push,按多租户教程顺序部署

samples/k8s-sample-application

Kubernetes 端到端应用(Dockerfile、pipeline、e2e)

改镜像/ingress 后 kubectl apply -f

samples/helm-sample-application

Kubernetes/Helm 版示例,含 SAP BTP Operator 与服务定义

helm install ... --values values.yaml

samples/http-client-examples

通用 HTTP Client 的可运行示例(以测试形式组织)

npm ci && npm run test

samples/resilience-examples

自定义韧性中间件示例

参考 resilience.ts 与 resilience.spec.ts

官方原文(参考)

本文是编者基于上述示例集主线扩写的离线教程:原文提供示例清单、仓库结构与官方命令,本文补齐了环境检查、Destination/通信安排配置、完整可运行代码、逐项验证与排错方法;SDK 具体版本行为(如 v4 要求 Node 22、Destination 默认缓存)以官方文档为准。