用途:该技能用于创建或修改 OpenRewrite 的 YAML 处理配方,以测试先行方式开发生产级配方,对 YAML 文件(如 GitHub Actions、Kubernetes 清单、CI 配置及通用 YAML)进行搜索或转换。核心原则为:先写测试(RED)、最小实现(GREEN)、再套用 OpenRewrite 惯例重构(REFACTOR)。
主要能力与工作流程:
- RED:使用 OpenRewrite 测试框架编写带前后 YAML 示例的失败测试,覆盖正常路径、边界情况(空文件、缺失键、空值)、无操作场景,以及多文档 YAML。
- 架构决策:优先考虑通过组合现有配方(声明式 YAML 编排,置于 src/main/resources/META-INF/rewrite/)实现;无法满足时再使用命令式 Java Visitor。
- GREEN:最小实现使测试通过。声明式配方常用 org.openrewrite.yaml.search.FindKey、FindValue、ChangeKey、ChangeValue、DeleteKey、MergeYaml、CopyValue 等。命令式配方可继承 YamlIsoVisitor(不改变树结构时)或 YamlVisitor(可能改变结构时)。可用 ./scripts/init_recipe.py <RecipeName> 生成样板。
- REFACTOR:套用 OpenRewrite 惯例,包括 Trait 使用、配方组合、参数化(@Option 注解)、预条件、身份检查以避免无谓改动、尽量保留格式与注释。
- 文档:提供 displayName、支持 markdown 的 description、参数说明与前后示例。
使用方法:按上述五阶段推进,命令式配方中可用 JsonPathMatcher(如 "$.jobs..steps[].uses")匹配,访问映射项时先判断键名再安全读取 Yaml.Scalar 值,始终调用 super 方法、用 withX() 返回修改副本而非直接改动 LST 元素。可运行 ./scripts/validate_java8.py src/ 校验 Java 8 兼容性;若存在 {repository_root}/gradle/licenseHeader.txt,需将其内容(替换 ${year} 为当前年份)作为新建 Java 配方文件头,并用 ./scripts/add_license_header.sh 添加。
适用场景:为 YAML 结构构建搜索或转换配方,处理 GitHub Actions、K8s、CI 等配置。
限制:仅支持 Java 8 兼容写法,禁止 switch 表达式、模式匹配、var、文本块等 Java 9+ 特性。不适用于通用 YAML 编辑(应使用标准 Edit 工具)、非 OpenRewrite 转换工具、Java 8 以上版本以及 OpenRewrite 生态之外的通用代码重构。