简介：本资源是面向SAP Cloud Platform Integration（CPI）开发者的Groovy脚本实践集合，专为初学者入门与中级开发者提效而设计，解决CPI场景中常见任务重复造轮子、函数查找困难、错误处理无参考等痛点。包内共36个文件，涵盖10个可直接复用的Groovy脚本（如HTTP/SOAP错误体提取、XML/CSV互转、SFTP同步读取、凭证安全读取、自定义Header与日志分级输出等），辅以11份配套Markdown文档（含上下文说明、输入/输出示例及使用提示），以及properties配置、XML模板、header定义等支撑文件，整体仅29KB，轻量易集成。已有912人学习下载，所有脚本均经实际CPI环境验证，附带MIT许可，支持社区共建。读者可即刻获取开箱即用的典型集成场景解决方案、清晰的调试输入输出样例、结构化文档指引，以及可扩展的模板化脚本框架，显著降低Groovy在CPI中的学习门槛与开发试错成本。
1. 这不是 Groovy 语法速查表，而是一套能直接塞进 SAP CPI 生产流程跑通的脚本弹药库
某公司做海外电商订单对接时卡在了「SAP CPI 流程里要动态拼接 EDI 报文头、校验供应商编码格式、再根据国家代码路由到不同后端系统」这一步——用 CPI 内置的 Mapping 或 Content Modifier 根本写不出带分支逻辑和正则校验的复合规则。最后靠一份从 GitHub 拉下来的cpi-groovy-examples项目，把其中validate-and-route.groovy和build-edi-header.groovy两个脚本改了三行参数，当天就上线了。这套资源不是教你怎么写println "Hello"的 Groovy 入门包，而是专为 SAP Cloud Platform Integration 场景打磨的实战脚本集合：覆盖消息头操作、JSON/XML 转换、HTTP 签名生成、错误重试封装、自定义日志埋点等真实集成链路中的黑匣子环节。如果你正在 SAP CPI 控制台里对着 Script Step 发呆，或者刚被客户要求「在不改 IFlow 结构的前提下加个字段脱敏逻辑」，这份资源就是你不用重启 IFlow 就能热插拔的 Groovy 弹药。
2. 项目结构与技术栈：Groovy 在 CPI 环境里的运行边界到底在哪
SAP CPI 的 Groovy 脚本不是独立进程，而是运行在 Java 8（CPI Neo 环境）或 Java 11（CPI Cloud Foundry 环境）JVM 上的嵌入式脚本引擎。它能调用完整的 Java 标准库，但不能加载外部 JAR、不能访问文件系统、不能创建新线程、不能反射调用私有方法——这些限制直接决定了cpi-groovy-examples里所有脚本的写法边界。项目本身是纯 Groovy 源码集合，无构建脚本、无测试框架、无依赖声明，因为 CPI 运行时已预置好com.sap.gateway.ip.core.customdev.util.Message、groovy.json.JsonSlurper、javax.xml.parsers.DocumentBuilder等关键类。它的价值不在“多炫技”，而在“每行代码都踩过 CPI 的坑”。
2.1 目录结构：按 CPI 集成场景归类，而非 Groovy 语法分类
项目采用扁平化目录，所有.groovy文件按实际使用场景分组，而非按语言特性分组：
/cpi-groovy-examples/ ├── header/ # 消息头（Header）操作相关 │ ├── add-correlation-id.groovy # 添加 Correlation ID 到 header │ ├── set-http-headers.gropy # 设置 HTTP 请求头（含 Authorization） │ └── copy-header-to-property.groovy # 将 header 值复制到 exchange property ├── payload/ # 负载（Payload）处理 │ ├── json-to-xml.groovy # JSON 转 XML（带命名空间处理） │ ├── xml-to-json.groovy # XML 转 JSON（处理 CDATA 和属性） │ ├── mask-credit-card.groovy # 信用卡号掩码（正则 + replaceAll） │ └── enrich-with-lookup.groovy # 从 lookup table 获取扩展字段 ├── routing/ # 路由（Routing）逻辑 │ ├── route-by-country-code.groovy # 根据 country code 动态路由 │ └── retry-on-404.groovy # HTTP 404 时触发重试（带指数退避） ├── logging/ # 日志与调试 │ ├── log-payload-size.groovy # 记录 payload 字节数（防超限） │ └── trace-message-flow.groovy # 打印完整 message flow path（含 step name） └── util/ # 工具类（全部为静态方法，无实例化） ├── CryptoUtil.groovy # HMAC-SHA256 签名生成（用于 API 认证） └── DateUtil.groovy # ISO8601 时间格式转换（适配 CPI 默认时区）提示：CPI 中所有 Groovy 脚本必须返回
message对象（类型为com.sap.gateway.ip.core.customdev.util.Message），否则流程中断。所有示例脚本第一行都是def message = message，最后一行都是return message，这是硬性契约。
2.2 CPI 环境下 Groovy 的核心能力图谱
| 能力类别 | CPI 支持情况 | 示例脚本体现 | 注意事项 |
|---|---|---|---|
| Java 互操作 | ✅ 完全支持 | CryptoUtil.groovy中调用javax.crypto.Mac | 必须用import显式引入，不能省略包名 |
| JSON 处理 | ✅JsonSlurper/JsonBuilder | json-to-xml.groovy中解析嵌套 JSON | JsonSlurper默认解析为LinkedHashMap，遍历时 key 顺序保留 |
| XML 处理 | ✅XmlParser/XmlSlurper | xml-to-json.groovy中读取 namespace | XmlParser不支持 XPath，XmlSlurper支持但性能略低 |
| HTTP 调用 | ❌ 不允许HttpURLConnection或HttpClient | 所有脚本均无 HTTP 发起逻辑 | HTTP 调用必须用 CPI 内置的Receiver或Content Modifier+HTTP Adapter |
| 日志输出 | ✅log.*方法 | log-payload-size.groovy中log.info("Size: ${size}") | 日志会出现在 CPI Monitor → Message Processing Logs，级别不可配置 |
| 异常处理 | ✅try/catch，但throw会终止流程 | route-by-country-code.groovy中捕获NullPointerException | 不建议throw new RuntimeException()，应改用message.setProperty("ERROR", "xxx")后交由 CPI 错误处理流 |
2.3 关键依赖与 CPI 版本兼容性
项目未声明任何外部依赖，但隐式依赖以下 CPI 内置类（Neo 环境与 CF 环境均存在）：
com.sap.gateway.ip.core.customdev.util.Message：CPI 消息对象主类，所有脚本操作入口groovy.json.JsonSlurper/groovy.json.JsonBuilder：Groovy 2.4+ 内置，CPI Neo（Java 8）与 CF（Java 11）均提供javax.xml.parsers.DocumentBuilder：Java 标准库，无需额外 importjava.time.format.DateTimeFormatter：Java 8+ 时间 API，在 CF 环境（Java 11）中更稳定
注意：
cpi-groovy-examples中DateUtil.groovy使用SimpleDateFormat而非DateTimeFormatter，是因为 CPI Neo 环境（Java 8）对java.time类的支持存在偶发 ClassLoader 问题。这是血泪经验——某次升级 CPI 补丁后，所有用LocalDateTime.parse()的脚本批量报NoClassDefFoundError，回退到SimpleDateFormat后立即恢复。
3. 核心模块拆解：一个 JSON 转 XML 脚本的完整执行链路
payload/json-to-xml.groovy是项目中最常被二次开发的脚本，它解决的是「上游系统发来扁平 JSON，下游 ERP 系统只认带命名空间的 XML」这一高频痛点。我们逐段拆解其如何在 CPI 环境中安全落地。
3.1 脚本主体：从输入到输出的四步闭环
// json-to-xml.groovy import groovy.json.JsonSlurper import groovy.xml.MarkupBuilder import java.io.StringWriter def message = message def jsonSlurper = new JsonSlurper() def payload = message.getBody(String.class) // Step 1: 解析 JSON，捕获解析异常（CPI 不会自动捕获 JSON 格式错误） def json try { json = jsonSlurper.parseText(payload) } catch (Exception e) { log.error("JSON parse failed: ${e.message}") message.setProperty("ERROR", "Invalid JSON format") return message } // Step 2: 构建 XML 字符串（注意：必须用 StringWriter，不能用 StringBuilder） def writer = new StringWriter() def xml = new MarkupBuilder(writer) xml.'ns0:Order'('xmlns:ns0': 'http://example.com/order') { Header { OrderID(json.orderId ?: 'UNKNOWN') CustomerID(json.customerId ?: 'ANONYMOUS') } Items { json.items?.each { item -> Item { SKU(item.sku) Quantity(item.quantity ?: 0) Price(item.price ?: 0.0) } } } } // Step 3: 将 XML 字符串写回 message body message.setBody(writer.toString()) // Step 4: 设置 Content-Type header，确保下游系统识别为 XML message.setHeader("Content-Type", "application/xml") return message逻辑说明与参数说明：
message.getBody(String.class)：强制将 payload 转为String，避免二进制流导致JsonSlurper解析失败。CPI 中 payload 可能是byte[]或InputStream，此调用会触发自动转换。jsonSlurper.parseText(payload)：parseText比parse更安全，因后者可能尝试解析InputStream导致流关闭异常。writer.toString()：MarkupBuilder必须绑定StringWriter，若用StringBuilder会导致 XML 编码错误（如中文乱码），这是 CPI 环境特有的字符集陷阱。message.setHeader("Content-Type", "application/xml")：CPI 的 HTTP Receiver 会读取此 header 决定请求体编码，不设则默认text/plain，下游系统可能拒收。
3.2 命名空间与 CDATA 的特殊处理
原始脚本仅处理基础 XML，但真实 ERP 接口常要求 CDATA 包裹描述字段。我们在Items/Item块内追加：
// 在 Item 闭包内插入： Description(cdata: json.description ?: '')cdata:是MarkupBuilder的特殊语法，会生成<Description><![CDATA[...]]></Description>。但需注意：cdata:后不能跟其他属性，且值必须为String，若json.description为null，cdata: null会抛NullPointerException，因此必须用?: ''提供空字符串兜底。
3.3 性能边界：为什么不用 XmlParser？
有开发者尝试用XmlParser先解析再修改，但在 CPI 中这是高危操作：
// ❌ 危险写法（不要用！） def xmlParser = new XmlParser() def doc = xmlParser.parseText(xmlString) // 此处可能 OOM doc.'**'.findAll { it.name() == 'Price' }.each { it.setValue(it.text().toBigDecimal() * 1.1) }原因：XmlParser会将整个 XML 加载为内存 DOM 树，当 payload 超过 1MB 时极易触发 CPI 内存限制（默认 256MB heap），导致OutOfMemoryError。而MarkupBuilder是流式生成，内存占用恒定，这才是 CPI 场景的正确姿势。
4. 避坑指南：CPI Groovy 脚本的 5 个真实翻车现场
在多个客户项目中，我们发现 80% 的 Groovy 脚本故障集中在以下五类。这些不是理论风险，而是监控日志里反复出现的 ERROR 级别报错。
4.1 现象：脚本执行超时（Timeout），CPI Monitor 显示Script execution exceeded maximum allowed time
原因：Groovy 脚本中存在隐式死循环或正则回溯爆炸。例如mask-credit-card.groovy中使用payload.replaceAll(/(\d{4})\d{8}(\d{4})/, '$1****$2')，当 payload 含大量数字且无空格分隔时，正则引擎会进行指数级回溯。
解决：改用非贪婪匹配replaceAll(/(\d{4})\d{8}(\d{4})/, '$1****$2')并添加长度校验if (payload.length() > 10000) { log.warn("Payload too long, skip masking"); return message }。
4.2 现象：java.lang.ClassNotFoundException: groovy.json.JsonSlurper
原因：脚本开头漏写import groovy.json.JsonSlurper，且 CPI 环境不会像本地 Groovy Shell 那样自动导入。
解决：所有import语句必须显式写出，且放在脚本最顶部（在def message = message之前）。CPI 不支持import static。
4.3 现象：XML 输出中中文显示为你好（Unicode 实体）
原因：MarkupBuilder默认对所有非 ASCII 字符进行 HTML 实体编码。
解决：在MarkupBuilder初始化时传入new StringWriter(new OutputStreamWriter(new ByteArrayOutputStream(), "UTF-8"))，或更简单——在 CPI 的 IFlow 中，将该 Script Step 的Content-Typeheader 设为application/xml;charset=UTF-8，让接收方正确解码。
4.4 现象：log.info()输出在 Monitor 中完全不可见
原因：CPI 日志级别默认为WARN，INFO级别日志被过滤。
解决：改用log.warn("DEBUG: ${payload.substring(0, Math.min(100, payload.length()))}")，或在 CPI Cockpit → Monitoring → Log Configuration 中临时提升日志级别（生产环境慎用）。
4.5 现象：message.setProperty("key", value)后，下游 Content Modifier 无法读取该 property
原因：setProperty设置的是Exchange Property，而 Content Modifier 默认读取Message Header。两者存储位置不同。
解决：统一使用message.setHeader("key", value)，或在 Content Modifier 中勾选Use Exchange Properties选项（CPI UI 中明确标注）。
5. 二次开发实战：给路由脚本增加「灰度开关」并验证其生效
routing/route-by-country-code.groovy是项目中最具改造价值的脚本。客户提出新需求：「下周上线新版本路由逻辑，但先对 5% 的加拿大订单走新逻辑，其余走旧逻辑」。这需要在不改动 IFlow 结构、不新增步骤的前提下，给脚本注入灰度能力。
5.1 改造思路：用 CPI Lookup Table 实现动态开关
CPI 提供Lookup Table功能，可将键值对存为 CSV 并在脚本中通过com.sap.it.api.lookup.LookupService读取。我们将灰度比例存为gray_ratio:0.05，国家白名单存为ca_enabled:true。
第一步：在 CPI Cockpit 创建 Lookup Table
- 名称：
ROUTING_GRAY_CONFIG - 内容（CSV 格式）：
key,value gray_ratio,0.05 ca_enabled,true
第二步：修改route-by-country-code.groovy，注入灰度逻辑
import com.sap.it.api.ITApiFactory import com.sap.it.api.lookup.LookupService def message = message def country = message.getHeader("countryCode", String.class) ?: "UNKNOWN" // Step 1: 获取 Lookup Service 实例（CPI 内置，无需配置） def lookupService = ITApiFactory.getApi(LookupService.class, null) // Step 2: 读取灰度配置（失败时降级为 0，即全走旧逻辑） def grayRatioStr = lookupService.lookup("ROUTING_GRAY_CONFIG", "gray_ratio") ?: "0" def grayRatio = grayRatioStr.toDouble() def caEnabled = "true".equals(lookupService.lookup("ROUTING_GRAY_CONFIG", "ca_enabled")) // Step 3: 生成灰度标识（基于订单 ID 哈希，保证同一订单始终走同一路由） def orderId = message.getHeader("orderId", String.class) ?: "NO_ID" def hash = orderId.hashCode() % 100 def isGray = (hash >= 0 ? hash : -hash) < (grayRatio * 100) // Step 4: 分支路由（新逻辑仅对加拿大 + 灰度命中生效） if (country == "CA" && caEnabled && isGray) { log.info("Route to NEW backend for CA order ${orderId} (gray)") message.setHeader("CamelDestinationEndpoint", "https://new-backend.example.com/api/order") } else { log.info("Route to LEGACY backend for ${country} order ${orderId}") message.setHeader("CamelDestinationEndpoint", "https://legacy-backend.example.com/api/order") } return message关键点说明：
ITApiFactory.getApi(LookupService.class, null)：第二个参数为null表示使用默认配置，CPI 自动注入。hashCode() % 100：用订单 ID 哈希取模模拟随机，比Math.random()更可控（避免每次执行结果不同）。isGray判断中(hash >= 0 ? hash : -hash)：hashCode()可能为负数，取绝对值保证范围在[0,99]。
5.2 验证方法：三步确认灰度真实生效
- Mock 数据验证：在 CPI Test Tool 中发送 100 个不同
orderId的请求（如order-001到order-100），检查 Monitor 中CamelDestinationEndpointheader 是否约 5 个为new-backend。 - 日志交叉验证：在脚本中加入
log.info("Gray check: orderId=${orderId}, hash=${hash}, isGray=${isGray}")，在 Monitor 中搜索Gray check，确认isGray=true的数量符合预期。 - 生产环境熔断验证：临时将
ROUTING_GRAY_CONFIG中gray_ratio改为0，观察流量是否 100% 切回旧后端——这是灰度开关的终极保险。
从那以后我每次加灰度逻辑，都强制走一遍「Mock 100 次 → 查日志 → 改配置验证熔断」三步。不是信不过代码，是信不过自己没考虑全 CPI 的异步日志延迟和缓存机制。希望帮到你。
本文还有配套的精品资源，点击获取
