1.Flink自定义注解级别

在升级 Flink版本至 1.15.3时，偶然遇到了一个异常，然后就准备详细了解下源码中的注解。设计注解的初衷：为了更好地进行代码和版本管理，Flink使用了Java的注解特性自定义了注解，对代码进行增强说明。

注解的使用场景：

提供信息给编译器：编译器可以利用注解来探测错误和警告信息

编译阶段时的处理：软件工具可以利用注解信息来生成代码，HTML文档或其他相应处理

运行时的处理：某些注解可以在程序运行时接受代码的提取

Flink 注解源码包的位置：org.apache.flink.annotation.*

Flink的自定义注解有如下几种：

1.2代码相关注解

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

1.2.1 @Experimental

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

package org.apache.flink.annotation;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Target;

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

1.2.2 @VIsibleForTesting

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

package org.apache.flink.annotation;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Target;

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

1.2.3 @Internal

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

package org.apache.flink.annotation;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Target;

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

1.2.4 @Public

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

package org.apache.flink.annotation;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Target;

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

1.2.5 @PublicEvolving

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

package org.apache.flink.annotation;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Target;

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

2.文档配置相关注解

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

import static org.apache.flink.docs.configuration.ConfigOptionsDocGenerator.getDescription;
import static org.apache.flink.docs.configuration.ConfigOptionsDocGenerator.getDocumentedKey;
import static org.apache.flink.docs.configuration.ConfigOptionsDocGenerator.stringifyDefault;
import static org.apache.flink.docs.configuration.ConfigOptionsDocGenerator.typeToHtml;

2.1 @ConfigGroup

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

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

2.2 @configGroups

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

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

2.3 Documentation.OverrideDefault

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

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

2.4 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;
  }

2.5 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 "";
  }