SuperAPI AI 工具集

recipe-writer

编程与开发

查看项目

更新于 10-16 05:57

技能介绍

用途

recipe-writer 是一个用于编写 OpenRewrite 配方的技能,目标是帮助开发者以测试优先的方式创建生产质量的 OpenRewrite 配方,实现自动化代码重构。它覆盖声明式(declarative)、Refaster 和命令式(imperative)三类配方,并聚焦 Java 与 YAML 转换。

核心原则:先写测试(RED),最小实现(GREEN),再应用 OpenRewrite 惯用法(REFACTOR)。

适用场景

技能明确列出以下应显式调用的情况:

  • 规划配方:为某个用例确定最佳配方类型。
  • 实现配方:编写配方类、访问器和 JavaTemplate 代码。
  • 编写测试:使用 RewriteTest 创建全面测试覆盖。
  • YAML 转换:GitHub Actions、Kubernetes 清单、CI/CD 配置。
  • Java 重构:代码迁移、API 更新、框架现代化。
  • 调试配方:排查访问器行为、类型检查或前置条件问题。
  • 转换配方类型:分析命令式配方能否改为声明式。
  • 理解 OpenRewrite 概念:学习 LST、cursor、trait 或扫描模式。

不适用场景

技能明确列出以下不应调用的情况:

  • 一般 Java 编程问题(除非专门涉及 OpenRewrite LST 操作)。
  • 普通 YAML 编辑(应使用标准编辑工具直接修改文件)。
  • 运行 OpenRewrite 配方(本技能用于编写配方,而非执行配方)。
  • 构建工具配置(除非直接涉及配方发布/分发)。
  • 一般重构问题(仅用于 OpenRewrite 配方实现)。
  • 阅读/理解现有代码(除非分析配方实现)。

配方类型选择

技能提供决策树:

  1. 能否组合现有配方?是 → 使用声明式 YAML。
  2. 否 → 是否为简单表达式/语句替换?是 → 使用 Refaster 模板。
  3. 否 → 是否需要自定义逻辑或条件变更?是 → 使用命令式 Java 配方。
  4. 仍不确定 → 从声明式开始,必要时回退到命令式。

三类配方对比:

  • 声明式 YAML:速度最快、复杂度最低,用于组合现有配方,例如框架迁移、标准重构。
  • Refaster 模板:速度快、复杂度低到中,用于表达式/语句替换,例如 API 更新、方法调用变更。
  • 命令式 Java:速度较慢、复杂度高,用于复杂转换、条件逻辑,例如自定义分析、YAML LST 操作。

决策规则:能声明式就声明式;简单替换用 Refaster;仅在必要时用命令式。

测试优先开发工作流

技能定义六阶段流程:

  1. RED:先写失败测试。对 Java 配方使用 RewriteTest 实现 defaults 与 rewriteRun;对 YAML 配方同样使用 RewriteTest。测试清单包括:快乐路径、边界情况(null、空文件、缺失元素)、无操作场景、多文档 YAML、真实示例,并确认测试初始为失败(RED)。
  2. DECIDE:选择配方类型。
  3. GREEN:最小实现。声明式配方放在 src/main/resources/META-INF/rewrite/;命令式 Java 配方可使用 ./templates/ 下的模板,并用 ./scripts/init_recipe.py <RecipeName> 生成样板;YAML 配方可扩展 YamlIsoVisitor。
  4. REFACTOR:应用 OpenRewrite 惯用法,包括 trait 使用、配方组合、命名约定、性能考虑、YAML 特定重构。
  5. DOCUMENT:添加元数据与示例,包括 displayName、description(支持 markdown)、@Option 文档、Javadoc 与命名约定。
  6. VALIDATE:生产就绪检查,包括测试通过、边界处理、格式/注释保留、文档清晰、幂等性;完整清单见 ./references/checklist-recipe-development.md(200+ 项)。许可证头检查 {repository_root}/gradle/licenseHeader.txt,存在则用 ./scripts/add_license_header.sh 添加。

实现模式

技能提供 Java 配方快速参考:使用 @Value 与 @EqualsAndHashCode(callSuper = false) 定义配方类,@Option 注解参数,getVisitor() 返回新实例;访问器继承 JavaIsoVisitor,始终调用 super 遍历树,先判断是否需要变更,再使用 JavaTemplate 或 LST 修改。YAML 配方示例继承 YamlIsoVisitor,重写 visitMappingEntry,匹配键并安全访问值。

限制

资料未提供该技能的收费、价格、平台支持范围、具体安装步骤或效果保证等信息,这些内容暂未提供。