登录
首页 >  文章 >  java教程

OpenRewrite教程：如何添加方法注解属性

时间：2025-12-23 17:36:35 416浏览 收藏

IT行业相对于一般传统行业，发展更新速度更快，一旦停止了学习，很快就会被行业所淘汰。所以我们需要踏踏实实的不断学习，精进自己的技术，尤其是初学者。今天golang学习网给大家整理了《OpenRewrite教程：精准添加方法注解属性》，聊聊，我们一起来看看吧！

OpenRewrite 教程：为特定方法参数精确添加或更新注解属性

本教程详细介绍了如何使用 OpenRewrite 实现对 Java 代码中特定方法参数的注解属性进行精确修改。针对需要根据其他注解或参数类型进行条件性修改的场景，文章首先分析了声明式配方的局限性，随后深入讲解了如何通过构建命令式配方，利用 OpenRewrite 的 AST 遍历机制和 `Cursor` 对象，实现对抽象语法树的上下文感知导航和条件判断，最终精准定位并修改目标注解属性，并提供了完整的示例代码和测试方法。

引言

OpenRewrite 是一个强大的代码重构工具，它允许开发者通过定义“配方”（Recipes）来自动化执行代码转换。常见的应用场景包括依赖升级、API 迁移、代码风格统一等。然而，在某些特定情况下，我们可能需要对代码进行更精细的控制，例如，只对满足特定条件的代码片段应用转换，而非整个文件或所有匹配项。本文将聚焦于一个具体的挑战：如何仅对同时带有 @NotNull 和 @RequestParam 注解的方法参数，将其 @RequestParam 注解的 required 属性设置为 true。

问题场景分析

假设我们有以下 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
    ) {
       return "Hello";
    }
}

我们的目标是：

  1. 找到所有方法参数。
  2. 检查这些参数是否同时带有 @NotNull 和 @RequestParam 注解。
  3. 如果满足条件，则将该参数上的 @RequestParam 注解的 required 属性设置为 true。
  4. 预期结果如下：
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
    ) {
       return "Hello";
    }
}

注意，第二个参数 lang 因为没有 @NotNull 注解，所以不应被修改。

解决方案一：声明式配方及其局限性

OpenRewrite 提供了声明式配方，通过 YAML 文件即可定义简单的代码转换。例如，我们可以使用 AddOrUpdateAnnotationAttribute 配方来添加或更新 @RequestParam 的 required 属性：

# 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 或 Gradle 项目中配置 OpenRewrite 构建插件：

Maven 配置示例：

<plugin>
  <groupId>org.openrewrite.maven</groupId>
  <artifactId>rewrite-maven-plugin</artifactId>
  <version>4.38.0</version>
  <configuration>
    <activeRecipes>
      <recipe>org.example.MandatoryRequestParameter</recipe>
    </activeRecipes>
  </configuration>
</plugin>

局限性： 这种声明式配方会无差别地将所有 @RequestParam 注解的 required 属性设置为 true，无法实现我们所需的条件判断（即只针对同时有 @NotNull 的参数）。因此，对于这种需要复杂逻辑判断的场景，我们需要编写命令式配方。

解决方案二：命令式配方实现精确控制

命令式配方允许我们利用 OpenRewrite 的 Java 抽象语法树（AST）遍历机制，编写自定义的 Java 代码来精确控制转换逻辑。

核心概念：AST 遍历与 Cursor

OpenRewrite 的核心是 TreeVisitor，它允许我们遍历代码的 AST。JavaVisitor（或其子类 JavaIsoVisitor）是处理 Java AST 的专用访问器。在遍历过程中，TreeVisitor 提供了一个 Cursor 对象，它代表了当前访问的 AST 节点及其在树中的上下文路径。通过 Cursor，我们可以访问当前节点的父节点、祖先节点，从而获取更丰富的上下文信息，这对于实现条件判断至关重要。

实现细节：定位与条件判断

我们将创建一个继承自 Recipe 的类 MandatoryRequestParameter，并在其中定义一个 JavaIsoVisitor 来实现我们的逻辑。

  1. 定义配方类：

    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 org.openrewrite.marker.Markers;

import javax.validation.constraints.NotNull;
import java.util.List;

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";

    @Override
    public @NotNull String getDisplayName() {
        return "Make Spring `RequestParam` mandatory with @NotNull";
    }

    @Override
    public String getDescription() {
        return "Add `required` attribute to `RequestParam` and set the value to `true` for parameters also annotated with @NotNull.";
    }

  2. 优化：getSingleSourceApplicableTest()

    为了提高性能，我们可以使用 getSingleSourceApplicableTest() 方法来预先检查源文件是否包含我们感兴趣的类型。如果文件不包含 org.springframework.web.bind.annotation.RequestParam 类型，则无需运行主访问器。

        @Override
    protected TreeVisitor<?, ExecutionContext> getSingleSourceApplicableTest() {
        return new UsesType<>(REQUEST_PARAM_FQ_NAME);
    }

  3. 核心逻辑：getVisitor()

    在 getVisitor() 方法中，我们将创建一个 JavaIsoVisitor。此访问器将覆盖 visitAnnotation 方法，因为我们主要关注注解的修改。

        @Override
    protected @NotNull JavaVisitor<ExecutionContext> getVisitor() {
        // 这是一个嵌套的 visitor，用于实际添加或更新注解属性
        JavaIsoVisitor<ExecutionContext> addAttributeVisitor = new AddOrUpdateAnnotationAttribute(
                REQUEST_PARAM_FQ_NAME, "required", "true", false
        ).getVisitor();

        return new JavaIsoVisitor<ExecutionContext>() {
            @Override
            public J.Annotation visitAnnotation(J.Annotation annotation, ExecutionContext ctx) {
                // 首先调用父类的 visitAnnotation，确保 AST 正常遍历
                J.Annotation a = super.visitAnnotation(annotation, ctx);

                // 1. 检查当前注解是否是 @RequestParam
                if (!TypeUtils.isOfClassType(a.getType(), REQUEST_PARAM_FQ_NAME)) {
                    return a; // 如果不是，则直接返回
                }

                // 2. 使用 Cursor 导航到父节点，获取方法参数声明
                // 当前 cursor 指向 Annotation，其父节点是 J.VariableDeclarations
                J.VariableDeclarations variableDeclaration = getCursor().getParent().getValue();

                // 3. 检查该方法参数是否也带有 @NotNull 注解
                boolean hasNotNull = false;
                for (J.Annotation leadingAnnotation : variableDeclaration.getLeadingAnnotations()) {
                    if (TypeUtils.isOfClassType(leadingAnnotation.getType(), NOT_NULL_FQ_NAME)) {
                        hasNotNull = true;
                        break;
                    }
                }

                // 4. 如果同时满足 @RequestParam 和 @NotNull，则委托给 addAttributeVisitor 进行修改
                if (hasNotNull) {
                    // 关键：将当前的注解和上下文传递给 addAttributeVisitor
                    // 这样 addAttributeVisitor 就能在正确的 AST 位置上操作
                    return (J.Annotation) addAttributeVisitor.visit(a, ctx, getCursor());
                }
                return a; // 不满足条件，返回未修改的注解
            }
        };
    }
}

解释：

  • addAttributeVisitor：我们创建了一个 AddOrUpdateAnnotationAttribute 的实例，并获取其内部的 Visitor。这个 Visitor 知道如何添加或更新注解属性。
  • visitAnnotation(J.Annotation annotation, ExecutionContext ctx)：这是我们自定义访问器的核心。当 OpenRewrite 遍历到任何注解时，都会调用此方法。
  • super.visitAnnotation(annotation, ctx)：确保 AST 的正常遍历，允许子节点被访问。
  • TypeUtils.isOfClassType(a.getType(), REQUEST_PARAM_FQ_NAME)：检查当前注解的完全限定名是否为 org.springframework.web.bind.annotation.RequestParam。
  • getCursor().getParent().getValue()：这是实现精确控制的关键。getCursor() 返回当前 AST 节点的 Cursor。getParent() 导航到父节点的 Cursor。getValue() 则获取父节点对应的 AST 元素。对于一个注解，它的父节点通常是 J.VariableDeclarations（即变量声明，这里是方法参数）。
  • variableDeclaration.getLeadingAnnotations()：获取该方法参数声明上所有前置注解的列表。
  • TypeUtils.isOfClassType(leadingAnnotation.getType(), NOT_NULL_FQ_NAME)：遍历这些注解，检查是否存在 javax.validation.constraints.NotNull。
  • addAttributeVisitor.visit(a, ctx, getCursor())：如果条件满足，我们不直接修改 a，而是将修改任务委托给 addAttributeVisitor。重要的是，我们将当前的注解 a、执行上下文 ctx 和当前 Cursor 一并传递过去。这样，addAttributeVisitor 就能在正确的上下文（即当前 @RequestParam 注解的位置）执行其修改逻辑，避免了原始问题中因上下文丢失而导致的 UncaughtVisitorException。

完整命令式配方代码

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.TypeUtils;

import javax.validation.constraints.NotNull;
import java.util.List;

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";

    @Override
    public @NotNull String getDisplayName() {
        return "Make Spring `RequestParam` mandatory with @NotNull";
    }

    @Override
    public String getDescription() {
        return "Add `required` attribute to `RequestParam` and set the value to `true` for parameters also annotated with @NotNull.";
    }

    @Override
    protected TreeVisitor<?, ExecutionContext> getSingleSourceApplicableTest() {
        return new UsesType<>(REQUEST_PARAM_FQ_NAME);
    }

    @Override
    protected @NotNull JavaVisitor<ExecutionContext> getVisitor() {
        JavaIsoVisitor<ExecutionContext> addAttributeVisitor = new AddOrUpdateAnnotationAttribute(
                REQUEST_PARAM_FQ_NAME, "required", "true", false
        ).getVisitor();

        return new JavaIsoVisitor<ExecutionContext>() {
            @Override
            public J.Annotation visitAnnotation(J.Annotation annotation, ExecutionContext ctx) {
                J.Annotation a = super.visitAnnotation(annotation, ctx);

                if (!TypeUtils.isOfClassType(a.getType(), REQUEST_PARAM_FQ_NAME)) {
                    return a;
                }

                J.VariableDeclarations variableDeclaration = getCursor().getParent().getValue();

                boolean hasNotNull = false;
                for (J.Annotation leadingAnnotation : variableDeclaration.getLeadingAnnotations()) {
                    if (TypeUtils.isOfClassType(leadingAnnotation.getType(), NOT_NULL_FQ_NAME)) {
                        hasNotNull = true;
                        break;
                    }
                }

                if (hasNotNull) {
                    return (J.Annotation) addAttributeVisitor.visit(a, ctx, getCursor());
                }
                return a;
            }
        };
    }
}

测试配方

为了验证配方是否按预期工作，我们可以使用 OpenRewrite 的测试工具。在 src/test/java 目录下创建一个测试类：

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 @RequestParam(value = "id") Long id,
                      @RequestParam(value = "age") Integer 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 @RequestParam(required = true, value = "id") Long id,
                      @RequestParam(value = "age") Integer age
                    ) {
                      return "Hello";
                    }
                  }
                """
            )
        );
    }

    @Test
    void noNotNullAnnotation() {
        rewriteRun(
            java(
                """
                  import org.springframework.web.bind.annotation.RequestParam;

                  class ControllerClass {
                    public String sayHello (
                      @RequestParam(value = "name") String name
                    ) {
                      return "Hello";
                    }
                  }
                """
            )
        ); // 预期没有变化，所以只提供一个参数
    }

    @Test
    void otherAnnotationsPresent() {
        rewriteRun(
            java(
                """
                  import org.springframework.web.bind.annotation.RequestParam;
                  import org.springframework.lang.Nullable; // 假设有其他注解

                  class ControllerClass {
                    public String sayHello (
                      @Nullable @RequestParam(value = "param1") String param1,
                      @RequestParam(value = "param2") String param2
                    ) {
                      return "Hello";
                    }
                  }
                """
            )
        ); // 预期没有变化，因为没有 @NotNull
    }
}

在 defaults 方法中，我们通过 classpath 配置了 spring-web 和 validation-api，确保 OpenRewrite 解析器能够正确识别 @RequestParam 和 @NotNull 注解。rewriteRun 方法接受原始代码和期望转换后的代码，OpenRewrite 会执行配方并比较结果。

总结与注意事项

  • 命令式配方的强大之处： 当声明式配方无法满足复杂的条件判断和上下文感知转换时，命令式配方提供了无与伦比的灵活性。
  • Cursor 的重要性： Cursor 是 OpenRewrite 中进行 AST 上下文导航的核心工具。理解如何使用 getCursor()、getParent() 和 getValue() 是编写高级配方的关键。
  • 委托模式： 在自定义访问器中，如果已经有现成的配方或访问器可以完成部分工作（如 AddOrUpdateAnnotationAttribute），可以将其作为嵌套访问器，并在满足条件时委托给它执行，同时传递正确的 Cursor，以保持 AST 上下文的正确性。
  • 性能优化： 使用 getSingleSourceApplicableTest() 可以有效减少不必要的 AST 遍历，提升配方执行效率。
  • 依赖管理： 确保 OpenRewrite 解析器在测试和实际应用时，能够访问到所有相关的库依赖（例如 Spring Web 和 Validation API），否则可能导致类型解析失败。

通过本文的指导，您应该能够掌握如何利用 OpenRewrite 的命令式配方，实现对代码的精确控制和有条件的自动化重构。

以上就是本文的全部内容了，是否有顺利帮助你解决问题？若是能给你带来学习上的帮助，请大家多多支持golang学习网！更多关于文章的相关知识，也可关注golang学习网公众号。

相关阅读
更多>
最新阅读
更多>
课程推荐
更多>