本文深入探讨了如何利用OpenRewrite框架，针对Java代码中具有特定注解组合（例如`@NotNull`和`@RequestParam`）的方法参数进行精细化改造。我们将介绍声明式和命令式两种配方（Recipe）的实现方式，重点演示如何通过命令式配方结合AST游标（Cursor）机制，实现对代码元素的上下文感知式修改，从而避免常见的`UncaughtVisitorException`，并提供详细的代码示例及测试方法。
OpenRewrite配方：精准修改方法参数注解
OpenRewrite是一个强大的自动化代码重构工具，通过编写配方（Recipe）来识别和修改代码模式。在实际开发中，我们经常需要对代码进行有条件的、细粒度的修改，例如只修改同时带有@NotNull和@RequestParam注解的方法参数，为其@RequestParam注解添加required = true属性。本文将详细介绍如何实现这一目标。
1. 遇到的挑战与问题分析
在尝试对特定代码片段应用OpenRewrite配方时，一个常见的误区是直接在自定义Visitor中调用另一个配方的Visitor。例如，在遍历方法参数时，如果直接在J.VariableDeclarations上调用AddOrUpdateAnnotationAttribute配方的Visitor，可能会遇到org.openrewrite.UncaughtVisitorException: java.lang.IllegalStateException: Expected to find a matching parent for Cursor{Annotation->root}的错误。
这个错误的原因在于，AddOrUpdateAnnotationAttribute配方的Visitor在执行时，期望其上下文（通过Cursor获取）是一个注解（J.Annotation）或其父级是注解。然而，当我们在J.VariableDeclarations的上下文中直接调用它时，Cursor的路径可能不匹配其预期，导致上下文错误。正确的做法是，当我们在遍历到目标注解时，再将修改操作委托给子配方的Visitor，并传递正确的Cursor。
2. 声明式配方（Declarative Recipe）：简单但缺乏灵活性
对于简单的、无条件的代码修改，声明式配方是一种快速有效的方法。你可以通过一个YAML文件定义配方，并结合OpenRewrite的构建插件（Maven或Gradle）来应用。
示例：在所有@RequestParam上添加required = true
创建一个名为rewrite.yml的文件：
type: specs.openrewrite.org/v1beta/recipe
name: org.example.MandatoryRequestParameter
displayName: Make Spring `RequestParam` mandatory
description: Add `required` attribute to `RequestParam` and set the value to `true`.
recipeList:
- org.openrewrite.java.AddOrUpdateAnnotationAttribute:
annotationType: org.springframework.web.bind.annotation.RequestParam
attributeName: required
attributeValue: "true"集成到Maven项目：
在pom.xml中添加OpenRewrite Maven插件：
org.openrewrite.maven rewrite-maven-plugin 4.38.0 org.example.MandatoryRequestParameter org.openrewrite.recipe rewrite-spring 5.3.0
局限性： 这种方式会将required = true应用到所有@RequestParam注解上，无法实现针对特定条件（如同时存在@NotNull）的修改。
3. 命令式配方（Imperative Recipe）：实现精细化控制
当需要根据复杂的条件来决定是否应用修改时，命令式配方是更合适的选择。它允许我们通过编写Java代码来遍历抽象语法树（AST），并利用Cursor来获取当前代码元素的上下文信息。
目标： 仅为同时带有@NotNull和@RequestParam注解的方法参数，将其@RequestParam注解的required属性设置为true。
核心思路：
- 创建一个主Visitor，继承JavaIsoVisitor。
- 重写visitAnnotation方法，因为我们要修改的是注解本身。
- 在visitAnnotation中，首先判断当前注解是否为@RequestParam。
- 通过getCursor().getParent().getValue()向上导航，获取到当前注解所属的J.VariableDeclarations（即方法参数）。
- 检查该J.VariableDeclarations是否同时包含@NotNull注解。
- 如果条件满足，则将修改操作委托给AddOrUpdateAnnotationAttribute配方自身的Visitor，并传递当前的Cursor。
实现步骤：
import org.openrewrite.ExecutionContext;
import org.openrewrite.Recipe;
import org.openrewrite.TreeVisitor;
import org.openrewrite.java.AddOrUpdateAnnotationAttribute;
import org.openrewrite.java.JavaIsoVisitor;
import org.openrewrite.java.JavaVisitor;
import org.openrewrite.java.UsesType;
import org.openrewrite.java.tree.J;
import org.openrewrite.java.tree.JavaType;
import org.openrewrite.java.tree.TypeUtils;
import javax.validation.constraints.NotNull; // 导入此注解以供检查
public class MandatoryRequestParameter extends Recipe {
private static final String REQUEST_PARAM_FQ_NAME = "org.springframework.web.bind.annotation.RequestParam";
private static final String NOT_NULL_FQ_NAME = "javax.validation.constraints.NotNull"; // NotNull注解的完全限定名
@Override
public @NotNull String getDisplayName() {
return "Make Spring RequestParam mandatory conditionally";
}
@Override
public String getDescription() {
return "Adds 'required=true' to @RequestParam annotations on method parameters that also have @NotNull.";
}
@Override
protected TreeVisitor getSingleSourceApplicableTest() {
// 优化：只有当源文件引用了RequestParam或NotNull注解时才运行此Visitor
return new UsesType<>(REQUEST_PARAM_FQ_NAME);
}
@Override
protected @NotNull JavaVisitor getVisitor() {
// 预先创建AddOrUpdateAnnotationAttribute的Visitor实例
// 这样可以避免在每次visitAnnotation时都创建新实例
JavaIsoVisitor addAttributeVisitor = new AddOrUpdateAnnotationAttribute(
REQUEST_PARAM_FQ_NAME, "required", "true", false
).getVisitor();
return new JavaIsoVisitor() {
@Override
public J.Annotation visitAnnotation(J.Annotation annotation, ExecutionContext ctx) {
J.Annotation a = super.visitAnnotation(annotation, ctx);
// 1. 检查当前注解是否为 @RequestParam
if (!TypeUtils.isOfClassType(a.getType(), REQUEST_PARAM_FQ_NAME)) {
return a;
}
// 2. 通过Cursor获取其父级，即J.VariableDeclarations（方法参数声明）
// 确保父级是J.VariableDeclarations类型
J.VariableDeclarations variableDeclaration = getCursor().getParent(2).getValue(); // 向上两级，Annotation -> J.Annotation.Arguments -> J.VariableDeclarations
if (variableDeclaration == null) {
return a; // 如果无法获取到VariableDeclarations，则返回
}
// 3. 检查该方法参数是否同时带有 @NotNull 注解
boolean hasNotNull = variableDeclaration.getLeadingAnnotations().stream()
.anyMatch(ann -> TypeUtils.isOfClassType(ann.getType(), NOT_NULL_FQ_NAME));
if (hasNotNull) {
// 如果条件匹配，则将修改操作委托给预先创建的addAttributeVisitor
// 关键在于传递当前的a和ctx以及getCursor()，确保上下文正确
return (J.Annotation) addAttributeVisitor.visit(a, ctx, getCursor());
}
return a;
}
};
}
} 代码解释：
- REQUEST_PARAM_FQ_NAME 和 NOT_NULL_FQ_NAME：定义了@RequestParam和@NotNull注解的完全限定名。
- getSingleSourceApplicableTest()：这是一个优化点，UsesType会检查源文件是否引用了指定的类型。如果未引用，则不会运行主Visitor，从而提高性能。
- addAttributeVisitor：AddOrUpdateAnnotationAttribute配方被实例化一次，并获取其内部的Visitor。
- visitAnnotation(J.Annotation annotation, ExecutionContext ctx)：我们在这里拦截所有注解。
- TypeUtils.isOfClassType(a.getType(), REQUEST_PARAM_FQ_NAME)：判断当前注解是否为@RequestParam。
- getCursor().getParent(2).getValue()：这是关键一步。getCursor()获取当前AST节点的游标。getParent()方法可以向上导航到父节点。对于一个注解（J.Annotation），它的直接父节点通常是J.Annotation.Arguments（如果注解有参数），再向上才是J.VariableDeclarations。因此，这里使用getParent(2)来获取方法参数声明。
- variableDeclaration.getLeadingAnnotations().stream().anyMatch(...)：遍历方法参数的所有前置注解，检查是否存在@NotNull。
- addAttributeVisitor.visit(a, ctx, getCursor())：如果所有条件都满足，我们不直接修改a，而是将当前注解a、执行上下文ctx和当前游标getCursor()传递给addAttributeVisitor进行处理。这确保了AddOrUpdateAnnotationAttribute配方在正确的AST上下文下执行，避免了UncaughtVisitorException。
4. 编写测试用例
使用OpenRewrite的测试框架可以方便地验证配方的行为。
import org.junit.jupiter.api.Test;
import org.openrewrite.java.JavaParser;
import org.openrewrite.test.RecipeSpec;
import org.openrewrite.test.RewriteTest;
import static org.openrewrite.java.Assertions.java;
class MandatoryRequestParameterTest implements RewriteTest {
@Override
public void defaults(RecipeSpec spec) {
spec.recipe(new MandatoryRequestParameter())
.parser(JavaParser.fromJavaVersion().classpath("spring-web", "validation-api")); // 确保classpath包含相关依赖
}
@Test
void requiredRequestParamWithNotNull() {
rewriteRun(
java(
"""
import org.springframework.web.bind.annotation.RequestParam;
import javax.validation.constraints.NotNull;
class ControllerClass {
public String sayHello (
@NotNull @RequestParam(value = "name") String name, // 应该被修改
@RequestParam(value = "lang") String lang, // 不应被修改
@NotNull String address, // 不应被修改，因为它不是RequestParam
@NotNull @RequestParam(value = "age") Long age // 应该被修改
) {
return "Hello";
}
}
""",
"""
import org.springframework.web.bind.annotation.RequestParam;
import javax.validation.constraints.NotNull;
class ControllerClass {
public String sayHello (
@NotNull @RequestParam(required = true, value = "name") String name,
@RequestParam(value = "lang") String lang,
@NotNull String address,
@NotNull @RequestParam(required = true, value = "age") Long age
) {
return "Hello";
}
}
"""
)
);
}
}测试用例说明：
- defaults(RecipeSpec spec)：配置测试环境，指定要运行的配方和Java解析器。classpath("spring-web", "validation-api")非常重要，它确保解析器能够识别@RequestParam和@NotNull注解的类型信息。
- requiredRequestParamWithNotNull()：定义一个测试方法。
- java(...)：接受两个字符串参数，第一个是修改前的源代码，第二个是期望修改后的源代码。OpenRewrite会运行配方并比较实际结果与期望结果。
- 测试代码中包含了多种情况：
- 同时有@NotNull和@RequestParam的参数（name, age）：期望被修改。
- 只有@RequestParam的参数（lang）：不应被修改。
- 只有@NotNull的参数（address）：不应被修改。
总结
通过本文的介绍，我们了解了如何使用OpenRewrite的命令式配方，结合AST游标（Cursor）机制，实现对Java代码中特定注解组合的方法参数进行精确修改。关键在于：
- 选择正确的Visitor方法：根据要修改的AST节点类型（例如，修改注解则重写visitAnnotation）。
- 利用Cursor获取上下文：通过getCursor().getParent().getValue()等方法向上导航AST，获取当前节点所在的更高级别上下文（如方法参数声明）。
- 条件判断：在获取到上下文后，进行复杂的条件判断（例如，检查是否存在其他注解）。
- 委托子配方Visitor：当条件满足时，将修改操作委托给目标子配方的Visitor，并确保传递正确的当前AST节点、执行上下文和Cursor，以避免上下文错误。
这种细粒度的控制能力使得OpenRewrite成为处理复杂代码重构任务的强大工具。
