简介本资源是面向SAP Cloud Platform IntegrationCPI开发者的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 8CPI Neo 环境或 Java 11CPI 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/JsonBuilderjson-to-xml.groovy中解析嵌套 JSONJsonSlurper默认解析为LinkedHashMap遍历时 key 顺序保留XML 处理✅XmlParser/XmlSlurperxml-to-json.groovy中读取 namespaceXmlParser不支持 XPathXmlSlurper支持但性能略低HTTP 调用❌ 不允许HttpURLConnection或HttpClient所有脚本均无 HTTP 发起逻辑HTTP 调用必须用 CPI 内置的Receiver或Content ModifierHTTP 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.MessageCPI 消息对象主类所有脚本操作入口groovy.json.JsonSlurper/groovy.json.JsonBuilderGroovy 2.4 内置CPI NeoJava 8与 CFJava 11均提供javax.xml.parsers.DocumentBuilderJava 标准库无需额外 importjava.time.format.DateTimeFormatterJava 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为nullcdata: 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 现象脚本执行超时TimeoutCPI 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 输出中中文显示为#x4F60;#x597D;Unicode 实体原因MarkupBuilder默认对所有非 ASCII 字符进行 HTML 实体编码。解决在MarkupBuilder初始化时传入new StringWriter(new OutputStreamWriter(new ByteArrayOutputStream(), UTF-8))或更简单——在 CPI 的 IFlow 中将该 Script Step 的Content-Typeheader 设为application/xml;charsetUTF-8让接收方正确解码。4.4 现象log.info()输出在 Monitor 中完全不可见原因CPI 日志级别默认为WARNINFO级别日志被过滤。解决改用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确认isGraytrue的数量符合预期。生产环境熔断验证临时将ROUTING_GRAY_CONFIG中gray_ratio改为0观察流量是否 100% 切回旧后端——这是灰度开关的终极保险。从那以后我每次加灰度逻辑都强制走一遍「Mock 100 次 → 查日志 → 改配置验证熔断」三步。不是信不过代码是信不过自己没考虑全 CPI 的异步日志延迟和缓存机制。希望帮到你。本文还有配套的精品资源点击获取