必须将包级注解写在 package-info.java 文件中，因其是 java 唯一允许声明 elementtype.package 注解的特殊文件，该文件仅用于包声明、包注解和包级 javadoc，且需严格遵循格式与编码要求。
要让自定义注解作用于整个包，必须用 @Target(ElementType.PACKAGE)，并且只能写在 package-info.java 文件中——不能写在普通类、接口或任何其他 Java 文件里，否则编译直接报错：“Package annotations must be in file package-info.java”。
为什么必须用 package-info.java
ElementType.PACKAGE 对应的是“包声明”这一语法结构，而 Java 规定：包级别的注解只能出现在一个特定文件中，即 package-info.java。这个文件不是普通类，没有 class 声明，也不允许 public/private 修饰符，更不能继承或实现接口。
它本质是包的元数据载体，编译后生成 package-info.class，但源码中只做三件事：
• 声明包名（必须第一行，格式为 package com.example;）
• 添加包级注解（紧接在 package 声明之后）
• 可选地写包级 Javadoc 注释（放在 package 声明前）
正确创建和编写 package-info.java
在主流 IDE 中不能通过“新建类”方式创建该文件，因为 package-info 不是合法的 Java 标识符（含连字符）。正确做法有：
- Eclipse/IDEA：新建包时勾选 “Create package-info.java”
- 已存在包：在对应文件夹下手动新建文本文件，命名为
package-info.java，内容严格按顺序写：@YourPackageAnnotation(version = "1.0")<br>package com.example.mypackage;
- 注意：文件编码需为 UTF-8，首行不能有空行或注释，package 声明必须完整且唯一
配套注解定义要点
声明支持 PACKAGE 的注解时，需确保：
-
@Target(ElementType.PACKAGE)单独使用，或与其它目标组合（如{PACKAGE, TYPE}），但 PACKAGE 必须显式包含 -
@Retention(RetentionPolicy.RUNTIME)才能通过Package.getPackage("...").getAnnotations()在运行时读取 - 注解内方法建议设默认值，避免在
package-info.java中强制赋值（因无上下文）
验证是否生效
运行时可通过反射获取包注解：
Package pkg = Package.getPackage("com.example.mypackage");<br>if (pkg != null) {<br> for (Annotation ann : pkg.getAnnotations()) {<br> if (ann instanceof YourPackageAnnotation) {<br> System.out.println("包注解已加载");<br> }<br> }<br>}
若返回空数组，检查：
• package-info.java 是否在正确路径（与包名完全一致）
• 注解 @Retention 是否为 RUNTIME
• 包是否已被 JVM 加载（首次调用 Class.forName 同包类可触发加载）
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
