注解

// 定义一个最简单的自定义注解
public @interface MyTag {
}

// 编译器实际生成的内容（反编译结果）
public interface MyTag extends java.lang.annotation.Annotation {
    // 注解本质上就是一个继承了 Annotation 的接口
}

// 这是注释（Comment）—— 给人看的，编译器直接丢弃
// 计算两个数的和
 
@Override  // 这是注解（Annotation）—— 给程序看的，编译器/JVM/框架会读取
public String toString() {
    return "Hello";
}

@Entity                          // 注解在【类】上
public class User {
 
    @Column(name = "user_name")  // 注解在【字段】上
    private String name;
 
    @Autowired                   // 注解在【构造方法】上
    public User(@Param("name") String name) {  // 注解在【参数】上
        this.name = name;
    }
 
    @Override                    // 注解在【方法】上
    public String toString() {
        return name;
    }
}

<!-- 早期 Servlet 配置：代码和配置分离，维护成本高 -->
<servlet>
    <servlet-name>userServlet</servlet-name>
    <servlet-class>com.example.UserServlet</servlet-class>
</servlet>
<servlet-mapping>
    <servlet-name>userServlet</servlet-name>
    <url-pattern>/user</url-pattern>
</servlet-mapping>

// 现代方式：注解直接标注在代码上，配置与代码合一
@WebServlet("/user")  // 一行注解替代了整段 XML 配置
public class UserServlet extends HttpServlet {
    // ...
}

@Entity                              // 元数据：告诉 JPA "这个类映射到数据库表"
@Table(name = "t_user")              // 元数据：指定表名为 t_user
public class User {
 
    @Id                              // 元数据：这是主键字段
    @GeneratedValue(strategy =       // 元数据：主键自增策略
        GenerationType.IDENTITY)
    private Long id;                 // 实际数据：用户 ID
 
    @Column(nullable = false,        // 元数据：非空，最大长度 50
            length = 50)
    private String username;         // 实际数据：用户名
 
    @Deprecated                      // 元数据：标记此方法已过时
    public String getDisplayName() { // 实际逻辑：获取显示名
        return username;
    }
}

public class Animal {
    // 父类定义了 speak 方法
    public void speak() {
        System.out.println("...");
    }
}
 
public class Dog extends Animal {
 
    // 正确：方法签名与父类完全一致，编译通过
    @Override
    public void speak() {
        System.out.println("Woof!");
    }
 
    // 错误示范：方法名拼写错误，写成了 speck
    // 如果没有 @Override，编译器会认为这是一个全新的方法，不会报错
    // 加上 @Override 后，编译器立刻报错：
    // "Method does not override or implement a method from a supertype"
    @Override
    public void speck() {  // ← 编译错误！
        System.out.println("Woof!");
    }
}

public interface Runnable {
    void run(); // 接口中定义的抽象方法
}
 
public class MyTask implements Runnable {
 
    @Override  // Java 6+ 允许且推荐：标记接口方法的实现
    public void run() {
        System.out.println("Task is running");
    }
}

public class Parent {
    public static void greet() {
        System.out.println("Hello from Parent");
    }
}
 
public class Child extends Parent {
    // 这里如果加 @Override 会编译报错
    // 因为静态方法不能被 override，只能被 hide
    public static void greet() {
        System.out.println("Hello from Child");
    }
}

public class StringUtils {
 
    /**
     * @deprecated 此方法效率低下，请使用 {@link #isBlank(String)} 替代。
     */
    @Deprecated
    public static boolean isEmpty(String str) {
        // 旧的实现：只判断了 null 和空字符串
        return str == null || str.length() == 0;
    }
 
    // 新的推荐方法：额外处理了空白字符
    public static boolean isBlank(String str) {
        return str == null || str.trim().isEmpty();
    }
}
 
public class Main {
    public static void main(String[] args) {
        // 编译器警告：'isEmpty(String)' is deprecated
        // IDE 中 isEmpty 会显示删除线
        StringUtils.isEmpty("hello");
 
        // 推荐使用新方法
        StringUtils.isBlank("hello");
    }
}

public @interface Deprecated {
    /**
     * since: 标明从哪个版本开始过时
     * 例如 "9" 表示从 Java 9 开始标记为过时
     */
    String since() default "";
 
    /**
     * forRemoval: 是否计划在未来版本中彻底移除
     * true 表示"这个 API 将被删除，必须尽快迁移"
     * false 表示"不推荐使用，但暂时不会删除"
     */
    boolean forRemoval() default false;
}

// java.lang.Thread 中的 stop() 方法（JDK 源码）
@Deprecated(since = "1.2", forRemoval = true)
public final void stop() {
    // ...
}

@Deprecated
public class OldParser {
    // 类内部方法互相调用，不会产生 deprecated 警告
    public void parse() {
        validate(); // 不会警告
    }
 
    public void validate() {
        // ...
    }
}
 
public class Main {
    public static void main(String[] args) {
        OldParser parser = new OldParser(); // 警告：OldParser is deprecated
        parser.parse();                      // 警告：parse() is deprecated
    }
}

// 压制单个警告类型
@SuppressWarnings("unchecked")
List<String> list = (List<String>) rawList;
 
// 压制多个警告类型
@SuppressWarnings({"unchecked", "deprecation"})
public void legacyMethod() {
    // 同时包含未检查转换和调用过时 API 的代码
}

┌──────────────────┬──────────────────────────────────────────────┐
│   警告类型        │   含义与触发场景                               │
├──────────────────┼──────────────────────────────────────────────┤
│ "unchecked"      │ 未经检查的泛型操作，如原始类型转泛型类型          │
│ "deprecation"    │ 调用了 @Deprecated 标记的 API                  │
│ "rawtypes"       │ 使用了原始类型（Raw Type），未指定泛型参数        │
│ "unused"         │ 声明了但未使用的变量、方法、导入等                │
│ "serial"         │ 可序列化类缺少 serialVersionUID 字段            │
│ "all"            │ 压制所有类型的警告（慎用）                       │
│ "fallthrough"    │ switch 语句中 case 缺少 break 导致穿透          │
│ "resource"       │ 未关闭的可关闭资源（如流、连接）                  │
└──────────────────┴──────────────────────────────────────────────┘

public class SuppressWarningsDemo {
 
    // ========== 场景一：压制 unchecked 警告 ==========
    @SuppressWarnings("unchecked")
    public static <T> T[] createArray(Class<T> clazz, int size) {
        // 泛型数组无法直接创建，必须通过 Object[] 强转
        // 这里编译器会警告 unchecked cast，但我们知道这是安全的
        return (T[]) java.lang.reflect.Array.newInstance(clazz, size);
    }
 
    // ========== 场景二：压制 deprecation 警告 ==========
    @SuppressWarnings("deprecation")
    public void connectLegacySystem() {
        // 必须调用旧系统的过时 API，短期内无法迁移
        // 压制警告避免编译输出中充斥大量无意义的 warning
        LegacyConnector connector = new LegacyConnector();
        connector.oldConnect(); // 这是一个 @Deprecated 方法
    }
 
    // ========== 场景三：压制 rawtypes 警告 ==========
    @SuppressWarnings("rawtypes")
    public void processRawList(List rawList) {
        // 与老代码交互时，可能不得不接收原始类型的 List
        // 加上注解表明这是有意为之
        for (Object item : rawList) {
            System.out.println(item);
        }
    }
}

// ❌ 不推荐：在整个方法上压制警告
// 这会掩盖方法内其他潜在的 unchecked 问题
@SuppressWarnings("unchecked")
public void processData() {
    List<String> names = (List<String>) getRawList();  // 真正需要压制的行
    Map<String, Object> config = loadConfig();          // 如果这里也有问题，会被掩盖
    // ... 100 行其他代码 ...
}
 
// ✅ 推荐：只在需要的局部变量上压制
public void processData() {
    @SuppressWarnings("unchecked")  // 精确标注在这一行
    List<String> names = (List<String>) getRawList();
 
    Map<String, Object> config = loadConfig(); // 这里的警告不会被压制，能正常暴露问题
    // ... 100 行其他代码 ...
}

┌─────────────────────┬────────────┬──────────────┬──────────────────────┐
│       注解           │ 保留策略    │  作用目标     │  核心用途             │
├─────────────────────┼────────────┼──────────────┼──────────────────────┤
│ @Override           │ SOURCE     │ 方法          │ 确保正确重写父类方法   │
│ @Deprecated         │ RUNTIME    │ 类/方法/字段等 │ 标记过时 API          │
│ @SuppressWarnings   │ SOURCE     │ 类/方法/变量等 │ 压制指定编译器警告     │
└─────────────────────┴────────────┴──────────────┴──────────────────────┘

public class Parent {
    public static void doWork() {
        System.out.println("Parent working");
    }
}
 
public class Child extends Parent {
    @Override
    public static void doWork() {
        System.out.println("Child working");
    }
}

// ElementType 枚举 —— 定义注解可以标注的目标类型
public enum ElementType {
    TYPE,            // 类、接口、枚举、record（Class, Interface, Enum, Record）
    FIELD,           // 字段（包括枚举常量）
    METHOD,          // 方法
    PARAMETER,       // 方法参数
    CONSTRUCTOR,     // 构造器
    LOCAL_VARIABLE,  // 局部变量
    ANNOTATION_TYPE, // 注解类型（即元注解的目标）
    PACKAGE,         // 包声明（package-info.java）
    TYPE_PARAMETER,  // 泛型类型参数（Java 8+），如 〈@MyAnno T〉
    TYPE_USE,        // 任何类型使用处（Java 8+），如 @NonNull String
    MODULE,          // 模块声明（Java 9+）
    RECORD_COMPONENT // Record 组件（Java 16+）
}

import java.lang.annotation.Target;
import java.lang.annotation.ElementType;
 
// @Target 限定：此注解只能贴在方法上
@Target(ElementType.METHOD)
public @interface TestCase {
    // 测试用例的描述信息
    String description() default "";
}

// ✅ 正确：贴在方法上
@TestCase(description = "测试用户登录")
public void testLogin() { }
 
// ❌ 编译错误：@TestCase 不允许标注在字段上
@TestCase
private String name;

// 允许标注在类和方法上
@Target({ElementType.TYPE, ElementType.METHOD})
public @interface Auditable {
    String operator() default "system";
}

// TYPE_USE 示例 —— 注解可以出现在类型使用的任何位置
@Target(ElementType.TYPE_USE)
public @interface NonNull { }
 
// 用法展示
@NonNull String name;                          // 字段类型
List<@NonNull String> names;                   // 泛型参数类型
String text = (@NonNull String) obj;           // 强制转型
public @NonNull String getName() { return ""; } // 返回值类型

// RetentionPolicy 枚举 —— 定义注解的保留策略
public enum RetentionPolicy {
    SOURCE,  // 仅存在于源码中，编译时丢弃（Discarded by the compiler）
    CLASS,   // 编译后保留在 .class 文件中，但 JVM 加载时不保留（默认值）
    RUNTIME  // 保留到运行时，可通过反射读取（Retained at runtime, accessible via reflection）
}

import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
 
// SOURCE 级别：编译后消失
@Retention(RetentionPolicy.SOURCE)
public @interface CompileOnly {
    String value() default "";
}
 
// CLASS 级别（默认）：存在于 .class 文件，运行时不可见
@Retention(RetentionPolicy.CLASS)
public @interface BytecodeVisible {
    String value() default "";
}
 
// RUNTIME 级别：运行时可通过反射读取
@Retention(RetentionPolicy.RUNTIME)
public @interface RuntimeAccessible {
    String value() default "";
}

import java.lang.reflect.Method;
 
public class RetentionDemo {
 
    @CompileOnly("编译后就没了")       // SOURCE
    @BytecodeVisible("反射看不到我")   // CLASS
    @RuntimeAccessible("反射能看到我") // RUNTIME
    public void testMethod() { }
 
    public static void main(String[] args) throws Exception {
        // 获取 testMethod 上的所有注解
        Method method = RetentionDemo.class.getMethod("testMethod");
 
        // 获取该方法上所有运行时可见的注解
        java.lang.annotation.Annotation[] annotations = method.getAnnotations();
 
        // 输出注解数量
        System.out.println("运行时可见注解数量: " + annotations.length); // 输出: 1
 
        // 遍历并打印
        for (java.lang.annotation.Annotation anno : annotations) {
            // 只有 @RuntimeAccessible 能被读到
            System.out.println(anno); // @RuntimeAccessible(value="反射能看到我")
        }
    }
}

import java.lang.annotation.*;
 
// 定义一个带 @Inherited 的注解
@Inherited                              // 关键：声明此注解可被子类继承
@Retention(RetentionPolicy.RUNTIME)     // 必须是 RUNTIME，否则反射读不到
@Target(ElementType.TYPE)               // 只能标注在类上
public @interface Component {
    String value() default "default";   // 组件名称
}
 
// 定义一个不带 @Inherited 的注解（作为对照）
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
public @interface Tag {
    String value() default "";
}

// 父类同时标注了 @Component 和 @Tag
@Component("baseService")
@Tag("base")
class BaseService { }
 
// 子类什么注解都没加
class UserService extends BaseService { }
 
public class InheritedDemo {
    public static void main(String[] args) {
        Class<?> clazz = UserService.class;
 
        // @Component 有 @Inherited，子类能继承到
        Component comp = clazz.getAnnotation(Component.class);
        System.out.println("@Component: " + comp);
        // 输出: @Component(value="baseService") ✅ 继承到了
 
        // @Tag 没有 @Inherited，子类继承不到
        Tag tag = clazz.getAnnotation(Tag.class);
        System.out.println("@Tag: " + tag);
        // 输出: @Tag: null ❌ 没有继承
 
        // getDeclaredAnnotations() 只看直接声明的，两个都没有
        Annotation[] declared = clazz.getDeclaredAnnotations();
        System.out.println("直接声明的注解数量: " + declared.length);
        // 输出: 0（UserService 自己没声明任何注解）
    }
}

import java.lang.annotation.*;
 
// 第一步：定义容器注解（Container Annotation）
// 容器注解内部有一个 value() 方法，返回被重复注解的数组
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
public @interface Roles {
    // 容器的 value() 返回 Role 数组
    Role[] value();
}
 
// 第二步：定义可重复注解，通过 @Repeatable 指向容器注解
@Repeatable(Roles.class)              // 指定容器注解为 Roles
@Retention(RetentionPolicy.RUNTIME)   // 保留策略必须与容器一致或更宽松
@Target(ElementType.TYPE)             // 目标类型必须与容器一致
public @interface Role {
    String value();                   // 角色名称
}

// 同一个类上重复使用 @Role
@Role("admin")
@Role("user")
@Role("auditor")
public class AdminController {
    // ...
}

// 编译器实际生成的等价形式
@Roles({
    @Role("admin"),
    @Role("user"),
    @Role("auditor")
})
public class AdminController { }

public class RepeatableDemo {
    public static void main(String[] args) {
        Class<?> clazz = AdminController.class;
 
        // 方式一：getAnnotationsByType() —— 直接获取所有重复注解（推荐）
        // 这个方法会"穿透"容器注解，直接返回所有 @Role
        Role[] roles = clazz.getAnnotationsByType(Role.class);
        System.out.println("角色数量: " + roles.length); // 输出: 3
        for (Role role : roles) {
            System.out.println("角色: " + role.value());
            // 输出: admin, user, auditor
        }
 
        // 方式二：getAnnotation(Role.class) —— 返回 null！
        // 因为实际存储的是容器注解 @Roles，不是单个 @Role
        Role singleRole = clazz.getAnnotation(Role.class);
        System.out.println("单个 @Role: " + singleRole); // 输出: null
 
        // 方式三：getAnnotation(Roles.class) —— 获取容器注解
        Roles container = clazz.getAnnotation(Roles.class);
        System.out.println("容器注解: " + container);
        // 输出: @Roles(value=[@Role("admin"), @Role("user"), @Role("auditor")])
    }
}

import java.lang.annotation.*;
 
// 容器注解
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@Inherited
public @interface ApiVersions {
    ApiVersion[] value();
}
 
// 可重复注解 —— 四个元注解全部用上
@Repeatable(ApiVersions.class)          // 可重复，容器为 ApiVersions
@Retention(RetentionPolicy.RUNTIME)     // 运行时保留
@Target(ElementType.TYPE)               // 只能标注在类上
@Inherited                              // 子类可继承
public @interface ApiVersion {
    String version();                   // API 版本号
    boolean deprecated() default false; // 是否已废弃
}

// 父类标注了多个 API 版本
@ApiVersion(version = "v1", deprecated = true)
@ApiVersion(version = "v2")
@ApiVersion(version = "v3")
class BaseApi { }
 
// 子类没有标注任何注解，但因为 @Inherited，会继承父类的
class UserApi extends BaseApi { }
 
public class CombinedDemo {
    public static void main(String[] args) {
        // 子类通过继承获得父类的所有 @ApiVersion
        ApiVersion[] versions = UserApi.class.getAnnotationsByType(ApiVersion.class);
 
        System.out.println("UserApi 支持的 API 版本:");
        for (ApiVersion v : versions) {
            // 打印每个版本及其废弃状态
            String status = v.deprecated() ? " [DEPRECATED]" : "";
            System.out.println("  " + v.version() + status);
        }
        // 输出:
        //   v1 [DEPRECATED]
        //   v2
        //   v3
    }
}

@Inherited
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@interface Cacheable { String value() default ""; }
 
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@interface Loggable { }
 
@Cacheable("60s")
@Loggable
class ParentService { }
 
class ChildService extends ParentService { }

// 使用 @interface 关键字声明一个注解类型
// 注解名遵循大驼峰命名规范，通常以形容词或名词命名
public @interface MyAnnotation {
    // 注解体：在这里声明"注解元素"（annotation elements）
}

// 反编译后的等价形式（javap -c 查看）
// 编译器自动让自定义注解继承 Annotation 接口
public interface MyAnnotation extends java.lang.annotation.Annotation {
}

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
 
// @Retention 指定注解保留到运行时，这样才能通过反射读取
@Retention(RetentionPolicy.RUNTIME)
// @Target 指定该注解可以标注在类和方法上
@Target({ElementType.TYPE, ElementType.METHOD})
public @interface ApiEndpoint {
 
    // 注解元素1：接口路径，无默认值（使用时必须显式赋值）
    String path();
 
    // 注解元素2：HTTP 请求方法，提供了默认值 "GET"
    String method() default "GET";
 
    // 注解元素3：接口描述，提供了默认值空字符串
    String description() default "";
 
    // 注解元素4：版本号，提供了默认值 1
    int version() default 1;
}

// 使用自定义注解标注一个控制器类
@ApiEndpoint(
    path = "/api/users",          // 必须赋值，因为没有 default
    method = "POST",              // 覆盖默认值 "GET"
    description = "创建新用户",    // 覆盖默认值 ""
    version = 2                   // 覆盖默认值 1
)
public class UserController {
 
    // 只提供必填元素，其余使用默认值
    @ApiEndpoint(path = "/api/users/list")
    public void listUsers() {
        // method 默认 "GET"，description 默认 ""，version 默认 1
    }
}

public @interface BadAnnotation {
    // ❌ 编译错误：注解元素不能有参数
    // String value(int index);
 
    // ❌ 编译错误：注解元素不能声明抛出异常
    // String name() throws Exception;
 
    // ✅ 正确：无参、无异常
    String value();
}

✅ 允许的返回类型：
├── 基本类型（int, long, float, double, boolean, byte, short, char）
├── String
├── Class（或带泛型的 Class<?>）
├── 枚举类型（enum）
├── 注解类型（嵌套注解）
└── 以上任意类型的一维数组

public @interface TypeDemo {
    int count();                          // ✅ 基本类型
    String name();                        // ✅ String
    Class<?> targetClass();               // ✅ Class
    ElementType targetType();             // ✅ 枚举
    Deprecated nested();                  // ✅ 注解类型
    String[] tags();                      // ✅ 数组
 
    // ❌ 以下类型全部非法：
    // Object obj();                      // 不允许 Object
    // List<String> list();               // 不允许集合类
    // Map<String, Object> map();         // 不允许 Map
    // int[][] matrix();                  // 不允许多维数组
}

public @interface DefaultDemo {
    // ✅ 编译期常量
    int timeout() default 30;
    String charset() default "UTF-8";
    boolean enabled() default true;
    String[] roles() default {"USER", "GUEST"};
 
    // ❌ 编译错误：null 不能作为默认值
    // String name() default null;
 
    // ❌ 编译错误：运行时表达式不能作为默认值
    // long timestamp() default System.currentTimeMillis();
}

// 定义一个只有 value 元素的注解
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.FIELD)
public @interface Label {
    // 命名为 value 的元素享有语法糖特权
    String value();
}

public class Product {
    // ✅ 完整写法
    @Label(value = "商品名称")
    private String name;
 
    // ✅ 简写：只给 value 赋值时可省略 "value ="
    @Label("商品价格")
    private double price;
}

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.FIELD)
public @interface Column {
    String value();                    // 列名
    boolean nullable() default true;   // 是否可空
}

public class User {
    // ✅ 只给 value 赋值，nullable 使用默认值 → 可以简写
    @Column("user_name")
    private String name;
 
    // ✅ 同时给多个元素赋值 → 必须使用完整写法
    @Column(value = "user_email", nullable = false)
    private String email;
 
    // ❌ 编译错误：多元素赋值时不能省略 key
    // @Column("user_age", false)
    // private int age;
}

// 1. 标记注解（Marker Annotation）：没有任何元素
//    作用：纯粹的"标记"，表示某种语义
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface Idempotent {
    // 空体，仅作标记用途
    // 表示该方法是幂等的，可安全重试
}
 
// 2. 单值注解（Single-Value Annotation）：只有一个元素（通常命名为 value）
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
public @interface Author {
    String value();   // 唯一元素，享受简写语法糖
}
 
// 3. 多值注解（Multi-Value / Full Annotation）：有多个元素
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface Cache {
    String key();                      // 缓存键
    int expireSeconds() default 3600;  // 过期时间
    boolean condition() default true;  // 是否启用
}

// 使用示例
@Author("张三")                        // 单值注解简写
public class OrderService {
 
    @Idempotent                         // 标记注解，无需括号（加了也行）
    @Cache(key = "order", expireSeconds = 600)  // 多值注解
    public Order getOrder(long id) {
        return null;
    }
}

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
 
// 非空校验注解
@Retention(RetentionPolicy.RUNTIME)   // 运行时保留，反射可读
@Target(ElementType.FIELD)            // 只能标注在字段上
public @interface NotNull {
    // 校验失败时的提示信息，默认为通用提示
    String message() default "字段不能为空";
}

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
 
// 字符串长度范围校验注解
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.FIELD)
public @interface Length {
    int min() default 0;              // 最小长度，默认 0
    int max() default Integer.MAX_VALUE;  // 最大长度，默认不限
    String message() default "字符串长度不符合要求";
}

public class UserDTO {
 
    @NotNull(message = "用户名不能为空")          // 标注非空校验
    @Length(min = 2, max = 20, message = "用户名长度需在2-20之间")  // 标注长度校验
    private String username;
 
    @NotNull                                      // 使用默认提示信息
    @Length(min = 6, max = 50)
    private String email;
 
    @Length(max = 200, message = "个性签名最多200字")
    private String signature;                     // 允许为空，但有长度限制
 
    // 构造方法
    public UserDTO(String username, String email, String signature) {
        this.username = username;
        this.email = email;
        this.signature = signature;
    }
 
    // getter 省略...
}

import java.lang.reflect.Field;
import java.util.ArrayList;
import java.util.List;
 
public class ValidationEngine {
 
    /**
     * 校验任意对象上标注的注解约束
     * @param obj 待校验的对象实例
     * @return 校验失败的错误信息列表，空列表表示全部通过
     */
    public static List<String> validate(Object obj) throws IllegalAccessException {
        // 存放所有校验错误信息
        List<String> errors = new ArrayList<>();
        // 获取对象的 Class 对象
        Class<?> clazz = obj.getClass();
        // 获取该类声明的所有字段（包括 private）
        Field[] fields = clazz.getDeclaredFields();
 
        // 遍历每一个字段
        for (Field field : fields) {
            // 突破 private 访问限制，允许反射读取字段值
            field.setAccessible(true);
            // 获取该字段在当前对象上的实际值
            Object value = field.get(obj);
 
            // ---------- 处理 @NotNull 注解 ----------
            // 判断该字段是否标注了 @NotNull
            if (field.isAnnotationPresent(NotNull.class)) {
                // 通过反射获取 @NotNull 注解实例
                NotNull notNull = field.getAnnotation(NotNull.class);
                // 如果字段值为 null，校验失败
                if (value == null) {
                    // 将注解中定义的 message 加入错误列表
                    errors.add("[" + field.getName() + "] " + notNull.message());
                    // 值为 null 时跳过后续校验，避免 NPE
                    continue;
                }
            }
 
            // ---------- 处理 @Length 注解 ----------
            // 判断该字段是否标注了 @Length
            if (field.isAnnotationPresent(Length.class)) {
                // 获取 @Length 注解实例
                Length length = field.getAnnotation(Length.class);
                // @Length 只对非 null 的 String 类型生效
                if (value instanceof String) {
                    // 强转为 String 并获取长度
                    int len = ((String) value).length();
                    // 判断长度是否在 [min, max] 范围内
                    if (len < length.min() || len > length.max()) {
                        // 校验失败，拼接详细错误信息
                        errors.add("[" + field.getName() + "] " + length.message()
                                + " (当前长度: " + len + ")");
                    }
                }
            }
        }
        // 返回所有错误信息
        return errors;
    }
}

public class ValidationTest {
    public static void main(String[] args) throws IllegalAccessException {
        // 构造一个不合法的 UserDTO 对象
        UserDTO user = new UserDTO(
            "A",       // 用户名太短，不满足 min=2
            null,      // email 为 null，触发 @NotNull
            "这是一段正常的签名"
        );
 
        // 调用校验引擎
        List<String> errors = ValidationEngine.validate(user);
 
        // 输出校验结果
        if (errors.isEmpty()) {
            System.out.println("✅ 校验通过！");
        } else {
            System.out.println("❌ 校验失败：");
            // 逐条打印错误信息
            for (String error : errors) {
                System.out.println("  - " + error);
            }
        }
    }
}

❌ 校验失败：
  - [username] 用户名长度需在2-20之间 (当前长度: 1)
  - [email] 字段不能为空

import java.lang.reflect.Field;
import java.lang.reflect.InvocationHandler;
import java.lang.reflect.Proxy;
 
public class AnnotationProxyDemo {
    public static void main(String[] args) throws Exception {
        // 获取 UserDTO 的 username 字段
        Field field = UserDTO.class.getDeclaredField("username");
        // 获取该字段上的 @NotNull 注解实例
        NotNull notNull = field.getAnnotation(NotNull.class);
 
        // 验证注解实例是否是代理对象
        System.out.println("是否为代理对象: " + Proxy.isProxyClass(notNull.getClass()));
        // 输出: 是否为代理对象: true
 
        // 获取代理背后的 InvocationHandler
        InvocationHandler handler = Proxy.getInvocationHandler(notNull);
        // 输出 handler 的类型
        System.out.println("Handler 类型: " + handler.getClass().getName());
        // 输出: Handler 类型: sun.reflect.annotation.AnnotationInvocationHandler
    }
}

@interface Config {
    Object value();
}

@interface Config {
    String[] value() default null;
}

@interface Config {
    String value() default "";
    int[] ports() default {8080, 8443};
}

@interface Config {
    List<String> names();
}

import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
 
// 定义一个用于描述数据库字段约束的注解
@Retention(RetentionPolicy.RUNTIME)
public @interface Column {
 
    // int 类型：指定字段长度，默认 255
    int length() default 255;
 
    // boolean 类型：是否允许为空，默认 true
    boolean nullable() default true;
 
    // double 类型：数值精度，默认 0.0
    double precision() default 0.0;
 
    // char 类型：填充字符，默认空格
    char padChar() default ' ';
 
    // byte 类型：标志位
    byte flag() default 0;
 
    // short 类型：排序权重
    short order() default 0;
 
    // long 类型：最大值限制
    long maxValue() default Long.MAX_VALUE;
 
    // float 类型：比例因子
    float scale() default 1.0f;
}

public class User {
 
    // 使用注解标注字段，指定长度为 50，不允许为空
    @Column(length = 50, nullable = false, padChar = '_')
    private String username;
 
    // 使用默认值，无需显式传参
    @Column
    private String email;
}

// ❌ 编译错误！Integer 不是合法的注解元素类型
public @interface WrongAnnotation {
    Integer count() default 0;  // 非法：不能使用包装类型
}

import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
 
@Retention(RetentionPolicy.RUNTIME)
public @interface RequestMapping {
 
    // 请求路径，默认为空字符串
    String path() default "";
 
    // HTTP 方法，默认 GET
    String method() default "GET";
 
    // 描述信息
    String description() default "No description provided";
}

// 使用示例
@RequestMapping(path = "/api/users", method = "POST", description = "创建新用户")
public class UserController {
    // ...
}

// ❌ 编译错误！注解元素的默认值不能是 null
public @interface BadAnnotation {
    String value() default null;  // 非法
}

@Retention(RetentionPolicy.RUNTIME)
public @interface Config {
 
    // 用空字符串作为"未设置"的哨兵值
    String name() default "";
 
    // 或者用一个明确的标记字符串
    String dataSource() default "<undefined>";
}

// 读取注解并判断是否设置了值
Config config = clazz.getAnnotation(Config.class);
if (config != null) {
    // 判断是否使用了默认的哨兵值
    String ds = config.dataSource();
    if (!"<undefined>".equals(ds)) {
        // 用户显式设置了 dataSource，执行相应逻辑
        System.out.println("DataSource: " + ds);
    }
}

import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
 
@Retention(RetentionPolicy.RUNTIME)
public @interface JsonSerialize {
 
    // 指定序列化器的 Class，默认使用 Void.class 表示"未指定"
    Class<?> using() default Void.class;
 
    // 带泛型上界约束：只接受 Number 的子类
    Class<? extends Number> numberType() default Integer.class;
}

// 自定义序列化器
public class CustomDateSerializer {
    // 序列化逻辑...
}
 
// 使用注解指定序列化器类
@JsonSerialize(using = CustomDateSerializer.class, numberType = Double.class)
public class Order {
    private String orderDate;
    private double totalAmount;
}

// 常见的"哨兵类"选择策略
public @interface Component {
 
    // 方案一：使用 Void.class 表示未指定（最常见）
    Class<?> factoryClass() default Void.class;
 
    // 方案二：使用注解自身作为标记（Spring 的做法）
    // Class<?> value() default Component.class;
 
    // 方案三：定义一个专用的空标记类
    // Class<?> handler() default DefaultMarker.class;
}

// 通过反射读取 Class 类型的注解元素
Component comp = clazz.getAnnotation(Component.class);
if (comp != null && comp.factoryClass() != Void.class) {
    // 用户指定了自定义工厂类
    Class<?> factory = comp.factoryClass();
    Object instance = factory.getDeclaredConstructor().newInstance();
    System.out.println("使用自定义工厂: " + factory.getName());
}

// 定义一个表示 HTTP 方法的枚举
public enum HttpMethod {
    GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS
}
 
// 定义一个表示日志级别的枚举
public enum LogLevel {
    TRACE, DEBUG, INFO, WARN, ERROR
}

import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
 
@Retention(RetentionPolicy.RUNTIME)
public @interface Api {
 
    // 使用枚举类型指定 HTTP 方法，默认 GET
    HttpMethod method() default HttpMethod.GET;
 
    // 使用枚举类型指定日志级别，默认 INFO
    LogLevel logLevel() default LogLevel.INFO;
}

// 使用示例：枚举值直接引用，编译期即可检查合法性
@Api(method = HttpMethod.POST, logLevel = LogLevel.DEBUG)
public class PaymentService {
    // ...
}

// ❌ 不推荐：使用 String，容易拼写错误，且无编译期检查
public @interface BadApi {
    String method() default "GET";  // 传入 "GETT" 也不会报错
}
 
// ✅ 推荐：使用枚举，拼写错误直接编译失败
public @interface GoodApi {
    HttpMethod method() default HttpMethod.GET;  // 类型安全
}

import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
 
// 内层注解：描述单个字段的校验规则
@Retention(RetentionPolicy.RUNTIME)
public @interface Constraint {
 
    // 校验规则名称
    String name();
 
    // 规则参数值
    String value() default "";
 
    // 错误提示信息
    String message() default "Validation failed";
}

// 外层注解：将 Constraint 注解作为元素类型嵌套使用
@Retention(RetentionPolicy.RUNTIME)
public @interface ValidField {
 
    // 字段名
    String fieldName();
 
    // 嵌套单个注解：主要校验规则
    Constraint primaryRule();
 
    // 嵌套注解数组：附加校验规则（可选）
    Constraint[] additionalRules() default {};
}

// 使用嵌套注解进行声明式校验配置
@ValidField(
    fieldName = "email",
    // 内层注解通过 @Constraint(...) 的形式传入
    primaryRule = @Constraint(
        name = "pattern",
        value = "^[\\w.-]+@[\\w.-]+\\.\\w+$",
        message = "邮箱格式不正确"
    ),
    additionalRules = {
        @Constraint(name = "notBlank", message = "邮箱不能为空"),
        @Constraint(name = "maxLength", value = "100", message = "邮箱长度不能超过100")
    }
)
private String email;

// 模拟 Spring 的 Filter 注解
@Retention(RetentionPolicy.RUNTIME)
public @interface Filter {
    String type() default "ANNOTATION";  // 过滤类型
    Class<?>[] classes() default {};     // 过滤的目标类
}
 
// 模拟 Spring 的 ComponentScan 注解
@Retention(RetentionPolicy.RUNTIME)
public @interface ComponentScan {
    String[] basePackages() default {};
 
    // 嵌套 Filter 注解数组：包含过滤器
    Filter[] includeFilters() default {};
 
    // 嵌套 Filter 注解数组：排除过滤器
    Filter[] excludeFilters() default {};
}

// 使用示例：声明式地配置组件扫描策略
@ComponentScan(
    basePackages = {"com.example.service", "com.example.dao"},
    includeFilters = {
        @Filter(type = "ANNOTATION", classes = {Service.class})
    },
    excludeFilters = {
        @Filter(type = "REGEX", classes = {})
    }
)
public class AppConfig {
    // Spring 容器启动时会解析这些嵌套注解
}

import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
 
@Retention(RetentionPolicy.RUNTIME)
public @interface Permission {
 
    // String 数组：允许的角色列表
    String[] roles() default {};
 
    // int 数组：允许的权限级别
    int[] levels() default {1, 2, 3};
 
    // Class 数组：允许的处理器类
    Class<?>[] handlers() default {};
 
    // 枚举数组：允许的 HTTP 方法
    HttpMethod[] methods() default {HttpMethod.GET};
 
    // 注解数组：多个校验约束（前面已演示过）
    Constraint[] constraints() default {};
}

// 多个元素：必须使用花括号
@Permission(roles = {"ADMIN", "MANAGER"}, methods = {HttpMethod.GET, HttpMethod.POST})
public void manageUsers() {}
 
// 单个元素：可以省略花括号（语法糖）
@Permission(roles = "ADMIN", methods = HttpMethod.GET)
public void viewDashboard() {}
 
// 空数组：使用空花括号
@Permission(roles = {}, methods = {})
public void publicEndpoint() {}

// ❌ 编译错误！不支持二维数组
public @interface Matrix {
    int[][] data();  // 非法
}
 
// ✅ 如果确实需要表达矩阵，只能用 String 编码后运行时解析
public @interface Matrix {
    String[] rows() default {};  // 每个 String 编码一行，如 "1,2,3"
}

import java.lang.annotation.*;
 
// 响应码描述（内层注解）
@Retention(RetentionPolicy.RUNTIME)
public @interface ResponseCode {
    int code();                    // 基本类型 int
    String description();          // String 类型
}

// API 版本枚举
public enum ApiVersion {
    V1, V2, V3
}

import java.lang.annotation.*;
 
// API 文档注解（外层注解，综合使用所有合法类型）
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface ApiDoc {
 
    // 1. String 类型：接口名称
    String name();
 
    // 2. String 类型：接口描述，带默认值
    String description() default "暂无描述";
 
    // 3. 基本类型 int：超时时间（毫秒）
    int timeout() default 3000;
 
    // 4. 基本类型 boolean：是否需要认证
    boolean requireAuth() default true;
 
    // 5. 枚举类型：API 版本
    ApiVersion version() default ApiVersion.V1;
 
    // 6. Class 类型：响应体的序列化器
    Class<?> serializer() default Void.class;
 
    // 7. 注解类型（嵌套注解）：成功响应码
    ResponseCode successResponse() default @ResponseCode(code = 200, description = "OK");
 
    // 8. String 数组：标签
    String[] tags() default {};
 
    // 9. 枚举数组：支持的 HTTP 方法
    HttpMethod[] methods() default {HttpMethod.GET};
 
    // 10. 注解数组：错误响应码列表
    ResponseCode[] errorResponses() default {};
}

// 实际使用：一个注解涵盖了所有合法元素类型
public class UserApi {
 
    @ApiDoc(
        name = "获取用户信息",                              // String
        description = "根据用户ID查询详细信息",               // String
        timeout = 5000,                                    // int
        requireAuth = true,                                // boolean
        version = ApiVersion.V2,                           // 枚举
        serializer = CustomSerializer.class,               // Class
        successResponse = @ResponseCode(                   // 嵌套注解
            code = 200,
            description = "成功返回用户信息"
        ),
        tags = {"用户模块", "查询接口"},                     // String 数组
        methods = {HttpMethod.GET, HttpMethod.POST},       // 枚举数组
        errorResponses = {                                 // 注解数组
            @ResponseCode(code = 404, description = "用户不存在"),
            @ResponseCode(code = 403, description = "无权限访问")
        }
    )
    public Object getUserById(long id) {
        return null;
    }
}

import java.lang.reflect.Method;
 
public class ApiDocReader {
    public static void main(String[] args) throws Exception {
        // 获取目标方法
        Method method = UserApi.class.getMethod("getUserById", long.class);
 
        // 读取 @ApiDoc 注解
        ApiDoc doc = method.getAnnotation(ApiDoc.class);
 
        if (doc != null) {
            // 读取各种类型的元素值
            System.out.println("接口名称: " + doc.name());                    // String
            System.out.println("超时时间: " + doc.timeout() + "ms");          // int
            System.out.println("需要认证: " + doc.requireAuth());             // boolean
            System.out.println("API版本: " + doc.version());                  // 枚举
            System.out.println("序列化器: " + doc.serializer().getName());    // Class
 
            // 读取嵌套注解
            ResponseCode success = doc.successResponse();                     // 注解
            System.out.println("成功码: " + success.code() + " - " + success.description());
 
            // 读取数组
            System.out.println("标签: " + String.join(", ", doc.tags()));     // String[]
 
            // 读取注解数组
            for (ResponseCode err : doc.errorResponses()) {                   // 注解数组
                System.out.println("错误码: " + err.code() + " - " + err.description());
            }
        }
    }
}