Flink1.15源码阅读——flink-annotations

flink-annotations源码分析

Flink-annotation类图关系

本文将详细介绍下flink中的自定义注解模块，了解flink注解的作用与使用。主要围绕flink源码中的 flink-annotations模块，与docs 相关的注解有@ConfigGroup和@ConfigGroups , 通常作用于配置类上；@Documentation.OverrideDefault、@Documentation.Section、@Documentation.TableOption、@Documentation.SuffixOption,@Documentation.ExcludeFromDocumentation 作用于配置类的 ConfigOption 字段上，对配置项做一些修改。另外，还有其他5种标记注解，@Experimental、@Internal、@Public、@PublicEvolving、@VisibleForTesting。

FlinkVersion

flink 版本枚举类，在SQL/Table API升级期间，它用于API版本控制和迁移测试。

docs注解

@ConfigGroup

指定一组配置选项的类。组的名称将作为基础生成的html文件的文件名，定义在{@link ConfigOptionsDocGenerator}中。
如 @ConfigGroup(name = ExponentialDelayRestartStrategy",keyPrefix = “restart-strategy.exponential-delay”)，生成的 HTML 文件名为 ExponentialDelayRestartStrategy ，其中的配置项名称都是以 restart-strategy.exponential-delay 开头的。

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

@ConfigGroups

在包含配置选项的类上使用的注释，允许根据键前缀将选项分离到不同的表中。如果选项键匹配组前缀，则配置选项被分配给{@link ConfigGroup}。当一个键匹配多个前缀时，匹配时间最长的前缀优先。选项永远不会分配给多个组。不匹配任何组的选项将隐式添加到默认组。

允许一个配置类中的配置项可以按照配置项名称前缀分成不同的组，生成多个 HTML 文件。
如：

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

@Documentation

用于修改文档生成器行为的注释集合。

@Documentation.OverrideDefault

/**
     * 使用此注解代表覆盖文档默认值
     **/
    @Target(ElementType.FIELD)
    @Retention(RetentionPolicy.RUNTIME)
    @Internal
    public @interface OverrideDefault {
        String value();
    }

@Documentation.Section

/**
     * 用于配置选项字段的注释，以将它们包含在特定部分中。部分跨选项类聚合的选项组，放置每个组放到一个专用文件中。
     * 参数{@link Section#position()}控制生成表中的位置，使用较低的值被放置在顶部。相同位置的字段按字母顺序排序的关键。
     */
    @Target(ElementType.FIELD)
    @Retention(RetentionPolicy.RUNTIME)
    @Internal
    public @interface Section {
        /**
         * 配置文档中应该包含此选项的部分。
         */
        String[] value() default {};

        /**
         * 该选项在其部分中的相对位置。
         */
        int position() default Integer.MAX_VALUE;
    }

@Documentation.TableOption

/**
     * 表配置选项中用于添加元数据标签的注释。
     * <p>
     * {@link TableOption#execMode()}参数表示配置工作的执行模式(批处理、流处理或两者兼有)。
     */
    @Target(ElementType.FIELD)
    @Retention(RetentionPolicy.RUNTIME)
    @Internal
    public @interface TableOption {
        ExecMode execMode();
    }

    /**
     * 执行模式根据配置的工作
     */
    public enum ExecMode {
        BATCH("Batch"),
        STREAMING("Streaming"),
        BATCH_STREAMING("Batch and Streaming");

        private final String name;

        ExecMode(String name) {
            this.name = name;
        }

        @Override
        public String toString() {
            return name;
        }
    }

@Documentation.SuffixOption

    /**
     * 用于配置选项字段或选项类的注释，将它们标记为后缀选项;
     * 例如，一个配置选项，其中键仅为后缀，前缀为动态在运行时提供。
     */
    @Target({ElementType.FIELD, ElementType.TYPE})
    @Retention(RetentionPolicy.RUNTIME)
    @Internal
    public @interface SuffixOption {
        String value();
    }

@Documentation.ExcludeFromDocumentation

    /**
     * 配置选项字段或REST API消息头上用于排除它的注释文档
     */
    @Target({ElementType.FIELD, ElementType.TYPE})
    @Retention(RetentionPolicy.RUNTIME)
    @Internal
    public @interface ExcludeFromDocumentation {
        /**
         * 从文档中排除它的可选原因。
         */
        String value() default "";
    }

@Experimental

/**
 * 此注解是为了标记某个类仍处于实验阶段
 *
 * @author DeveloperZJQ
 * @since 2022-7-19
 */
@Documented
@Target({ElementType.TYPE, ElementType.METHOD, ElementType.FIELD, ElementType.CONSTRUCTOR})
@Public
public @interface Experimental {
}

@Internal

/**
 * 标记用作稳定的方法 ， 公共的api作为内部的开发者api
 *
 * @author DeveloperZJQ
 * @since 2022-7-19
 */
@Documented
@Target({ElementType.TYPE, ElementType.METHOD, ElementType.CONSTRUCTOR, ElementType.FIELD})
@Public
public @interface Internal {
}

@Public

/**
 * 被标记的类，意味着是一个公共的稳定的接口
 *
 * @author DeveloperZJQ
 * @since 2022-7-19
 */
@Documented
@Target(ElementType.TYPE)
@Public
public @interface Public {
}

@PublicEvolving

/**
 * 标记类和方法供公众使用的注释，但接口在不断变化。
 *
 * @author DeveloperZJQ
 * @since 2022-7-19
 */
@Documented
@Target({ElementType.TYPE, ElementType.METHOD, ElementType.FIELD, ElementType.CONSTRUCTOR})
@Public
public @interface PublicEvolving {
}

@VisibleForTesting

/**
 * 这个注释声明一个函数、字段、构造函数或整个类型只在测试时可见。
 *
 * @author DeveloperZJQ
 * @since 2022-7-19
 */
@Documented
@Target({ElementType.TYPE, ElementType.METHOD, ElementType.FIELD, ElementType.CONSTRUCTOR})
@Internal
public @interface VisibleForTesting {
}