@Internal注解简介说明

@Internal 注解简介

`@Internal`是一种自定义注解(或某些框架中提供的注解)
   通常用于标记类、方法或字段
   表明它们是 “内部实现细节”
    不建议在外部代码中直接使用
=========================================================	
	@Internal注解的主要目的是向开发者传达一种设计意图
	  被标记的内容可能在未来版本中发生更改或移除
	  因此不应依赖这些内容

@Internal主要用途

1.标识内部实现细节
   - 被标记为`@Internal`类
       或
	 方法通常是框架或库的私有实现部分
       仅供内部调用。
   - 外部用户如果直接使用这些内容
       可能会导致代码在后续版本中无法正常工作

2.增强代码可读性
   通过显式标注
     开发者可以快速识别哪些内容是公开接口
	 哪些是内部实现

3.防止误用
   在静态分析工具或编译器插件的帮助下
    可禁止外部代码直接调用被标记为 `@Internal` 的内容。

定义 @Internal 注解

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Retention(RetentionPolicy.CLASS) // 注解在编译时保留，不会进入运行时
@Target({ElementType.TYPE, ElementType.METHOD, ElementType.FIELD}) // 可用于类、方法和字段
public @interface Internal {
    String value() default "This is an internal API and should not be used directly.";
}
 
使用 @Internal 标记内部类或方法

public class LibraryClass {

    @Internal
    public void internalMethod() {
        System.out.println("This is an internal method.");
    }

    public void publicMethod() {
        System.out.println("This is a public method.");
    }
}

@Internal注意事项

1.非强制性
   - `@Internal` 注解本身并不会阻止外部代码调用被标记的内容。
      它更多是一种约定和提示，
	   具体约束需要通过代码审查或工具（如 Lint 工具）来实现。

2.与其他注解的区别
   - `@Internal` 和 `@Deprecated` 不同：
     - `@Deprecated` 表示某个功能已经过时，不推荐继续使用。
     - `@Internal` 表示某个功能是内部实现细节，从未对外公开。
   - `@Internal` 和 `private/protected` 不同：
     - 访问修饰符（如 `private` 或 `protected`）限制了编译时的访问权限。
     - `@Internal` 更多是一种语义上的提示，
	   适用于无法使用访问修饰符的情况（例如公共 API 中的部分方法）。

3.框架中的实现
   - 某些框架（如 Spring、Guava 等）
      可能提供类似的注解(如 `@VisibleForTesting`)
	    用于标记仅限测试使用的代码。