feat: Add Support for Meta-Spring Controller Annotations

tangcent · tangcent · commit a89e60450bbf · 2025-02-16T15:38:17.000+08:00
diff --git a/idea-plugin/src/main/kotlin/com/itangcent/idea/plugin/api/export/spring/CustomSpringControllerAnnotationResolver.kt b/idea-plugin/src/main/kotlin/com/itangcent/idea/plugin/api/export/spring/CustomSpringControllerAnnotationResolver.kt
@@ -0,0 +1,53 @@
+package com.itangcent.idea.plugin.api.export.spring
+
+import com.google.inject.Inject
+import com.intellij.psi.PsiClass
+import com.itangcent.intellij.jvm.PsiResolver
+import java.util.concurrent.ConcurrentHashMap
+
+/*
+ * This class provides a custom implementation for resolving whether a given PsiClass
+ * has a Spring controller annotation. It supports meta-annotations, allowing for
+ * custom annotations that are themselves annotated with Spring controller annotations.
+ * For example, a custom annotation that is annotated with @Controller will be recognized
+ * ```java
+ * @Target({ElementType.TYPE})
+ * @Retention(RetentionPolicy.RUNTIME)
+ * @Documented
+ * @Controller
+ * public @interface XxxxController {
+ *     @AliasFor(
+ *         annotation = Controller.class
+ *     )
+ *     String value() default "";
+ * }
+ * ```
+ */
+class CustomSpringControllerAnnotationResolver : SpringControllerAnnotationResolver {
+
+    @Inject
+    private lateinit var psiResolver: PsiResolver
+
+    @Inject
+    private lateinit var standardSpringControllerAnnotationResolver: StandardSpringControllerAnnotationResolver
+
+    /**
+     * A cache to store the resolution results of whether a given annotation is a Spring controller annotation.
+     * The key is the qualified name of the annotation, and the value is a boolean indicating if it is a controller annotation.
+     */
+    private val controllerAnnotationLookup = ConcurrentHashMap<String, Boolean>()
+
+    override fun hasControllerAnnotation(psiClass: PsiClass): Boolean {
+        return psiClass.annotations.any { annotation ->
+            val annotationQualifiedName = annotation.qualifiedName ?: return@any false
+            controllerAnnotationLookup.computeIfAbsent(annotationQualifiedName) {
+                val annotationClass = annotation.resolveAnnotationType()
+                    ?: psiResolver.resolveClass(annotationQualifiedName, psiClass)
+                    ?: return@computeIfAbsent false
+                return@computeIfAbsent standardSpringControllerAnnotationResolver.hasControllerAnnotation(
+                    annotationClass
+                )
+            }
+        }
+    }
+} 
diff --git a/idea-plugin/src/main/kotlin/com/itangcent/idea/plugin/api/export/spring/CustomSpringRequestMappingResolver.kt b/idea-plugin/src/main/kotlin/com/itangcent/idea/plugin/api/export/spring/CustomSpringRequestMappingResolver.kt
@@ -12,8 +12,24 @@ import com.itangcent.intellij.context.ActionContext
 import com.itangcent.intellij.jvm.AnnotationHelper
 import java.util.concurrent.ConcurrentHashMap
 
-/**
- * Support custom annotation which annotated with [SpringClassName.SPRING_REQUEST_MAPPING_ANNOTATIONS]
+/*
+ * This class provides support for resolving custom request mapping annotations that are
+ * themselves annotated with standard Spring request mapping annotations.
+ *
+ * It enables the use of custom annotations as alternatives to the standard Spring
+ * request mapping annotations. For example:
+ *
+ * ```java
+ * @Target({ElementType.METHOD})
+ * @Retention(RetentionPolicy.RUNTIME)
+ * @RequestMapping(method = RequestMethod.GET)
+ * public @interface CustomGet {
+ *     String value() default "";
+ * }
+ * ```
+ *
+ * The resolver will recognize such custom annotations and extract the appropriate
+ * mapping information from them by analyzing their meta-annotations.
  */
 @Singleton
 class CustomSpringRequestMappingResolver : SpringRequestMappingResolver {
diff --git a/idea-plugin/src/main/kotlin/com/itangcent/idea/plugin/api/export/spring/DefaultSpringControllerAnnotationResolver.kt b/idea-plugin/src/main/kotlin/com/itangcent/idea/plugin/api/export/spring/DefaultSpringControllerAnnotationResolver.kt
@@ -0,0 +1,20 @@
+package com.itangcent.idea.plugin.api.export.spring
+
+import com.intellij.psi.PsiClass
+import com.itangcent.spi.SpiCompositeLoader
+
+/*
+ * This class provides a default implementation for resolving whether a given PsiClass
+ * has a Spring controller annotation. It delegates the resolution to a composite
+ * loader that can handle multiple strategies.
+ */
+class DefaultSpringControllerAnnotationResolver : SpringControllerAnnotationResolver {
+
+    private val delegate: SpringControllerAnnotationResolver by lazy {
+        SpiCompositeLoader.loadComposite()
+    }
+
+    override fun hasControllerAnnotation(psiClass: PsiClass): Boolean {
+        return delegate.hasControllerAnnotation(psiClass)
+    }
+}
diff --git a/idea-plugin/src/main/kotlin/com/itangcent/idea/plugin/api/export/spring/DefaultSpringRequestMappingResolver.kt b/idea-plugin/src/main/kotlin/com/itangcent/idea/plugin/api/export/spring/DefaultSpringRequestMappingResolver.kt
@@ -7,6 +7,10 @@ import com.intellij.psi.PsiElement
 import com.itangcent.intellij.context.ActionContext
 import com.itangcent.spi.SpiCompositeLoader
 
+/*
+ * This class provides a default implementation of SpringRequestMappingResolver that uses
+ * a composite pattern to delegate the resolution to multiple resolvers.
+ */
 @Singleton
 class DefaultSpringRequestMappingResolver : SpringRequestMappingResolver {
 
diff --git a/idea-plugin/src/main/kotlin/com/itangcent/idea/plugin/api/export/spring/SimpleSpringRequestClassExporter.kt b/idea-plugin/src/main/kotlin/com/itangcent/idea/plugin/api/export/spring/SimpleSpringRequestClassExporter.kt
@@ -7,7 +7,6 @@ import com.intellij.psi.PsiElement
 import com.intellij.psi.PsiMethod
 import com.itangcent.common.logger.traceError
 import com.itangcent.common.model.Request
-import com.itangcent.common.utils.stream
 import com.itangcent.idea.condition.annotation.ConditionOnClass
 import com.itangcent.idea.plugin.api.ClassApiExporterHelper
 import com.itangcent.idea.plugin.api.export.condition.ConditionOnDoc
@@ -45,6 +44,9 @@ open class SimpleSpringRequestClassExporter : ClassExporter {
     @Inject
     protected lateinit var classApiExporterHelper: ClassApiExporterHelper
 
+    @Inject
+    private lateinit var springControllerAnnotationResolver: SpringControllerAnnotationResolver
+
     override fun support(docType: KClass<*>): Boolean {
         return docType == Request::class
     }
@@ -72,10 +74,12 @@ open class SimpleSpringRequestClassExporter : ClassExporter {
 
                     return false
                 }
+
                 shouldIgnore(cls) -> {
                     logger!!.info("ignore class: $clsQualifiedName")
                     return true
                 }
+
                 else -> {
                     logger!!.info("search api from: $clsQualifiedName")
 
@@ -92,9 +96,8 @@ open class SimpleSpringRequestClassExporter : ClassExporter {
     }
 
     protected open fun isCtrl(psiClass: PsiClass): Boolean {
-        return SpringClassName.SPRING_CONTROLLER_ANNOTATION.any {
-            annotationHelper!!.hasAnn(psiClass, it)
-        } || (ruleComputer.computer(ClassExportRuleKeys.IS_SPRING_CTRL, psiClass) ?: false)
+        return springControllerAnnotationResolver.hasControllerAnnotation(psiClass)
+                || (ruleComputer.computer(ClassExportRuleKeys.IS_SPRING_CTRL, psiClass) ?: false)
     }
 
     private fun shouldIgnore(psiElement: PsiElement): Boolean {
diff --git a/idea-plugin/src/main/kotlin/com/itangcent/idea/plugin/api/export/spring/SpringClassName.kt b/idea-plugin/src/main/kotlin/com/itangcent/idea/plugin/api/export/spring/SpringClassName.kt
@@ -1,6 +1,10 @@
 package com.itangcent.idea.plugin.api.export.spring
 
-
+/*
+ * This object holds constants for various Spring class and annotation names.
+ * It is used throughout the codebase to refer to these classes and annotations
+ * in a consistent manner.
+ */
 object SpringClassName {
 
     val SPRING_REQUEST_RESPONSE: Array<String> = arrayOf(
@@ -58,8 +62,10 @@ object SpringClassName {
     //Spring Boot Actuator Annotations
     const val ENDPOINT_ANNOTATION = "org.springframework.boot.actuate.endpoint.annotation.Endpoint"
     const val WEB_ENDPOINT_ANNOTATION = "org.springframework.boot.actuate.endpoint.web.annotation.WebEndpoint"
-    const val CONTROLLER_ENDPOINT_ANNOTATION = "org.springframework.boot.actuate.endpoint.web.annotation.ControllerEndpoint"
-    const val REST_CONTROLLER_ENDPOINT_ANNOTATION = "org.springframework.boot.actuate.endpoint.web.annotation.RestControllerEndpoint"
+    const val CONTROLLER_ENDPOINT_ANNOTATION =
+        "org.springframework.boot.actuate.endpoint.web.annotation.ControllerEndpoint"
+    const val REST_CONTROLLER_ENDPOINT_ANNOTATION =
+        "org.springframework.boot.actuate.endpoint.web.annotation.RestControllerEndpoint"
 
     const val READ_OPERATION_ANNOTATION = "org.springframework.boot.actuate.endpoint.annotation.ReadOperation"
     const val WRITE_OPERATION_ANNOTATION = "org.springframework.boot.actuate.endpoint.annotation.WriteOperation"
diff --git a/idea-plugin/src/main/kotlin/com/itangcent/idea/plugin/api/export/spring/SpringControllerAnnotationResolver.kt b/idea-plugin/src/main/kotlin/com/itangcent/idea/plugin/api/export/spring/SpringControllerAnnotationResolver.kt
@@ -0,0 +1,14 @@
+package com.itangcent.idea.plugin.api.export.spring
+
+import com.google.inject.ImplementedBy
+import com.intellij.psi.PsiClass
+
+/*
+ * This interface defines a contract for resolving whether a given PsiClass
+ * has a Spring controller annotation. It is implemented by various classes
+ * to provide different strategies for determining the presence of controller annotations.
+ */
+@ImplementedBy(DefaultSpringControllerAnnotationResolver::class)
+interface SpringControllerAnnotationResolver {
+    fun hasControllerAnnotation(psiClass: PsiClass): Boolean
+} 
diff --git a/idea-plugin/src/main/kotlin/com/itangcent/idea/plugin/api/export/spring/SpringRequestClassExporter.kt b/idea-plugin/src/main/kotlin/com/itangcent/idea/plugin/api/export/spring/SpringRequestClassExporter.kt
@@ -34,6 +34,9 @@ open class SpringRequestClassExporter : RequestClassExporter() {
     @Inject
     protected lateinit var springRequestMappingResolver: SpringRequestMappingResolver
 
+    @Inject
+    private lateinit var springControllerAnnotationResolver: SpringControllerAnnotationResolver
+
     override fun processClass(cls: PsiClass, classExportContext: ClassExportContext) {
 
         val ctrlRequestMappingAnn = findRequestMappingInAnn(cls)
@@ -50,9 +53,8 @@ open class SpringRequestClassExporter : RequestClassExporter() {
     }
 
     override fun hasApi(psiClass: PsiClass): Boolean {
-        return SpringClassName.SPRING_CONTROLLER_ANNOTATION.any {
-            annotationHelper.hasAnn(psiClass, it)
-        } || (ruleComputer.computer(ClassExportRuleKeys.IS_SPRING_CTRL, psiClass) ?: false)
+        return springControllerAnnotationResolver.hasControllerAnnotation(psiClass) ||
+               (ruleComputer.computer(ClassExportRuleKeys.IS_SPRING_CTRL, psiClass) ?: false)
     }
 
     override fun isApi(psiMethod: PsiMethod): Boolean {
diff --git a/idea-plugin/src/main/kotlin/com/itangcent/idea/plugin/api/export/spring/SpringRequestMappingResolver.kt b/idea-plugin/src/main/kotlin/com/itangcent/idea/plugin/api/export/spring/SpringRequestMappingResolver.kt
@@ -3,6 +3,12 @@ package com.itangcent.idea.plugin.api.export.spring
 import com.google.inject.ImplementedBy
 import com.intellij.psi.PsiElement
 
+/*
+ * This interface defines a contract for resolving Spring request mapping annotations.
+ * It is responsible for extracting mapping information from Spring MVC request mapping
+ * annotations on classes and methods. This includes both standard Spring annotations
+ * and custom annotations that may be used for request mapping.
+ */
 @ImplementedBy(DefaultSpringRequestMappingResolver::class)
 interface SpringRequestMappingResolver {
 
diff --git a/idea-plugin/src/main/kotlin/com/itangcent/idea/plugin/api/export/spring/StandardSpringControllerAnnotationResolver.kt b/idea-plugin/src/main/kotlin/com/itangcent/idea/plugin/api/export/spring/StandardSpringControllerAnnotationResolver.kt
@@ -0,0 +1,20 @@
+package com.itangcent.idea.plugin.api.export.spring
+
+import com.google.inject.Inject
+import com.intellij.psi.PsiClass
+import com.itangcent.intellij.jvm.AnnotationHelper
+
+/*
+ * This class provides a standard implementation for resolving whether a given PsiClass
+ * has a Spring controller annotation.
+ */
+class StandardSpringControllerAnnotationResolver : SpringControllerAnnotationResolver {
+
+    @Inject
+    private lateinit var annotationHelper: AnnotationHelper
+
+    override fun hasControllerAnnotation(psiClass: PsiClass): Boolean {
+        // Check for direct Spring controller annotations
+        return SpringClassName.SPRING_CONTROLLER_ANNOTATION.any { annotationHelper.hasAnn(psiClass, it) }
+    }
+} 
diff --git a/idea-plugin/src/main/kotlin/com/itangcent/idea/plugin/api/export/spring/StarandSpringRequestMappingResolver.kt b/idea-plugin/src/main/kotlin/com/itangcent/idea/plugin/api/export/spring/StarandSpringRequestMappingResolver.kt
@@ -10,7 +10,19 @@ import com.itangcent.order.Order
 import com.itangcent.order.Ordered
 
 /**
- * Support standard spring RequestMapping annotations [SpringClassName.SPRING_REQUEST_MAPPING_ANNOTATIONS]
+ * This class handles the resolution of standard Spring request mapping annotations.
+ * It is responsible for processing the core Spring MVC annotations such as:
+ * - @RequestMapping
+ * - @GetMapping
+ * - @PostMapping
+ * - @PutMapping
+ * - @DeleteMapping
+ * - @PatchMapping
+ *
+ * This resolver has the highest precedence among all request mapping resolvers,
+ * ensuring that standard Spring annotations are processed before any custom ones.
+ * It extracts mapping information like HTTP methods, paths, headers, and other
+ * attributes from these standard annotations.
  */
 @Singleton
 @Order(Ordered.HIGHEST_PRECEDENCE)
diff --git a/idea-plugin/src/main/kotlin/com/itangcent/idea/plugin/rule/StandardJdkRuleParser.kt b/idea-plugin/src/main/kotlin/com/itangcent/idea/plugin/rule/StandardJdkRuleParser.kt
@@ -94,7 +94,7 @@ abstract class StandardJdkRuleParser : ScriptRuleParser() {
 
         fun findClass(canonicalText: String): ScriptPsiTypeContext? {
             return context?.let {
-                duckTypeHelper!!.findType(canonicalText, it)?.let { type -> ScriptPsiTypeContext(type) }
+                duckTypeHelper.findType(canonicalText, it)?.let { type -> ScriptPsiTypeContext(type) }
             }
         }
 
diff --git a/idea-plugin/src/main/resources/META-INF/services/com.itangcent.idea.plugin.api.export.spring.SpringControllerAnnotationResolver b/idea-plugin/src/main/resources/META-INF/services/com.itangcent.idea.plugin.api.export.spring.SpringControllerAnnotationResolver
@@ -0,0 +1,2 @@
+com.itangcent.idea.plugin.api.export.spring.StandardSpringControllerAnnotationResolver
+com.itangcent.idea.plugin.api.export.spring.CustomSpringControllerAnnotationResolver
diff --git a/idea-plugin/src/test/kotlin/com/itangcent/idea/plugin/api/export/spring/SpringRequestClassExporterTest.kt b/idea-plugin/src/test/kotlin/com/itangcent/idea/plugin/api/export/spring/SpringRequestClassExporterTest.kt
@@ -46,6 +46,8 @@ internal class SpringRequestClassExporterTest : PluginContextLightCodeInsightFix
 
     private lateinit var userApiImplPsiClass: PsiClass
 
+    private lateinit var customCtrlPsiClass: PsiClass
+
     private val settings = Settings()
 
     override fun beforeBind() {
@@ -63,6 +65,7 @@ internal class SpringRequestClassExporterTest : PluginContextLightCodeInsightFix
         loadSource(LocalDateTime::class)
         loadSource(HashMap::class)
         loadFile("annotation/Public.java")
+        loadFile("annotation/MyController.java")
         loadFile("constant/UserType.java")
         loadFile("model/IResult.java")
         loadFile("model/Result.java")
@@ -85,6 +88,7 @@ internal class SpringRequestClassExporterTest : PluginContextLightCodeInsightFix
         testCtrlPsiClass = loadClass("api/TestCtrl.java")!!
         iuserApiPsiClass = loadClass("api/IUserApi.java")!!
         userApiImplPsiClass = loadClass("api/UserApiImpl.java")!!
+        customCtrlPsiClass = loadClass("api/CustomCtrl.java")!!
         settings.inferEnable = true
 
         //clear log
@@ -702,4 +706,19 @@ internal class SpringRequestClassExporterTest : PluginContextLightCodeInsightFix
         }
         assertEquals(ResultLoader.load("testExportFromUserApi"), LoggerCollector.getLog().toUnixString())
     }
+
+    fun testExportFromMyController() {
+        val requests = ArrayList<Request>()
+        actionContext.withBoundary {
+            classExporter.export(customCtrlPsiClass, requestOnly {
+                requests.add(it)
+            })
+        }
+        assertEquals(1, requests.size)
+        requests[0].let { request ->
+            assertEquals("hello", request.name)
+            assertEquals("GET", request.method)
+            assertEquals(customCtrlPsiClass.methods[0], (request.resource as PsiResource).resource())
+        }
+    }
 }
diff --git a/idea-plugin/src/test/resources/annotation/MyController.java b/idea-plugin/src/test/resources/annotation/MyController.java
@@ -0,0 +1,19 @@
+package api.annotation;
+
+import org.springframework.core.annotation.AliasFor;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+@Target({ElementType.TYPE})
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
+@RestController
+public @interface MyController {
+    @AliasFor(annotation = RestController.class)
+    String value() default "";
+} 
diff --git a/idea-plugin/src/test/resources/api/CustomCtrl.java b/idea-plugin/src/test/resources/api/CustomCtrl.java
@@ -0,0 +1,13 @@
+package api.annotation;
+
+import api.annotation.MyController;
+import org.springframework.web.bind.annotation.RequestMapping;
+
+@MyController
+public class CustomCtrl {
+
+    @RequestMapping(value = "/hello")
+    public String hello() {
+        return "Hello, World!";
+    }
+} 
diff --git a/idea-plugin/src/test/resources/spring/AliasFor.java b/idea-plugin/src/test/resources/spring/AliasFor.java
