如何应用 requires transitive 实战简化复杂依赖链下的变量引用路径并提升可维护性

在 Java 9 引入模块系统（JPMS）之后，模块之间的依赖关系必须显式声明。这带来了更强的封装性，但也带来一个新问题：当模块 A 依赖模块 B，而模块 B 的公开 API 中又暴露了模块 C 中的类型时，模块 A 想使用这些类型就必须自己再声明对模块 C 的依赖，否则编译直接失败。requires transitive 指令正是为解决这种依赖传递问题而设计的，它能让依赖关系沿着模块链自动向下传递，从而简化变量引用路径，减少重复声明，让整体结构更清晰。

一、普通 requires 与 requires transitive 的本质区别

在 module-info.java 中，requires 表示当前模块在编译期和运行期需要依赖另一个模块，但这个依赖是模块内部的实现细节，不会传递给依赖自己的下游模块。而 requires transitive 表示这个依赖不仅当前模块需要，任何依赖当前模块的模块也隐式地获得了对该模块的依赖资格。

换句话说，requires 是私有依赖，requires transitive 是公共依赖。判断标准很简单：如果一个模块导出的公开 API（被 exports 的包中的公开类型）的签名中出现了另一个模块的类型，比如方法参数、返回值或者父类来自其他模块，那么这个依赖就必须标记为 transitive，否则下游模块在编译时会遇到“不可见模块”的错误。

举个典型场景：模块 com.example.service 提供了一个方法，返回值类型是 java.util.List。虽然代码中从未显式 import，但由于公开签名暴露了该类型，就必须写 requires transitive java.base 吗？其实不需要，因为 java.base 是所有模块隐式依赖的默认模块。但如果暴露的是第三方模块的类型，就必须显式声明为传递依赖。

二、多模块项目实战：完整配置与编译运行

下面通过一个三层依赖链的实例演示具体用法。假设有三个模块：com.example.model（基础数据模型）、com.example.api（对外接口层）、com.example.app（应用层）。api 模块的公开方法返回 model 模块中的 User 对象，app 模块直接调用该方法并访问 User 的属性。

首先创建 model 模块，目录结构为 src/com.example.model/com/example/model/，包含实体类与模块描述文件：

package com.example.model;

public class User {
    private final String name;
    private final int age;

    public User(String name, int age) {
        this.name = name;
        this.age = age;
    }

    public String getName() { return name; }
    public int getAge() { return age; }
}

对应的 module-info.java 写法如下：

module com.example.model {
    exports com.example.model;
}

接着是 api 模块。关键点在于：UserApi 的公开方法签名暴露了 User 类型，因此对 model 的依赖必须写成 requires transitive：

package com.example.api;

import com.example.model.User;

public class UserApi {
    public User findUser(String name) {
        return new User(name, 28);
    }
}

module com.example.api {
    requires transitive com.example.model;
    exports com.example.api;
}

最后是 app 模块。注意它的 module-info.java 中没有声明对 model 的依赖，但由于 api 模块使用了传递依赖，app 依然可以直接引用 User 类型：

package com.example.app;

import com.example.api.UserApi;
import com.example.model.User;

public class Main {
    public static void main(String[] args) {
        User user = new UserApi().findUser("张三");
        System.out.println(user.getName() + " 年龄: " + user.getAge());
    }
}

module com.example.app {
    requires com.example.api;
}

如果 api 模块中把 requires transitive 改成普通的 requires，app 模块在编译时会直接报错，提示 com.example.model 对 app 不可见，这就是传递依赖发挥作用的最直观证明。

三、使用 requires transitive 的最佳实践与常见误区

第一，不要滥用传递依赖。只有当公开 API 的签名确实暴露了其他模块的类型时才使用 requires transitive，纯粹的内部实现依赖应该用普通 requires。滥用会让依赖关系网越来越模糊，下游模块可能隐式依赖了大量自己根本不需要的模块，反而损害可维护性。

第二，理解它对可读性的双重影响。一方面，下游模块的 module-info.java 更简洁，不用重复声明间接依赖；另一方面，依赖关系从显式变成了隐式，排查问题时需要借助工具。可以使用 java --describe-module 模块名 命令查看模块的传递依赖，也可以用 jdeps --module-path 分析整个项目的依赖树，快速定位某个类型的真实来源模块。

第三，老项目迁移时容易踩坑。许多遗留代码把工具类模块当作万能依赖，如果将其所有依赖都改成 transitive，等于变相绕过了模块系统的封装检查。正确做法是逐步梳理：先保持普通 requires，编译报错时分析报错位置是否属于公开签名暴露，是则改 transitive，属于内部实现则应该调整代码结构，把不该暴露的类型收回到非导出包中。这样一步步整理后，模块边界的定义会越来越准确，整个系统的依赖链路也会更加清晰、更易长期维护。

requires transitiveJava模块化依赖传递修改时间：2026-08-31 09:22:26