模块规则语法大全：modules-graph-assert正则规则写法完全指南与常见误区

模块规则语法大全modules-graph-assert正则规则写法完全指南与常见误区【免费下载链接】modules-graph-assertGradle plugin to keep your modules graph healthy and lean.项目地址: https://gitcode.com/gh_mirrors/mo/modules-graph-assertmodules-graph-assert 是一款让多模块项目依赖图谱保持健康精瘦的 Gradle 插件它的核心就是用regex - regex与regex -X regex这类正则语法编写模块规则约束哪些模块允许相互依赖。本文完整整理正则规则的所有语法要点、匹配细节和常见误区帮助新手一次写对模块依赖护栏避免规则写了却不生效。两种核心规则语法 规则统一配置在moduleGraphAssert代码块中两个属性定义见 GraphRulesExtension.kt属性分隔符语义典型用途allowed-白名单命中任意一条规则才通过整体分层管控restricted-X黑名单命中任意一条规则即失败精准封禁特定路径白名单规则regex - regexallowed左侧是依赖方模块右侧是被依赖方模块两侧都是正则表达式moduleGraphAssert { allowed [ :.* - :core, // 任何模块都可以依赖 :core :feature.* - :lib.* // feature 模块只能依赖 lib 模块 ] }项目中只要出现没有命中任何allowed规则的依赖assertModuleGraph任务就会失败并列出全部违规项校验逻辑见 OnlyAllowedAssert.kt。黑名单规则regex -X regexrestricted使用-X作为分隔符注意 X 是普通字母不是-语义与白名单相反——命中规则的依赖即为违规moduleGraphAssert { restricted [:feature-[a-z]* -X :forbidden-to-depend-on] }匹配与错误信息拼装实现在 RestrictedDependenciesAssert.kt失败时会逐条列出每个违规依赖命中的具体规则定位问题很快。常用正则写法速查表 ⚡想表达的需求规则写法左侧示例任意模块.*任意 feature 模块:feature[a-z]*带冒号前缀的模块:core、:.*feature 或 core 二者之一:(feature\|core)Groovy 中写\|任意数字[0-9]或\dGroovy 中写\\d匹配行为的 3 个隐藏细节 1. 整串匹配不是包含匹配规则生效时依赖对会被拼接成左模块 - 右模块或-X形式的单个字符串然后与你的正则做整串匹配见 RegexpDependencyMatcher.kt。直接推论:feature - :lib只匹配:feature - :lib这一条精确依赖它不会放行:feature2 - :lib需要写成:feature[a-z0-9]* - :lib无需手写^、$锚点默认全串匹配写了也不影响。ParseTest.kt 中有明确的边界用例:feature:[a-zA-Z]* -X :lib能匹配:feature:aboutX -X :lib但匹配不了:feature:aboutX -X :libx。2. 分隔符两侧的空格不能丢-与-X两边各有一个半角空格解析代码 Parse.kt 对子串做严格判断。写成:a- :b或:a - :b会在配置阶段直接抛出Incorrect format. Expected: regexp - regexp构建根本跑不起来。3. 捕获组与反向引用可用规则两侧都支持捕获组Groovy 中用\\1写反向引用反斜杠需双写。项目测试里的经典用法——只允许同一父功能下的兄弟子模块互相依赖allowed [:features:(\\S*):\\S* - :features:\\1:\\S*]这样:features:X:Y - :features:X:Z通过而:features:data:Y - :features:dat:Z被拦截完整示例见 ParseTest.kt。常见误区清单6 个高频坑 ⚠️黑名单用了-分隔restricted必须写-X误写:feature - :lib会直接报格式错误。忘记模块名开头的冒号Gradle 模块名通常形如:core规则里若不统一带上:前缀正则永远匹配不上。误以为allowed为空等于全部禁止allowed、restricted为空时对应断言会被整体跳过见 GraphRulesExtension.kt想收紧图谱必须先写下至少一条规则。忘了 Groovy 反斜杠转义规则字符串里\1、\d、\S都要双写为\\1、\\d、\\S。模块名与别名混用使用moduleNameAssertAlias给模块定型后规则应统一按别名或统一按真实名编写官方明确不推荐混用。断言结果里模块不见了开启 Gradle Configuration On Demand 时部分模块对插件不可见请加--no-configure-on-demand标志运行。进阶玩法按模块类型写规则 ️除了真实模块名还可以为任意模块设置ext.moduleNameAssertAlias Api让allowed/restricted直接按别名匹配。适合扁平化架构将模块分为 Api / Implementation / App 三类规则写成类型级约束allowed [Implementation - Api, App - Implementation, App - Api]渐进式迁移时可将待改造模块临时标为NeedsMigration并为其加上NeedsMigration - .*、.* - NeedsMigration两条豁免规则逐个迁回正式类型该策略详见 README.md。验证命令一条命令守住图谱 ✅规则写完后两种方式验证./gradlew assertModuleGraph ./gradlew check // check 会自动包含 assertModuleGraph如果希望每次构建都自动校验设置assertOnAnyBuild true若还想防止模块依赖退化成长链配合maxHeight 4约束以任一模块为根的依赖树高度即可。掌握了白名单/黑名单两种语法、整串匹配的细节和上表中的误区清单modules-graph-assert 的正则规则基本没有难写的部分。建议先写兜底规则、再逐条收紧让图谱护栏既严格又易维护。【免费下载链接】modules-graph-assertGradle plugin to keep your modules graph healthy and lean.项目地址: https://gitcode.com/gh_mirrors/mo/modules-graph-assert创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考