Flink 详解源码中的注解

1.Flink自定义注解级别

为了更好地进行代码和版本管理，flink使用了java的注解特性自定义了注解，对代码进行增强说明，Flink的自定义注解有

代码相关注解

在阅读Flink源码时，记住常用的有@internal、@public、@publicevolving这三个注释就够了。

@Experimental：该注解标识类仅供实验目的使用。添加该注解的类通常不会使用@Public和 @PublicEvolving注解

@Documented
@Target(ElementType.TYPE)
@Public
public @interface Experimental {
}

@VIsibleForTesting:该注解声明类、属性、构造方法、或整个类型，其可见性只对测试目的开放。这个注解的典型场景是，当一个方法是应当别申明为私有（不打算被外部调用）而无法申明为私有时(因为某些测试需要访问它)，通常会附加此注释。

@Documented
@Target({ ElementType.TYPE, ElementType.METHOD, ElementType.FIELD, ElementType.CONSTRUCTOR })
@Internal
public @interface VisibleForTesting {}

@Internal：该注解标识方法是稳定的，或公有的API是一个内部开发者级别的API。开发者级别的API是稳定的但只对Flink内部开放，但可能会通过版本发布改变。

@Documented
@Target({ ElementType.TYPE, ElementType.METHOD, ElementType.CONSTRUCTOR })
@Public
public @interface Internal {
}

@Public：该注解标识类是公有的，接口是稳定的。使用该注解的类、方法、属性在小版本中(1.0,1.1,1.2)是稳定的,但在大版本(1.0,2.0,3.0)中可能会破坏。

@Documented
@Target(ElementType.TYPE)
@Public
public @interface Public {}

@PublicEvolving：该注解标识类和方法是公有的，但是有不断演变的接口。添加该注解的类和方法通常不会使用Public 注解具有该注解的类和方法表明是公有和稳定的。但是，它们的接口和签名并不被认为是稳定的，可能会随着版本发布而变化。

@Documented
@Target({ ElementType.TYPE, ElementType.METHOD, ElementType.FIELD, ElementType.CONSTRUCTOR })
@Public
public @interface PublicEvolving {
}

2.文档配置相关注解：

文档相关的配置注释，主要在生成配置html文件的时候使用，便于配置文件的管理,具体使用可以参考ConfigOptionsDocGenerator类。

@ConfigGroup:改注解标识一个类指定了一组配置项

@Target({})
@Internal
public @interface ConfigGroup {
  String name();
  String keyPrefix();
}

@configGroups:改注解标识一个类包含多个配置项，

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Internal
public @interface ConfigGroups {
  ConfigGroup[] groups() default {};
}

Documentation.OverrideDefault:该注解用于配置项字段，标识覆盖默认值

@Target(ElementType.FIELD)
  @Retention(RetentionPolicy.RUNTIME)
  @Internal
  public @interface OverrideDefault {
      String value();
  }

Documentation.CommonOption:该注解用于配置项字段，将配置项添加到CommonOption Section中。 CommonOption.position参数控制生成html页面中表的位置，较低的值会置于顶部

@Target(ElementType.FIELD)
  @Retention(RetentionPolicy.RUNTIME)
  @Internal
  public @interface CommonOption {
      int POSITION_MEMORY = 10;
      int POSITION_PARALLELISM_SLOTS = 20;
      int POSITION_FAULT_TOLERANCE = 30;
      int POSITION_HIGH_AVAILABILITY = 40;
      int POSITION_SECURITY = 50;

      int position() default Integer.MAX_VALUE;
  }

Documentation.ExcludeFromDocumentation:该注解用于配置项字段，用于从文档中排除配置选项。

@Target(ElementType.FIELD)
  @Retention(RetentionPolicy.RUNTIME)
  @Internal
  public @interface ExcludeFromDocumentation {
      /**
       * The optional reason why the config option is excluded from documentation.
       */
      String value() default "";
  }

3.Java注解分类

注解按生命周期来划分可分为3类：

1 RetentionPolicy.SOURCE：注解只保留在源文件，当Java文件编译成class文件的时候，注解被遗弃；
2 RetentionPolicy.CLASS：注解被保留到class文件，但jvm加载class文件时候被遗弃，这是默认的生命周期；
3 RetentionPolicy.RUNTIME：注解不仅被保存到class文件中，jvm加载class文件之后，仍然存在；

Flink 详解源码中的注解