产品 API 深水区：Java、Kotlin、JavaScript、Python 与 Database

产品专属 API 的难点不在于写一个 <depends>，而在于把“依赖、类加载、测试、兼容产品、降级路径”作为一组工程约束处理。官方文档给出了模块和插件 ID、产品开发入口、测试框架入口，本章把这些信息整理成可执行的设计清单。

先判断能力边界

不要用 IDE 名称推断 API 是否可用。应按能力声明依赖：

能力	plugin.xml / 模块 ID	Gradle 2.x 依赖	典型测试框架
Java PSI、检查、重构、测试	com.intellij.java 或 com.intellij.modules.java	bundledPlugin("com.intellij.java")	TestFrameworkType.Plugin.Java
Kotlin PSI / Analysis API	org.jetbrains.kotlin	bundledPlugin("org.jetbrains.kotlin")	Kotlin 插件测试基础设施，按目标版本配置 K1/K2
JavaScript / TypeScript	JavaScript	bundledPlugin("JavaScript")	TestFrameworkType.Plugin.JavaScript
Python	com.intellij.modules.python	目标 IDE 或 Python 插件依赖	以 PyCharm 或安装 Python 插件的 IDE 运行 fixture
Database / SQL	com.intellij.database	bundledPlugin("com.intellij.database")	以 DataGrip / Database Tools 沙盒运行集成验证

com.intellij.modules.platform 仍应作为基础依赖声明。对于 JavaScript、com.intellij.database 这类不是平台模块的捆绑插件，官方 WebStorm 和 DataGrip 文档都特别强调：如果只声明插件依赖而没有声明 com.intellij.modules.platform，插件可能被当作 legacy plugin，从而不能在目标产品中加载。

Java：优先复用 PSI Cookbook 和 UAST

Java 支持已经从平台中拆为 com.intellij.java 插件。只要代码引用 Java PSI、Java 检查、Java 重构、JUnit/TestNG 相关测试基类，就应同时配置 Gradle 依赖和 plugin.xml 依赖。

dependencies {
    intellijPlatform {
        intellijIdea("2025.2")
        bundledPlugin("com.intellij.java")
        testFramework(org.jetbrains.intellij.platform.gradle.TestFrameworkType.Plugin.Java)
    }
}

<depends>com.intellij.modules.platform</depends>
<depends>com.intellij.java</depends>

Java 代码模型优先用 PsiClass、PsiMethod、PsiField 等 PSI API。若功能面向多 JVM 语言，例如“检测 Spring 注解”“为 Java/Kotlin 都提供行标记”，优先评估 UAST，而不是为 Java 和 Kotlin 各写一套结构遍历。UAST 不能覆盖所有语言细节，涉及 Kotlin 类型推断、symbol 解析或 K2 行为时仍要回到 Kotlin Analysis API。

Java 功能的验收至少包括：

• Java 文件、测试文件、library class、generated source 各一组 fixture。
• Dumb Mode 下不会触发索引未就绪异常。
• 读 PSI 在 read action 内完成，写 PSI 使用 command + write action。
• Plugin Verifier 覆盖最低支持 IDEA 与最新稳定 IDEA。

Kotlin：面向 K2 迁移到 Analysis API

Kotlin 插件 ID 是 org.jetbrains.kotlin。官方 IDEA 页面明确指出：Analysis API 自 2024.2 可用；从 IntelliJ IDEA 2025.1 起，K2 Kotlin mode 默认启用。新插件不应继续把 K1-only 解析逻辑当作长期基础。

<depends optional="true" config-file="with-kotlin.xml">org.jetbrains.kotlin</depends>

with-kotlin.xml 中只注册 Kotlin 相关扩展：

<idea-plugin>
  <extensions defaultExtensionNs="com.intellij">
    <annotator
        language="kotlin"
        implementationClass="com.example.kotlin.ExampleKotlinAnnotator"/>
  </extensions>
</idea-plugin>

工程上建议把 Kotlin 能力放进单独源码集或模块，主插件只暴露稳定 facade：

interface JvmSymbolReader {
    fun findPublicApiNames(file: PsiFile): List<String>
}

Java 实现可以基于 Java PSI，Kotlin 实现基于 Analysis API。主流程只依赖接口，避免在没有 Kotlin 插件的产品中加载 Kotlin 类。

Kotlin 测试要显式覆盖：

• K2 默认模式。
• 最低支持版本仍使用 K1 时的兼容路径。
• Java/Kotlin mixed project。
• Kotlin script、multiplatform source set 或 generated source，如果插件声称支持这些场景。

JavaScript / TypeScript：以 WebStorm 能力为准

JavaScript 插件 ID 是 JavaScript。WebStorm 插件项目在 Gradle 2.x 中应使用目标产品依赖和 bundled plugin：

dependencies {
    intellijPlatform {
        webstorm("2025.2")
        bundledPlugin("JavaScript")
        testFramework(org.jetbrains.intellij.platform.gradle.TestFrameworkType.Plugin.JavaScript)
    }
}

<depends>com.intellij.modules.platform</depends>
<depends>JavaScript</depends>

如果插件同时支持 IDEA、WebStorm、PyCharm 等产品，JavaScript 功能通常应做成可选依赖：

<depends optional="true" config-file="with-javascript.xml">JavaScript</depends>

实现时不要把 TypeScript、Vue、React、Angular 等框架能力混为同一个硬依赖。基础 JS/TS 能力来自 JavaScript；框架插件、WebSymbols/PolySymbols、Node/npm 工具链能力需要单独确认可用性。对项目模型或包管理器做假设前，应检查当前项目是否真的存在对应配置文件、library、content root 和索引。

JavaScript 功能的典型测试矩阵：

• .js、.ts、.tsx、package.json workspace。
• 没有 Node.js 解释器配置的项目。
• WebStorm 目标产品与 IDEA Ultimate 安装 JS 插件的目标产品。
• 缺少 JavaScript 插件的产品，主插件仍能加载。

Python：不要假设 PyCharm 等于 Python API

官方兼容表把 Python 能力标为 com.intellij.modules.python，适用于 PyCharm 以及安装 Python 插件的其他产品。Python API 常见用途包括 Python PSI、检查、重构、测试框架、解释器/SDK 相关能力。

建议把 Python 功能设计成可选能力：

<depends optional="true" config-file="with-python.xml">com.intellij.modules.python</depends>

Python 项目里的“能解析 PSI”和“能运行代码”是两件事。很多插件只需要 Python PSI 和索引；需要运行、调试、包管理或虚拟环境时，还要处理 SDK/解释器为空、远程解释器、conda/venv、pytest/unittest 等差异。文档或 UI 上不要承诺“支持 PyCharm”就等于支持所有 Python 项目形态。

Python 功能验收建议：

• 无解释器项目能正常禁用运行相关入口。
• 有本地 venv/conda 的项目可以发现 SDK。
• 只依赖 PSI 的检查在轻量 fixture 中可测。
• 运行/调试相关功能在真实 PyCharm 沙盒或目标产品中手动验证。

Database / SQL：把 DataGrip 和 Database Tools 当作目标运行时

Database Tools and SQL 的插件 ID 是 com.intellij.database。官方 DataGrip 文档给出的 Gradle 2.x 最小配置是目标产品加 bundled plugin：

dependencies {
    intellijPlatform {
        datagrip("2025.2")
        bundledPlugin("com.intellij.database")
    }
}

<depends>com.intellij.modules.platform</depends>
<depends>com.intellij.database</depends>

Database API 涉及 SQL PSI、数据源、查询执行、schema introspection、completion、inspection、refactoring 等能力。工程上要特别区分三层：

层级	常见能力	风险
SQL PSI	解析 SQL 文件、引用、补全、检查	方言差异、索引状态
数据源模型	database/schema/table/column 元数据	连接未配置、introspection 未完成
执行与控制台	查询、结果集、console 交互	用户凭据、远程连接、事务和权限

默认策略应是“只读优先”。插件如果要生成 SQL、修改数据源或执行查询，必须让用户确认目标连接、schema 和语句，并把不可恢复操作交给用户显式触发。测试上至少覆盖 DataGrip 和一个带 Database Tools 的非 DataGrip IDE，例如 IDEA Ultimate 或 WebStorm 安装 Database Tools 的场景。

可选依赖的代码组织

可选 XML 只能控制扩展注册，不能阻止 JVM 类加载错误。以下写法有风险：

class MainService {
    private val jsHelper = com.intellij.lang.javascript.psi.JSFile::class.java
}

即使 JS 是 optional dependency，这个类只要在主插件初始化路径被加载，就可能在缺少 JavaScript 插件的产品中失败。推荐结构：

plugin-core/
  com.example.core.*
plugin-java/
  com.example.java.*
plugin-kotlin/
  com.example.kotlin.*
plugin-js/
  com.example.javascript.*
plugin-database/
  com.example.database.*

主模块只依赖平台稳定 API。各产品模块通过可选描述符注册实现，并在类名、service、extension point 上保持边界清晰。

发布前产品矩阵

产品专属 API 插件发布前，至少维护一个矩阵：

场景	必测项
最低支持 IDE build	插件能安装、启动、核心功能可用
最新稳定 IDE build	Plugin Verifier + 手动 smoke test
每个目标产品	对应产品沙盒中真实启动
缺少可选依赖	主插件能加载，功能入口隐藏或降级
安装可选依赖	可选功能出现且不会污染其他产品
Remote Development	后端/前端依赖和 UI 位置符合 Split Mode

如果 Marketplace 展示的兼容产品与预期不一致，优先检查 plugin.xml 的 <depends> 和 Gradle 依赖，而不是在 Marketplace 页面上手动修正认知。

参考来源

• Plugin Compatibility with IntelliJ Platform Products
• Plugin Dependencies
• IntelliJ IDEA Plugin Development
• WebStorm Plugin Development
• DataGrip Plugin Development
• UAST