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)
具体交付物如下:
交付物 |
验收标志 |
|---|---|
一份官方示例代码 |
从 |
一个可用的 Destination |
BTP Cockpit 里 |
一段可复用的调用代码 |
类型安全 OData 客户端 + 分页 + 错误分类日志 + 超时/重试/熔断中间件 |
一个本地可运行的应用 |
|
一个云端可验证的应用 |
|
一份可回收的资源清单 |
「验收与清理」一节给出 |
跑通后,控制台里最有代表性的一段输出是这样的(字段以你系统实际返回为准):
{
"d": {
"results": [
{ "BusinessPartner": "1000000", "FirstName": "Peter", "LastName": "Pan" },
{ "BusinessPartner": "1000001", "FirstName": "Alice", "LastName": "Smith" }
]
}
}

图:本教程主线代码来自 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 生成实体与请求构造器 |
韧性 |
自己写重试/超时/熔断 |
一行 |
多租户 |
自己解析 JWT 里的租户 |
传 |
核心包与分工
npm 包 |
作用 |
本教程用在哪 |
|---|---|---|
|
Destination/XSUAA/Connectivity/服务绑定的读取与转换 |
理解“目标从哪来”; |
|
通用 HTTP 客户端 |
步骤 8 的最小验证脚本 |
|
OData V2/V4 运行时基础库(实体、序列化、请求构造基类) |
生成客户端时的运行时依赖 |
|
读 EDMX 生成 TypeScript 客户端(CLI: |
步骤 7 生成业务伙伴客户端 |
|
|
步骤 11 加超时与重试 |
|
同理,面向 OpenAPI 服务 |
本教程不展开 |
一次调用的完整链路
以「应用在 Cloud Foundry 上,经 Destination 调用 S/4HANA 的 Business Partner API」为例:
应用启动,环境变量
VCAP_SERVICES里已经有destination、xsuaa两个服务绑定(由manifest.yml自动绑定)。业务代码执行
businessPartnerApi.requestBuilder().getAll().execute({ destinationName: 'S4HANA_BUSINESS_PARTNER' })。SDK 向 XSUAA 用服务绑定的 client id/secret 换一个 access token。
SDK 拿 token 调 Destination 服务,请求名为
S4HANA_BUSINESS_PARTNER的目标配置(URL、认证方式、附加属性)。Destination 服务返回解析好的目标;SDK 按认证方式准备请求头(Basic 直接加,OAuth2 再换目标系统令牌)。
SDK 拼接 URL:目标 URL + 服务路径(如
/sap/opu/odata/sap/API_BUSINESS_PARTNER)+ 实体集与查询参数,发出请求。若目标是公网 S/4HANA,直连;若目标是内网 on-premise,请求经 Connectivity 服务、Cloud Connector 到达后端。
响应被反序列化成实体数组返回;异常被包装成带
cause/rootCause的错误,供你分类处理。

组件 |
职责 |
出问题时通常表现为 |
|---|---|---|
XSUAA |
给应用签发访问 Destination 服务的令牌 |
401/403,日志提示取不到 token |
Destination 服务 |
保存并下发目标配置 |
|
Connectivity 服务 |
为 on-premise 目标建立到 Cloud Connector 的隧道 |
云端超时、502/504,本地却正常 |
Cloud Connector |
部署在客户网络,把内网系统映射给 BTP |
云端 404/连接被拒; |
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 的顺序(命中即停止):
进程的环境变量
destinations(本地开发时最方便,不要用于生产);代码里用
registerDestination()注册的目标;服务绑定环境变量(
VCAP_SERVICES);BTP Destination 服务(生产环境的主要来源)。
理解这个顺序很重要:本地能跑、云端找不到目标,十有八九是第 4 步没配好或服务实例没绑定。
Destination 的认证方式怎么选
场景 |
Proxy Type |
Authentication |
说明 |
|---|---|---|---|
公网可达的 S/4HANA Cloud |
|
|
最简单,用通信用户账号密码;教程主线用这个 |
公网可达的 S/4HANA Cloud |
|
|
通信安排里创建 OAuth 2.0 客户端,Destination 填 Token Service URL、Client ID/Secret |
内网 S/4HANA(on-premise) |
|
|
必须创建 connectivity 服务实例 + 配好 Cloud Connector |
需要把登录用户身份传到后端 |
|
|
还要求 Cloud Connector 开启主体传播、后端信任配置;比 Basic 复杂 |
本地 mock / 沙箱演练 |
|
|
无认证最省事,仅供联调 |
安全底线:URL、用户名、密码、Client Secret 一律不写进代码和 Git。用 Destination、服务绑定或环境变量注入;本教程所有代码都只引用 Destination 名称。
OData V2 与 V4 的差异
SDK 对两个版本都提供类型安全客户端,日常写法几乎一样,差别集中在“协议细节 + 生成器用哪个包”:
对比项 |
OData V2 |
OData V4 |
|---|---|---|
典型后端 |
S/4HANA 大量标准 API,如 Business Partner( |
CAP 服务、部分云服务/新 API |
元数据 |
|
同样 |
运行时包 |
|
|
服务路径 |
常见 |
常见 |
集合返回 |
JSON 里常见 |
JSON 里常见 |
分页 |
|
|
生成器 |
|
同上 |
本教程主线用 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 中创建再同步到集群。

图:Kubernetes/Helm 形态下 SDK 应用的组件关系(来自官方示例仓的架构图)。本教程只走 CF 主线;这张图用于理解「服务绑定 → 目标/认证/连通性」在另一种运行环境里的对应物。
准备工作
本机环境
工具 |
建议版本 |
检查命令 |
说明 |
|---|---|---|---|
Node.js |
22 LTS(最低 22) |
|
Cloud SDK v4 要求 Node 22+;若示例仓锁定 v3,可用 18/20,以 |
npm |
随 Node 附带(10+) |
|
用于安装依赖、跑脚本 |
Git |
2.30+ |
|
稀疏检出示例仓 |
Cloud Foundry CLI |
8.x |
|
登录、创建服务实例、部署、看日志 |
编辑器/IDE |
任意 |
— |
VS Code 等,能装 TypeScript 插件更好 |
curl / jq |
可选 |
|
验证 OData 与 CF 路由 |
node -v # 期望 v22.x 或更高
npm -v
git --version
cf -v
curl --version | head -n 1

注意:原始示例仓 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 服务实例 |
保存并下发目标配置 |
必需(计划 |
XSUAA 实例 |
应用访问 Destination 服务的令牌 |
必需(计划 |
Connectivity 服务实例 |
仅 on-premise 目标需要 |
按场景 |
Cloud Connector |
仅 on-premise 目标需要,部署在客户内网 |
按场景 |
S/4HANA 系统 + 通信用户/通信安排 |
提供 OData 服务 |
必需(可用 mock/沙箱替代) |
业务伙伴读权限 |
通信用户能读取 |
必需 |
没有 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 报错,回到这一步处理。
顺手准备一张“命名小抄”,后面会反复用到,写错一个字符都要折腾半天:
变量 |
本教程示例值 |
用在哪 |
|---|---|---|
应用名 |
|
|
Destination 名 |
|
代码、 |
Destination 实例 |
|
|
XSUAA 实例 |
|
同上 |
本地端口 |
|
|
另外,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 ...。
示例目录 |
适合谁 |
特点 |
|---|---|---|
|
本教程主线 |
CAP + Cloud SDK,含 |
|
想一次看全 4 种调用端点 |
云端、on-premise、主体传播多端点 + approuter,需 destination/xsuaa/connectivity 三个实例 |
|
想做多租户 SaaS |
配套多租户教程,含 approuter 与 |
|
只想看 HTTP Client 用法 |
|
|
想定制韧性中间件 |
|
|
想部署到 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)"
脚本 |
作用 |
什么时候用 |
|---|---|---|
|
用 EDMX 生成 OData 客户端 |
|
|
部署 CDS 模型到本地数据库 |
首次本地运行前 |
|
开发模式启动应用(含热重载) |
本地调试 |
|
把 TypeScript 编译为 JavaScript |
部署前构建 |
|
打包部署产物 |
部署前打包 |
|
串起 |
一键部署到 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 通信管理为例:
打开 Communication Systems(通信系统) 应用,新建一条通信系统:填写系统 ID、主机名(
<your-s4-host>)、可选 SAP Client。在通信系统里创建 Communication User(通信用户):设置用户名/密码(或客户端证书),并给它分配能读取业务伙伴的业务角色/授权。
打开 Communication Arrangements(通信安排) 应用,新建通信安排:
Scenario 选择业务伙伴相关场景(常见为
SAP_COM_0008,不同版本名称可能是“Business Partner, Customer and Supplier Integration”,以你系统里搜索 Business Partner 出现的场景为准);选择刚建的通信系统;
Inbound 认证方式选
Basic(用户/密码)或OAuth 2.0(客户端凭据);勾选/启用
API_BUSINESS_PARTNER相关服务,记下它显示的服务路径。
保存并确认通信安排状态为 Active。

创建通信系统时常用字段: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 的场景才要额外处理)。
字段/对象 |
示例值 |
说明 |
|---|---|---|
通信系统主机名 |
|
必须是 BTP 侧可达的地址 |
通信用户 |
|
只用技术用户,不要用个人账号 |
认证方式 |
Basic(用户/密码) |
后续 Destination 选 |
通信场景 |
|
业务伙伴集成;以你系统实际场景编号为准 |
服务路径 |
|
服务根路径,后面拼实体集 |
验证(在能访问该系统的网络里执行;不要把你的密码留在 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 在页面下方的同名区域逐行添加,保存前不要漏。

字段 |
示例值 |
必填/说明 |
|---|---|---|
Name |
|
必填;代码里用的就是这个名字,大小写敏感 |
Type |
|
必填 |
Description |
|
可选,写清用途 |
URL |
|
必填;只填 scheme + host + port,不要带服务路径 |
Proxy Type |
|
必填 |
Authentication |
|
与 S/4HANA 通信安排保持一致 |
User |
|
|
Password |
通信用户密码 |
只存在 Destination 里,不落代码 |
Additional Properties |
|
按系统需要;client 号不对会查不到数据 |
如果选择 OAuth2ClientCredentials,还需要填:
字段 |
从哪里取 |
|---|---|
Token Service URL |
通信安排的 OAuth 2.0 客户端信息里复制(形如 |
Client ID / Client Secret |
通信安排中创建的 OAuth 2.0 客户端 |
Token Service User / Password |
通常留空或按令牌服务要求填写 |
填写时的三条硬规则:
URL 只到 host。把
/sap/opu/odata/sap/API_BUSINESS_PARTNER写进 URL 是最常见的错误,结果就是 404;服务路径应由生成客户端的basePath或请求的url提供。Name 一旦定下就不要改。代码、
destinations环境变量、文档全用它;大小写和连字符都算数。认证方式与通信安排一一对应。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

三个实例的对应关系如下,创建时对照检查,避免名字/计划写错:
实例名(示例仓约定) |
服务 |
计划 |
绑定到应用后提供什么 |
|---|---|---|---|
|
|
|
Destination 服务的访问凭据,SDK 用它按名取目标 |
|
|
|
换取访问 Destination 服务令牌所需的 client id/secret |
|
|
|
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"
}
}
生成物 |
用途 |
|---|---|
|
客户端入口(导出 |
|
|
|
类型定义与编译产物(启用 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;
}
现象 |
原因 |
处理 |
|---|---|---|
|
认证方式/密码/证书错误,通信用户被锁 |
在 BTP 里重测 Destination 连接;核对通信安排认证方式 |
|
认证成功但无权限 |
给通信用户补业务角色/授权,确认服务已在通信安排启用 |
|
URL/路径/Client 不对 |
Destination URL 只到 host;检查 |
|
查询参数非法( |
用 |
|
后端或网关临时故障/超时 |
先看响应体;配合步骤 11 的超时+重试 |
|
网络、证书链、代理问题 |
公网查白名单/证书;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 临时失败 |
是 |
典型瞬时故障,重试大概率恢复 |
|
是 |
后端或网关临时故障;结合响应体判断 |
|
有条件 |
尊重服务端限流,配合退避;不要固定高频重试 |
|
否 |
请求/认证/权限/路径错误,重试不会变好 |
熔断器已打开 |
否 |
直接快速失败,等恢复窗口后再试 |
使用要点:
顺序:超时在前(防止一个请求挂太久),重试在后(覆盖所有失败路径);
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 |
|---|---|---|
运行时包 |
|
|
EDMX 来源 |
服务商/API Hub 下载 V2 规格 |
下载 V4 规格,不要混用 |
服务路径 |
|
按 V4 服务的实际路径(CAP 常见 |
|
V2 里 select 导航属性常隐式展开 |
V4 中 |
分页续页 |
|
可能返回 |
日期时间类型 |
|
|
下载规格时先确认版本: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 服务演练,流程不变:
按该 mock 项目 README 启动服务(默认监听
http://localhost:3000);把本地
destinations环境变量里的url改成http://localhost:3000,authentication改成NoAuthentication:
export destinations='[{"name":"S4HANA_BUSINESS_PARTNER","url":"http://localhost:3000","authentication":"NoAuthentication"}]'
重新执行
node scripts/verify-bp.mjs,确认能拿到模拟数据;部署步骤仍可照做:只验证“应用能上 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

几个部署期的注意点:
如果 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/1running;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
部署前还要做三件事:
把仓库里所有
<REPLACE-ME>占位符替换成实际值(Destination 名称、子域名等)——搜索REPLACE-ME就能找全;修改
approuter/xs-app.json,改用与你子账户关联的 IdP,或按 README 说明不使用 IdP;在根目录和
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 |
示例仓能拉到 |
|
2 |
依赖与客户端生成 |
|
3 |
Destination 配置正确 |
BTP 里 |
4 |
服务实例已绑定 |
|
5 |
本地最小调用成功 |
|
6 |
类型安全客户端可用 |
查询代码能编译/运行,返回实体数组 |
7 |
分页正确 |
翻页无重复、无遗漏;页大小与 |
8 |
错误分类有效 |
错误名称/URL 时能输出 401/403/404/网络错误分类日志 |
9 |
韧性中间件生效 |
不可达目标时能超时/重试后失败,不无限挂起 |
10 |
云端部署成功 |
|
11 |
云端调用成功 |
|
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 空间 |
|
路由一并删除 |
Destination 实例 |
CF 空间 |
|
删除前确认无绑定 |
XSUAA 实例 |
CF 空间 |
|
同上 |
Connectivity 实例 |
CF 空间 |
|
未使用则不需要创建 |
Destination 配置 |
BTP Cockpit |
Connectivity → Destinations → 删除 |
删除后本地无法再按名解析 |
通信用户/通信安排 |
S/4HANA Fiori |
通信管理里删除或停用 |
若其他集成也在用,不要直接删,先确认影响 |
本地仓库与凭据 |
本机 |
删仓库、 |
检查 shell 历史里是否残留密码 |
常见问题
现象 |
原因 |
处理 |
|---|---|---|
|
名称不一致;服务实例未绑定;本地未设置 |
逐字核对 Destination 名称; |
本地成功、云端 401 |
云端 Destination 认证方式与通信安排不一致;服务绑定指向了另一套 Destination 配置 |
在 BTP 里 |
|
XSUAA 实例缺失或 |
确认 |
|
通信用户权限不足;通信安排未启用该服务 |
补业务角色/授权;在通信安排中启用 |
|
Destination URL 带了服务路径;服务路径拼错; |
URL 只填 |
on-premise 目标云端超时、本地正常 |
缺 connectivity 实例;Cloud Connector 未映射/未信任;证书问题 |
创建并绑定 connectivity;Cloud Connector 添加系统映射与访问控制;检查 TLS 信任 |
|
Node 版本不符;EDMX 缺失或路径不对; |
切到 Node 22(或仓内 engines 要求);检查 |
生成客户端后编译报“找不到模块” |
导入路径/生成目录名不对;OData V2/V4 包混用 |
看 |
改了 Destination 但云端仍用旧配置 |
SDK v4 默认启用 Destination 缓存 |
用 |
分页有重复/漏数据 |
按页取数但没有稳定排序;分页期间数据被修改;页大小超过服务端上限 |
用 |
重试把 401/403 也重试了,越试越慢 |
未区分错误类型,盲目重试 4xx |
只对网络错误和 5xx 重试;4xx 直接暴露给调用方;校准超时与熔断参数 |
|
内存不足;启动命令与产物不匹配;Node 版本被 buildpack 选错 |
|
用沙箱 API 直接 401 |
沙箱要求 |
代码里 |
其他示例索引
本案例的原始资料是一批示例的合集。主线之外,其余示例按需取用:
示例目录 |
一句话场景 |
主要命令 |
|---|---|---|
|
CF 上的多端点应用(云端/on-premise/主体传播),带 approuter 与 Cypress e2e |
根目录与 |
|
多租户参考实现(approuter + service-config),部署前替换 |
各组件 |
|
Kubernetes 端到端应用(Dockerfile、pipeline、e2e) |
改镜像/ingress 后 |
|
Kubernetes/Helm 版示例,含 SAP BTP Operator 与服务定义 |
|
|
通用 HTTP Client 的可运行示例(以测试形式组织) |
|
|
自定义韧性中间件示例 |
参考 |
官方原文(参考)
Cloud SDK for JavaScript 文档:https://sap.github.io/cloud-sdk/docs/js/overview
入门教程(从零建应用并部署 CF):https://sap.github.io/cloud-sdk/docs/js/tutorials/getting-started/introduction
Destination 与认证:https://sap.github.io/cloud-sdk/docs/js/features/connectivity/destinations
HTTP Client:https://sap.github.io/cloud-sdk/docs/js/features/connectivity/http-client
OData 客户端生成:https://sap.github.io/cloud-sdk/docs/js/features/odata/generate-client
韧性(超时/重试/熔断):https://sap.github.io/cloud-sdk/docs/js/guides/resilience
升级到 v4:https://sap.github.io/cloud-sdk/docs/js/guides/upgrade-to-version-4
从 CF 迁移到 Kubernetes:https://sap.github.io/cloud-sdk/docs/js/guides/migrate-sdk-application-from-btp-cf-to-kubernetes
S/4HANA Business Partner API(API Hub):https://api.sap.com/api/API_BUSINESS_PARTNER/overview
本文是编者基于上述示例集主线扩写的离线教程:原文提供示例清单、仓库结构与官方命令,本文补齐了环境检查、Destination/通信安排配置、完整可运行代码、逐项验证与排错方法;SDK 具体版本行为(如 v4 要求 Node 22、Destination 默认缓存)以官方文档为准。