扫描原则一：@Controller 注解的识别与限制

AsyncTest Caller 在扫描 Spring Web 接口时，会严格遵循 Spring MVC 的实际行为模型，仅对可能被 Spring 容器注册并生效的 Controller 类进行识别与处理。本节将详细说明插件在 @Controller 注解层面的支持范围与过滤规则。

---

1️⃣ 支持的 @Controller 查找方式

插件支持在类级别识别
org.springframework.stereotype.Controller 注解，并会从 注解方向进行查找：

---

✅ 注解方向（组合 / 元注解）

• 如果当前类上标注的注解：
  • 本身并非 @Controller
  • 但其 注解定义上包含 @Controller
• 插件同样会识别该类为 Controller

📌 这与 Spring 对 组合注解（Meta-Annotation） 的支持行为保持一致。

📸 示例结构（注解方向）：

import com.example.springforpluginstest.test.classAnnotation.helper.PrivateRestController;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;

@PrivateRestController
@RequestMapping("/api")
public class ExtendsControllerChild {

  @GetMapping("/user")
  public String methodController() {
    return "hello user";
  }
}

---

import org.springframework.web.bind.annotation.RestController;

import java.lang.annotation.*;

@RestController
@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface PrivateRestController {

}

---

2️⃣ 不支持接口和继承上的 @Controller

❌ 插件 不会 识别定义在 接口（interface）和继承（extends） 上的 @Controller 注解。

原因：

• Spring MVC 官方明确不支持 从接口继承类级别的 @Controller
• 接口本身不会被注册为 Spring Bean
• 即使实现类实现了该接口，也不会自动具备 Controller 语义

📌 因此，接口上的 @Controller 定义将被直接忽略。

---

3️⃣ 抽象类或接口形式的 Controller 将被忽略

当满足以下任一条件时，该类会被忽略：

• @Controller 标注在：
  • 抽象类（abstract class）
  • 接口（interface）
• 或通过继承方式获得的父类为抽象类 / 接口

原因：

• 这类类型在 Spring 中 不会被实际实例化
• 因此也不会参与真实的 Web 请求处理

---

4️⃣ 注解定义（@interface）将被忽略

插件在扫描过程中：

• 会忽略所有：
  • 注解类型定义（@interface）
• 即使该注解本身或其元注解中包含 @Controller

📌 这是因为注解定义本身并不承载任何 Web 行为。

---

5️⃣ 匿名内部类将被忽略

以下形式的类将被忽略：

• 匿名内部类
• 无法明确归属到具体 Java 文件 / 类名的结构

原因：

• Spring MVC 本身也不会将匿名类作为 Controller 注册
• 同时无法进行稳定、可追踪的接口归档

---

6️⃣ 无任何 Spring Web 方法的 Controller 将被忽略

即使某个类满足以下条件：

• 被识别为 @Controller
• 但 类及其继承体系中：
  • 不包含任何 Spring Web 请求方法
    （如 @RequestMapping、@GetMapping 等）

➡️ 该类 不会出现在扫描树中

📌 插件只关心：

• 实际对外暴露接口的 Controller
• 而非仅作为结构或占位存在的类

---

✅ 小结

• 插件的 @Controller 扫描逻辑 与 Spring MVC 行为严格对齐
• 只扫描：
  • 可实例化
  • 实际暴露 Web 接口
  • 具备明确归属关系的 Controller
• 通过明确的忽略规则，避免：
  • 无效节点
  • 重复接口
  • 与真实运行行为不一致的问题

这确保了最终同步到 AsyncTest 的接口数据 准确、可信、可维护。