为 AWS Transform Custom 设计社区技能：AWS Glue 5.0 升级就绪

为 AWS Transform Custom 设计社区技能：AWS Glue 5.0 升级就绪

TL;DR

我设计了一个拟议的 AWS Transform Custom 社区技能，用于将 Glue 2.0、3.0 和 4.0 仓库升级至 Glue 5.0 就绪。该技能将安全的机械转换与需要人工核实的变更区分开来，生成迁移报告，并保留已兼容的文件不做改动。由于我没有实时 atx 访问权限，本文中的基准数据均明确标注为手动模拟，而非代理执行。该提案已作为 issue #75 开放——尚未合并，也未提交拉取请求。

缺失的数据工程转换

AWS Transform Custom 可跨单个仓库（或通过 AWS Batch 和 Fargate 同时跨数千个仓库）应用代理驱动的代码转换。截至 2026 年 7 月 30 日，其公开示例仓库 aws-samples/aws-transform-custom-samples 中包含三个社区贡献的转换：EKS 版本升级就绪技能、JBoss 到 Spring Boot 迁移，以及 Kubernetes 就绪迁移。它们均未涉及数据工程。

鉴于我的日常工作主要横跨 AWS 数据工程、Databricks 和 Delta Lake，这一空白显然亟待填补。

AWS Transform Custom “技能” 的形态

在编写代码之前，我深入研究了现有的最完善示例 jboss-to-springboot，因为它确立的模式实际上已成为其他两个技能的非书面规范：

• README.md —— 问题描述、技能功能，以及如何通过 atx CLI 调用。这里也明确划定界限：这些是就绪转换。它们修改仓库中的制品——代码和基础设施即代码——但不部署任务、不调用 AWS API 更改运行中的资源，也不声称数据级等价。该区分贯穿下文。
• SKILL.md —— 面向代理的定义：YAML 前言包含触发关键词、目标、明确的非目标、约束、已验证的前后示例、“源代码信号 → 参考文件” 路由表，以及带编号的验证/退出条件清单。
• references/ —— 仅在检测到特定信号时代理才会读取的深度剖析文件。
• BENCHMARKS.md —— 高管摘要表及有据可查、可复现的方法论。

有两个设计选择值得完全沿用。首先，技能会运行条件性 Phase 0，在触碰任何内容前检测哪些迁移阶段实际适用。其次，它们维护一个仅标记类别：代理绝不能自动转换的项——模糊依赖、自定义连接器、非机械行为变更——而应在报告中列出，交由人工决策。这第二点最终成为我构建内容中最重要的部分。

为什么专门针对 Glue 5.0

AWS Glue 5.1 已于 2025 年 11 月正式发布，运行 Spark 3.5.6、Python 3.11、Scala 2.12.18 和 Java 17。Glue 5.0（Spark 3.5.4，Python/Scala/Java 版本相同）仍完全受支持。我将此技能的首个版本——及其所有测试夹具和基准——范围限定为 Glue 5.0，与 issue #75 中的提案保持一致。该技能的结构可干净地扩展至 5.1 作为后续版本；我更希望交付一个经过实际验证的狭窄技能，而非一个包含未经验证声明的宽泛技能。

glue-version-upgrade-readiness 分析 AWS Glue ETL 作业（PySpark 和 Scala）及其 IaC，并将源版本 2.0、3.0 或 4.0 准备至 Glue 5.0。通过 Phase 0 检测标志进行门控，确保每个仓库仅执行相关工作，涵盖：

• Spark 2.4/3.1/3.3 → 3.5 兼容性与现代化模式——已弃用 API（如 registerTempTable，自 Spark 2.0 起弃用但未移除，值得与运行时升级一并清理）、旧版日期时间解析标志及相关 SQL 语义变更
• Python 3.7/3.10 → 3.11 兼容性，包括依赖固定版本提升
• Glue 特定 API 和日志参数变更
• 连接器与数据湖格式更新——较新 Glue 版本中的原生 Iceberg/Delta/Hudi 支持
• Terraform / CloudFormation / CDK 更新以适配新运行时

同时，它故意拒绝自动处理：AWS Marketplace 连接器、已编译/原生依赖，以及任何依赖 Spark 2.x 行为且无清晰机械等价物的内容。这些将写入 MIGRATION_REPORT.md 并附带理由，绝不会被静默迁移。

无实时访问权限下的基准测试

验证技能的预期方式是通过真实 atx CLI 针对预置的测试仓库运行。由于我的环境中没有实时 AWS Transform Custom 访问权限，我没有伪造数据或完全跳过验证，而是用已知、预植的不兼容项填充三个测试夹具仓库——一个 PySpark Glue 2.0 作业、一个 Scala Glue 3.0 作业和一个 Terraform 管理的 Glue 4.0 作业——然后手动逐阶段应用技能，最后使用真实本地工具（Python 3.11、Terraform、cfn-lint 和 sbt）检查结果。

下方的每个数字均标注为“手动模拟，非代理执行”，且该标签保留在公开 issue 中，未在任何地方淡化处理：

测试夹具	检测到的发现	已验证的机械修复	需人工复核项	误报	结果
Glue 2.0 PySpark	5/5	4/4	1/1	0	部分就绪
Glue 3.0 Scala	5/5	3/3	2/2	0	被连接器阻断
Glue 4.0 Terraform	4/4	3/3	1/1	0	部分就绪
总计	14/14	10/10	4/4	0	3/3 控件未变更

这些数字衡量的是针对测试夹具手动应用技能规定阶段的结果。它们并非 AWS Transform Custom 自主执行准确性的度量——我尚无相关数据，且已在数字出现的所有地方说明了这一点。

Scala 结果是我最信任的，正是因为它不是一次干净的通过。该夹具中故意植入了未发布的自定义连接器。技能正确地拒绝猜测替代方案、进行了标记，并且 sbt compile 在完整构建时确实失败——而转换后的源代码本身在隔离的测试环境中可干净编译。若技能在此报告“就绪”，将是错误的结果。

迁移技能不应追求最高通过率，而应追求最高可辩护的通过率。

我还将技能文档中所有嵌入的代码示例——Python、Terraform 和 CloudFormation 片段——通过相同的真实验证器运行，并在每个夹具中包含一个不应变更的对照文件，通过 SHA-256 在前后进行校验。

发现自己的过度延伸

在打开 issue 之前，我针对自己最不自信的两项声明进行了单独的事实核查：AWS 文档是否普遍弃用 Glue DynamicFrames（并非如此——仅在特定的 Lake Formation 细粒度访问控制场景中弃用），以及 CDK 团队是否规定 cdk synth 作为实验性 aws-glue-alpha 模块的稳定性机制。

第二项声明未能成立。CDK 将该模块记录为实验性并警告跨版本可能存在破坏性变更，但并未特别指出合成作为稳定性保证——这是我最初决定要求的验证步骤，最初写成仿佛是 AWS 自己的指导。我在技能文件、参考文档和提案中重新措辞，使该要求现在被正确归属：它是此技能自身的安全门控，而非 CDK 的文档化推荐。

这本身是一项小修正，但这类问题要么在发布前被发现，要么在审查中被维护者发现。自己发现总归更好——这决定了某项声明是需要被反驳，还是可以直接验证。

当前状态

这是一项提案，而非已落地的贡献。完整的技能、参考文档和三个基准测试夹具已在本地构建并验证，但尚未合并——我在此不提供分支链接，因为目前尚无公开分支。根据仓库的贡献指南，重大工作需先在 issue 中讨论，再提交拉取请求，因此当前状态正是如此：issue #75，开放以供维护者反馈。

如果您正在大规模运行 AWS Glue 并遇到自己的 Glue 5.0 或 5.1 迁移边缘案例，我很乐意在 issue 或本文评论中听到您的分享。如果您是首次接触 AWS Transform Custom，community-sourced-transformations/ 是一个真正未被充分探索的入口；除现有 Java 和 Kubernetes 示例外，还有大量贡献空间。