@Documented 的作用

1. @Documented 的含义

  • @Document 是 java 在生成文档,是否显示注解的开关。

2. 加和不加有什么区别?

  • 测试注解

    @Target(ElementType.TYPE)
    @Retention(RetentionPolicy.RUNTIME)
    @Documented
    public @interface RestMapping {
    String[] value() default {};

    String[] path() default {};
    }

  • 测试类 TerminalController

    @RestMapping(“/terminal”)
    public class TerminalController {

  • 使用命令

    // 生成 java doc 的命令:
    javadoc -d doc TerminalController.java`
    // -d 输出文件的目标目录

a. 不加的效果

b. 加上的效果

可以看到在 public class TerminalController 上面多了一个我们写的注解。这就是 @Documented 的用处。

3. 题外话:注解合并

java 注解原本只是一种不会被编译器忽略的注释。本身对代码逻辑没有任何影响(可以用来判断是否存在,能读取内容信息),而使用效果完全由使用工具决定。

注解被很多规范使用,作为标记或者约定,如 jsr303 参数校验。

a. 注解合并

在 springboot 中注解发挥了很大的作用,而这些作用仅在springboot中有用,就好比@AliasFor。

注解本身并不能被注解继承,而 springboot 中却看到大量的合并注解就好比 @RestController = @Controller + @ResponseBody。这就是 @AliasFor 的功劳。需要注意的是,离开 Spring 就无法使用了。

spring 的注解都是由下面这个类读取的,所以 spring 的注解可以进行注解合并(有且仅限 spring 注解:Spring Annotations)

public interface MergedAnnotations

b. @AliasFor

@AliasFor 有四个作用:

  1. 注释中的显式别名:
    在@ContextConfiguration中, value和locations是彼此的显式别名。

    public @interface ContextConfiguration {
    @AliasFor(“locations”)
    String[] value() default {};

    @AliasFor(“value”)
    String[] locations() default {};

    // …
    }

  2. 元注释中属性的显式别名:
    在@XmlTestConfig中, xmlFiles是@ContextConfiguration中locations的显式别名。换句话说, xmlFiles覆盖了@ContextConfiguration中的locations属性。

    @ContextConfiguration
    public @interface XmlTestConfig {

      @AliasFor(annotation = ContextConfiguration.class, attribute = "locations")
      String[] xmlFiles();
    

    }

  3. 注释中的隐式别名:
    在@MyTestConfig中, value 、 groovyScripts和xmlFiles都是@ContextConfiguration中locations属性的显式元注释属性覆盖。因此,这三个属性也是彼此的隐式别名。

    @ContextConfiguration
    public @interface MyTestConfig {
    @AliasFor(annotation = ContextConfiguration.class, attribute = “locations”)
    String[] value() default {};

    @AliasFor(annotation = ContextConfiguration.class, attribute = “locations”)
    String[] groovyScripts() default {};

    @AliasFor(annotation = ContextConfiguration.class, attribute = “locations”)
    String[] xmlFiles() default {};
    }

  4. 注释中的传递隐式别名:
    在@GroovyOrXmlTestConfig中, groovy是对@MyTestConfig中groovyScripts属性的显式覆盖;而xml是对@ContextConfiguration中的locations属性的显式覆盖。此外, groovy和xml是彼此的可传递隐式别名,因为它们都有效地覆盖了@ContextConfiguration中的locations属性。

    @MyTestConfig
    public @interface GroovyOrXmlTestConfig {
    @AliasFor(annotation = MyTestConfig.class, attribute = “groovyScripts”)
    String[] groovy() default {};

    @AliasFor(annotation = ContextConfiguration.class, attribute = “locations”)
    String[] xml() default {};
    }

(完)

你可能感兴趣的