SuperAPI AI 工具集

extract-module

编程与开发

查看项目

更新于 10-16 07:07

技能介绍

用途

extract-module 是一份面向 IntelliJ 平台插件开发的指南,用于把某个插件模块的依赖变为可选:将该依赖相关的代码移动到一个独立的内容模块(content module)中。

目标是:宿主模块在新模块缺失时仍能正常工作,在新模块存在时行为保持一致。

两种模式

  • Pattern A — 简单移动:所有触及依赖 X 的代码都集中在少数文件中,且宿主模块内没有调用者,可整体移动这些文件。
  • Pattern B — 扩展点(EP):宿主模块的核心文件里散布着对 X 的引用。此时在宿主模块中引入一个 EP 接口(不导入 X),在新模块中实现它,并用空安全的静态辅助方法替换对 X 的直接调用。

主要步骤

  1. 创建模块目录,包含 resources(模块描述符 intellij.<module-name>.xml)、src(源码,目录需与包名匹配)以及 intellij.<module-name>.iml。
  2. 编写 .iml 文件,使用 JAVA_MODULE 类型,配置 content、sourceFolder、inheritedJdk、sourceFolder、jetbrains-annotations 库以及宿主模块依赖。规则:不要在 <sourceFolder> 上使用 packagePrefix,改用匹配的目录结构;.iml 文件以规范形式序列化,不加尾随换行、不重排。
  3. Kotlin 模块必须添加 kotlin-stdlib 库依赖,否则会出现“Cannot access built-in declaration 'kotlin.Any'”这类误导性错误,实际是整个 stdlib 缺失。
  4. 编写模块描述符 XML。若新模块中的类被另一个插件直接使用,需在 <idea-plugin> 根上设置 visibility:internal(同一 monorepo 内的其他插件)或 public(面向外部第三方插件的 API)。生成器管理 <dependencies> 区域,手动依赖需写在 <!-- region --> 标记之前、同一个 <dependencies> 标签内,不要创建第二个独立的 <dependencies> 块。
  5. 包与源文件约定:新代码一律使用 Kotlin;仅移动文件时保持原类型。源文件目录必须与包名匹配,包名遵循 com.<module-name> 约定。需保持 freemium 可用性一致。
  6. 在宿主模块声明 EP(仅 Pattern B),使用 qualifiedName,格式为 com.intellij.<language/framework, lowercase>.<epNameLikeThisOne>。EP 接口写在宿主模块中(不导入 X),提供 @JvmStatic 伴生辅助方法,在 EP 缺失时优雅返回 no-op 默认值。实现注册在新模块的 XML 中。
  7. 多方法 EP 打包与不透明状态模式:当库操作构成生命周期时,将所有相关操作打包进一个 EP;当需要在调用间传递宿主无法导入的类型化状态时,使用 Any? 作为状态类型,实现内部用 @Suppress("UNCHECKED_CAST") 转换。
  8. 在插件中注册新模块:plugin.xml 添加 <module> 内容条目,plugin-content.yaml 添加 jar 条目,并用 bun build/jps-module.mjs register 注册模块。
  9. 修复被移除传递依赖的下游消费者:为受影响的插件 XML 添加显式依赖,必要时添加 <module> 与 .iml 的 orderEntry,并确保新模块 XML 设置 visibility="public"。
  10. Kotlin open:若移动的类被其他模块或插件继承,或内部类被匿名继承,需将外层类和相关内部类标记为 open。
  11. git add 所有新文件。

变更后必须运行的命令

  • 任何 .iml 变更后:./build/jpsModelToBazel.cmd
  • 任何 .iml、插件 XML 或模块结构变更后:./bazel.cmd run //platform/buildScripts:plugin-model-tool,预期输出 ✓ All files unchanged。

必须通过的测试

  • AllProductsPackagingTest(打包验证)
  • IntelliJProjectPackageNamesTest(包命名验证)
  • PluginsAvailableInIdeaFreeModeTest(IDEA Free 模式可用性验证)

三者需逐个运行,全部通过才算完成。

常见陷阱

指南列出了多种陷阱及修复方式,包括:.iml 中使用 packagePrefix、包名与模块名不匹配、EP 使用 name 而非 qualifiedName、手动 <dependencies> 块位置错误、模块注册方式不当、新文件未 git add、跳过 plugin-model-tool、新源文件用 Java 创建、移除传递依赖破坏调用者、跨插件继承 final 类、文件移动但包声明或物理目录未同步、Java→Kotlin 转换后的可空重写不匹配、val lambda 中的 return@label、Kotlin 接口常量从 Java 访问、Kotlin 定义的 getXxx() 未自动暴露为属性、object : JavaInterface() 带括号、顶层 Kotlin 函数从 Java 导入、移除依赖后的超类型级联问题等。

适用场景与限制

本指南适用于 IntelliJ 社区仓库中需要将插件可选依赖抽取为独立内容模块的开发者。它依赖 Bazel 构建、JPS 模块模型以及仓库内的生成器与测试工具。指南未提供与具体产品收费、价格、平台或效果相关的信息。