Java 模块系统怎样导出反射需要的包

Java 模块系统里，exports 和 opens 都像是在“放行一个包”，但它们解决的不是同一件事：exports 面向其他模块的正常编译和公开 API 使用，opens 面向运行时反射，尤其是框架对非公开成员进行深度反射。如果框架只是调用公开方法，先考虑 exports；如果它要读取私有字段、调用非公开构造器或做对象序列化，通常需要 opens。

判断口诀是：编译器要直接调用公开类型，用 exports；框架要在运行时越过语言访问级别，用 opens。两者可以同时出现，但不应该因为一次反射报错就把整个模块改成 open module。

本文只讨论 JPMS 的模块边界与 Java 反射，不把“类能否被加载”“调用方是否声明 requires”和“私有成员是否允许深度访问”混成一个问题。

exports 和 opens 到底分别放开什么

exports com.example.api; 表示包中的公开类型可以作为模块 API 被其他可读模块使用。它适合服务接口、DTO 的公开方法或需要在编译期被调用的公共类，但不会自动让框架访问私有字段。

opens com.example.model; 表示该包在运行时对所有模块开放反射能力。Oracle 的 Module API 将开放包描述为允许调用方对包内所有类型进行深度反射，因此私有字段、包级成员和非公开构造器才有机会通过反射访问。开放并不等于把这些成员变成了普通 Java 代码可以直接调用的公开 API。

还要补上两个经常被忽略的前提：

• 调用方仍然要能看到目标模块。实际代码通常需要在调用方的 module-info.java 中写 requires com.example.domain;。
• “能找到类”不代表“能访问成员”。Class.forName、getDeclaredField 等发现动作与随后调用 setAccessible(true) 的权限判断是两步。

用 module-info.java 配出三种常见边界

假设库模块叫 com.example.domain，对外提供 com.example.api，同时有一个对象模型包供序列化框架读取私有字段。最小的模块描述可以这样写：

module com.example.domain {
    // 公开服务契约，允许其他模块在编译期正常调用
    exports com.example.api;

    // 只对框架开放深度反射，不把模型包作为普通 API
    opens com.example.model to com.example.framework;
}

这段配置使用了限定 opens：只有名为 com.example.framework 的模块得到深度反射权限。若框架和调用方很多，可以暂时使用无限定的 opens com.example.model;，但要意识到它会对所有模块开放该包。

如果一个包既要被其他模块直接调用公开类型，又要被框架访问私有成员，可以同时声明两条指令：

module com.example.domain {
    // 允许其他模块直接使用公开类型
    exports com.example.model;

    // 允许指定框架访问私有字段或非公开构造器
    opens com.example.model to com.example.framework;
}

如果写成 open module com.example.domain { ... }，模块中的所有包都会对所有模块开放深度反射。它适合确实以反射为核心的特殊模块，普通业务库更适合逐包、逐框架开放，避免把不需要反射的内部包一起暴露。

反射失败时先看访问目标，而不是盲加 exports

公开成员和私有成员的判断路径不同。假设框架通过反射读取 User 的私有字段：

package com.example.framework;

import java.lang.reflect.Field;

public final class FieldReader {
    public static Object readPrivateField(Object target, String fieldName)
            throws ReflectiveOperationException {
        // 只查找声明类自己的字段，避免误把继承层次当成模块开放问题
        Field field = target.getClass().getDeclaredField(fieldName);

        // trySetAccessible 失败时返回 false，适合框架给出明确诊断
        if (!field.trySetAccessible()) {
            throw new IllegalStateException(
                    "目标包没有向当前框架模块开放深度反射: "
                            + target.getClass().getPackageName());
        }

        // 读取成功后返回字段值；调用方仍应处理字段类型和业务空值
        return field.get(target);
    }
}

如果目标类处在另一个命名模块，且字段不是公开成员，exports 往往不足以让 trySetAccessible() 成功；目标包需要对当前框架模块执行 opens。直接调用 setAccessible(true) 在同样条件下通常抛出 InaccessibleObjectException，这个异常表示 Java 语言访问检查无法被抑制。

反过来，如果框架只需要调用一个公开方法：

package com.example.framework;

import com.example.api.UserService;

public final class ServiceCaller {
    public static String call(UserService service, String id) {
        // 公开 API 的直接调用依赖 exports 与 requires，不依赖 opens
        return service.findName(id);
    }
}

这时把 com.example.api 改成 opens 并不能替代公开 API 设计；框架要在编译期引用公开类型，仍然需要 exports。一个常见误区是看到“反射”两个字就统一加 opens，实际应该先区分反射对象是否需要突破私有访问级别。

用 Module API 确认当前调用方看到的边界

排查框架问题时，错误日志常只给出包名。可以把目标类所在模块、调用方模块和两个权限判断打印出来，重点看 isExported 与 isOpen 的结果。

package com.example.framework;

public final class ModuleBoundary {
    public static void print(Class> targetType) {
        // 目标模块来自被反射类，调用方模块来自当前框架类
        Module targetModule = targetType.getModule();
        Module callerModule = ModuleBoundary.class.getModule();
        String packageName = targetType.getPackageName();

        // isExported 关注普通公开访问，isOpen 关注深度反射
        System.out.printf(
                "target=%s caller=%s package=%s exported=%s open=%s%n",
                targetModule.getName(),
                callerModule.getName(),
                packageName,
                targetModule.isExported(packageName, callerModule),
                targetModule.isOpen(packageName, callerModule));
    }
}

Module.isExported(packageName, callerModule) 会考虑目标包是否至少向调用方模块导出；Module.isOpen(packageName, callerModule) 则直接回答该包是否向调用方开放。它们不会替你检查调用方是否声明了读取关系，所以日志还应结合 callerModule.canRead(targetModule) 一起看。

不要把 isExported 的运行时结果当成“只能通过 exports 获得”。Oracle API 明确说明，运行时对调用方开放的包也会被视为已导出；排查深度反射时，isOpen 才是更直接的指标。

按最小范围处理框架、测试和启动参数

很多项目把测试、序列化、依赖注入和代理生成都归为“反射”，但它们需要的范围可能不同。可以按下面顺序做决策：

1. 只调用公开类型和公开方法：在库模块写必要的 exports，调用方写 requires。
2. 只让一个框架读私有字段：使用限定 opens package to framework;，不要先改成无条件开放。
3. 多个框架都需要同一个模型包：逐个列出限定模块，并把这些框架模块纳入升级和审计清单。
4. 测试阶段临时验证边界：可以使用对应的 --add-opens module/package=target-module 作为启动参数，但它是部署配置，不应掩盖模块描述本身缺少的长期契约。
5. 只有模块所有包都确实以深度反射为主要用途时，才考虑 open module。

还要留意 --add-exports 与 --add-opens 的区别：前者补的是普通导出边界，后者补的是运行时深度反射边界。若生产环境必须加参数，建议把它写入启动脚本或部署清单，并注明对应框架和包，避免下一次升级后变成没人知道的隐式依赖。

一张表记住排查顺序

常见问题

写了 exports 还需要 opens 吗？

如果框架只使用公开 API，通常不需要。若它要让 setAccessible(true) 或 trySetAccessible() 访问私有成员，目标包还需要对调用方开放。

opens 会让私有字段变成公开字段吗？

不会。opens 是运行时反射边界，不改变 Java 源码层面的访问修饰符，也不等于其他模块可以直接写出对私有字段的访问语句。

为什么反射能拿到 Field，却不能读取值？

获取反射对象和启用访问权限是两个阶段。模块边界可能允许发现类和字段元数据，但不允许对非公开成员抑制访问检查；这时应检查 isOpen(packageName, callerModule)。

open module 是不是最省事的方案？

它最省配置，但开放范围最大。业务模块优先用单包、单框架的限定 opens，只有所有包都需要深度反射时才选择 open module。

最后可以把排查动作固定成一句话：先确认 requires 和普通 API 的 exports，再根据反射对象是否突破私有访问判断 opens，最后用 Module.isExported、Module.isOpen 和调用方模块名记录实际边界。这样处理后，模块描述文件和框架的反射契约会更清楚，升级时也不必靠不断追加启动参数碰运气。