模块描述文件强制依赖分层的核心是将架构约束转为机器可验证契约，在编译或ci阶段拦截越界访问；需选对载体（如archunit dsl、archguard配置或java模块元数据），覆盖字段、方法参数、泛型、注解四类变量级依赖场景，并配套ci卡点、ide提示与修复模板。
用模块描述文件强制执行变量依赖分层，核心不是“写文档”，而是把架构约束变成可验证、可执行的规则。它本质是将“人脑记忆的规范”转为“机器可检查的契约”，从而在编译或ci阶段就拦截越界访问。
一、选对载体：模块描述 ≠ README.md
模块描述文件必须具备解析性与可集成性，不能是纯文本说明。主流选择有三类：
-
ArchUnit DSL（Java）：直接在测试中定义分层规则，如
layer("Service").definedBy("..service..")，搭配mayOnlyBeAccessedByLayers("Controller")，运行rule.check(classes)即刻验证 -
ArchGuard 规则配置（YAML/JSON）：在
archguard-rules.yml中声明forbidden-dependencies，例如禁止ui模块导入data-jdbc包路径，支持正则匹配和通配符 -
Gradle/Maven 模块元数据（.module 或 pom.xml）：通过
<dependencymanagement></dependencymanagement>锁定版本，配合requires static（Java 9+模块系统）显式声明可导出包，未导出的包对外不可见
二、变量级依赖控制的关键细节
“变量依赖”常被误认为仅指字段引用，实际需覆盖四类场景：
-
字段类型引用：如
private UserRepository userRepo;——检查UserRepository所在包是否属于允许依赖的层 -
方法参数/返回值类型：如
public UserDto getUser(Long id)——若UserDto来自presentation层，而该方法在service层，则违反分层 -
泛型边界：如
ResponseEntity<orderentity></orderentity>——OrderEntity若属data层，出现在controller返回值中合理，但若出现在domain层类中则越界 -
注解类型：如
@Transactional（Spring）或@Query（JPA）——这些注解本身带语义约束，应限制其仅出现在特定层（如@Transactional只允许在service层方法上）
三、落地时必须配套的三件事
仅有描述文件不够，需形成闭环：
-
CI流水线卡点：将架构检查作为必过门禁，失败则阻断合并。ArchUnit测试跑在
test阶段，ArchGuard分析接入verify阶段，失败时输出具体违规类与调用链 - IDE实时提示：用IntelliJ插件（如ArchUnit Support）或VS Code扩展，在编码时高亮非法import，提前拦截而非等CI报错
-
违规修复模板化：对常见错误（如
controller直接newrepository），提供一键修复脚本，自动替换为构造器注入，并补全对应层接口
四、为什么能防架构腐化
腐化不是突然发生的，而是从一次“临时绕过”开始。模块描述文件的作用是：
- 把“不该这么写”的模糊认知，变成
ImportNotAllowedException这样的确定报错 - 让每次新增代码都接受同一套规则校验，避免新人因不了解历史约定而引入耦合
- 当业务压力大时，开发者仍可快速交付——因为规则已内建于工具链，无需额外决策成本
