如何让Java主动抛出编译错误，限制自定义类仅在单元测试中使用

原生能力说明 #

Java 本身没有内置支持「限定类仅允许在单元测试中引用、生产代码引用直接触发编译错误」的语法特性，默认访问修饰符、常用的@VisibleForTesting注解仅能做可见性提示或限定包内访问，无法满足跨包测试可用、生产全禁用的强校验需求。

可落地实现方案 #

方案1：构建工具路径隔离（成本最低，零侵入） #

直接将自定义工具类放在项目的src/test/java目录下，而非生产代码的src/main/java目录：

• Maven/Gradle 等标准构建工具默认只会将src/test/java下的类加载到测试类路径，生产编译、打包阶段的类路径中完全不存在该工具类，生产代码只要引用就会直接抛出「找不到类」的编译错误
• 所有src/test/java下的单元测试无论归属哪个包，都可以正常调用该工具类，完美匹配跨包测试使用的需求

方案2：自定义注解+编译期注解处理器（适合工具类必须放在生产目录的场景） #

如果因为历史原因工具类必须放在src/main/java下，可以通过编译期校验实现强限制：

1. 自定义标记注解，示例代码：

@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.CLASS)
public @interface OnlyForTest {
}

2. 开发编译期注解处理器，逻辑为：扫描所有代码中对标记了@OnlyForTest的类/方法的引用，判断引用所在文件的路径是否为生产代码路径（src/main/java），如果命中则直接抛出编译错误
3. 将注解处理器绑定到项目生产编译流程，测试编译阶段单独配置跳过该校验即可实现需求

方案3：静态代码扫描规则校验 #

在团队的静态代码检查工具（SonarQube、自定义代码检查插件等）中新增规则，检测到生产代码引用测试专用工具类就阻断代码合并流程，该方案为CI流程层面的校验，适合不希望强制阻断本地编译的团队。

内容的提问来源于stack exchange，提问作者yizhou wang