Java 反射调用私有方法为什么失败：MethodHandles 查找模式与模块边界

线上代码把一段反射调用从 Method.invoke 换成 MethodHandle 后，最容易遇到的不是“方法不存在”，而是 IllegalAccessException、IllegalAccessError 或模块访问失败。先记住一个判断：能不能找到私有方法，取决于创建 Lookup 的位置和能力，不取决于你有没有把方法名写对。

普通的 MethodHandles.lookup() 只代表调用者本身的访问权限；目标类在另一个包或命名模块时，应先核对可读性与 opens，再决定是否使用 privateLookupIn。

先把失败现场缩小到 Lookup

下面的示例故意把目标方法设成包可见，并让调用代码位于不同包。这样能稳定观察到访问检查，而不是依赖某个框架的代理实现。

package demo.target;

public final class TokenBox {
    private String normalize(String value) {
        return value.trim().toLowerCase();
    }
}

调用端如果直接使用自己的查找对象：

MethodHandles.Lookup lookup = MethodHandles.lookup();
MethodHandle handle = lookup.findVirtual(
        TokenBox.class,
        "normalize",
        MethodType.methodType(String.class, String.class));

这里可能得到 NoSuchMethodException 或 IllegalAccessException。前者表示名称、返回值或参数类型不匹配；后者表示方法存在，但当前 Lookup 没有通过访问检查的能力。不要先把所有异常都改成“反射不支持私有方法”。

为什么 publicLookup 也解决不了私有成员

publicLookup() 只适合公开 API。它不会因为目标类是 public 就自动获得私有成员权限。查找方法时，Java 还会检查声明类、成员修饰符、包关系和模块关系。

MethodHandles.Lookup publicOnly = MethodHandles.publicLookup();
// 私有 normalize 不会因为 TokenBox 是 public 而变得可查找
MethodHandle handle = publicOnly.findVirtual(
        TokenBox.class, "normalize",
        MethodType.methodType(String.class, String.class));

排查时先记录三个值：目标方法的实际声明类、Modifier.toString(method.getModifiers()) 的结果，以及调用方和目标类的模块名。三个值缺一个，后面的“加权限”建议都可能走偏。

用 privateLookupIn 修复同一模块内的访问

如果调用方已经被允许访问目标包，可以从调用方 Lookup 派生一个面向目标类的私有 Lookup：

MethodHandles.Lookup caller = MethodHandles.lookup();
MethodHandles.Lookup targetLookup = MethodHandles.privateLookupIn(
        TokenBox.class, caller);

MethodHandle normalize = targetLookup.findVirtual(
        TokenBox.class,
        "normalize",
        MethodType.methodType(String.class, String.class));

String result = (String) normalize.invokeExact(
        new TokenBox(), "  Alice ");
System.out.println(result); // alice

这段代码的关键不是“把反射改成 MethodHandles”，而是让派生出来的 Lookup 具备目标类上下文中的私有访问能力。privateLookupIn 仍然会检查模块可读性与包开放状态，失败时应把异常当成模块配置问题继续查。

跨命名模块时，先看 opens 而不是继续换 API

当 TokenBox 位于命名模块 billing.core 的 demo.target 包中，调用模块至少要能读取目标模块；目标包还需要按场景开放给调用模块。示例模块描述符可以写成：

module billing.core {
    exports demo.target;
    opens demo.target to billing.app;
}

module billing.app {
    requires billing.core;
}

exports 解决普通编译期和运行期公开访问，opens 解决深层反射相关的访问边界，二者不是同一个开关。若只是为了临时验证，可在启动参数中针对明确模块和包配置开放；生产配置应收敛到模块描述符，并保留变更记录。

若错误信息同时包含“module does not read”或“does not open”，先检查模块图和包名大小写。不断改 findVirtual、findSpecial 的组合，不能绕过模块系统的边界。

访问通过后，再核对 invokeExact 的类型

私有成员已经成功查找到，调用仍可能因为 WrongMethodTypeException 失败。MethodHandle 是强类型对象，invokeExact 要求调用点的返回值、接收者和参数类型都精确匹配。

System.out.println(normalize.type());
// (TokenBox,String)String

String ok = (String) normalize.invokeExact(new TokenBox(), " Bob ");
// Object bad = normalize.invokeExact(new TokenBox(), " Bob ");

如果确实需要允许可转换类型，使用普通的 invoke，但先写测试覆盖装箱、返回值和 null。对核心路径而言，我更建议保留 invokeExact，让签名变化尽早暴露。

一张清单判断到底是哪一层出错

• 名称或参数不对：核对 MethodType，确认实例方法的接收者不是误写进参数列表。
• 成员存在但不可访问：检查 Lookup 的创建位置、目标类修饰符和包关系。
• 跨命名模块失败：确认调用模块能读取目标模块，目标包按最小范围配置 opens。
• 查找成功但调用失败：打印 handle.type()，优先排查 invokeExact 的静态类型。
• 依赖框架内部类：不要把临时开放内部包当作长期 API，优先改用公开扩展点。

复查时至少保留一个正例和两个反例：公开方法可查找、私有方法在未开放包中失败、开放后调用成功。这样升级 JDK 或调整模块描述符时，测试能告诉你变化发生在访问边界还是调用签名。

总结

MethodHandles 的查找失败通常是权限模型在正常工作。先区分方法不存在、Lookup 无权访问、模块未读取或未开放，再用 privateLookupIn 和精确的 MethodType 处理对应层级。只要把 Lookup 来源、模块关系和句柄类型记录下来，私有方法调用就不再是靠试错换 API。

相关问题

privateLookupIn 会永久改变目标类权限吗？

不会。它返回一个新的 Lookup 对象，权限随这个能力对象传播；不要把它无边界地交给不可信代码。

公开方法也需要 privateLookupIn 吗？

通常不需要。公开成员优先使用普通 Lookup 或 publicLookup，只有在明确需要目标类上下文或特殊访问时才考虑派生 Lookup。

为什么 Method.invoke 能调用，MethodHandle 却失败？

两者的访问检查入口和调用类型约束不同。不要把一个 API 的成功当作另一个 API 必然成功，分别检查模块开放状态与句柄签名。