# Jakarta Persistence (JPA)

> For the complete documentation index, see [llms.txt](https://www.jetbrains.com.cn/help/idea/llms.txt).

> **TL;DR**
> 所需插件： [Jakarta EE：持久性 (JPA)](https://plugins.jetbrains.com/plugin/20202)（捆绑）

[Jakarta Persistence](https://jakarta.ee/specifications/persistence/)（JPA），前身为 Java Persistence API，是用于在 [Java Enterprise](java-ee.html)应用程序中管理关系数据的 Java 规范。

Procedure: 启用 Jakarta EE：持久性（JPA）插件

此功能依赖于 [Jakarta EE: Persistence ​(JPA)​](https://plugins.jetbrains.com/plugin/20202)插件，该插件在 IntelliJ IDEA 中默认捆绑并启用。 如果相关功能不可用，请确保您没有禁用插件。

1. 按 `Ctrl+Alt+S` (Windows), `⌘ Comma` (macOS), `⌘ Comma` (IntelliJ IDEA Classic (macOS)), `⌘ Comma` (macOS System Shortcuts), `Ctrl+Alt+S` (XWin), `Ctrl+Alt+S` (GNOME), `Ctrl+Alt+S` (KDE), `Ctrl+Alt+S` (Emacs), `Ctrl+Alt+S` (Sublime Text), `⌘ Comma` (Sublime Text (macOS)), `Ctrl+Alt+S` (Visual Studio), `⌘ Comma` (Visual Studio (macOS)), `Ctrl+Alt+S` (NetBeans), `Ctrl+Alt+S` (Eclipse), `⌘ Comma` (Eclipse (macOS)) 打开设置，然后选择  `插件` 。

2. 找到  Jakarta EE: Persistence ​(JPA)​  插件并点击   启用  。

IntelliJ IDEA 提供以下内容：

* 与 JPA 相关的编码支持。

* 用于管理 JPA 配置 `persistence.xml` 和对象关系映射 `orm.xml` 文件的专用面。

* 用于管理 JPA 项目项、创建配置文件和持久类、在编辑器中导航到相关源代码、打开图表和控制台等的 [Persistence](persistence-tool-window.html) 工具窗口。

* 可从 [持久性](persistence-tool-window.html) 工具窗口访问的实体关系 (ER) 图。

* 通过导入数据库架构或 EJB 部署描述符文件来生成托管实体类及其对象关系映射的功能 `ejb-jar.xml` 。

* 用于编写和运行 JPQL 查询及分析查询结果的 [JPA console](using-jpa-console.html)。

Procedure: 创建一个新的 Jakarta EE 项目并使用 JPA。

1. 打开   新建项目  向导：

* 如果位于主屏幕，请选择 `![加号](https://resources.jetbrains.com.cn/help/img/idea/2026.3/intellij.platform.icons.expui.general.add.svg) 新建 | ![文件夹图标](https://resources.jetbrains.com.cn/help/img/idea/2026.3/intellij.platform.icons.expui.nodes.folder.svg) 项目……` 。

* 如果已打开另一个项目，请转到 `文件 | 新建 | 项目` 。

2. 从左侧的   生成器   列表中，选择 ![Jakarta EE 徽标](https://resources.jetbrains.com.cn/help/img/idea/2026.3/intellij.java.ultimate.icons.icons.javaee.newui.jakartaEE.svg)   Jakarta EE  。

![Jakarta EE 项目向导的第一步](https://resources.jetbrains.com.cn/help/img/idea/2026.3/jakarta_new_project_step_1_web.png)

3. 设置 [Jakarta EE 项目设置](new-project-wizard.html#java-ee)。

准备就绪后，点击   下一步  。

4. 从   版本   下拉菜单中选择要使用的 Jakarta EE 版本。

5. 从   规范   列表中选择   持久化（JPA）  。

如果您不打算自己实现 JPA 规范的所有接口，您还需要包含一个持久性框架。 默认情况下，IntelliJ IDEA 提供对以下持久化框架的支持：

* EclipseLink 是参考实现。 如果您只是尝试一些东西，请选择它。

* Hibernate 是最最受欢迎的的实现。 如需更多信息，请参阅 [Hibernate](hibernate.html)。

![使用 JPA 和 Hibernate 的新 Jakarta EE 项目](https://resources.jetbrains.com.cn/help/img/idea/2026.3/java_enterprise_new_project_step_2_hibernate.png)

6. 点击   创建  。

有关创建 Jakarta EE 项目的更多信息，例如如何设置应用程序服务器，请参阅 [教程：您的第一个 Jakarta EE 应用程序](creating-and-running-your-first-jakarta-ee-application.html)。

Procedure: 向现有项目添加 JPA

1. 在编辑器中打开构建文件（  `pom.xml`  或  `build.gradle` ，具体取决于项目中使用的 [构建工具](build-tools.html)）。

2. 添加 JPA 库，并确保其版本与项目的其余部分匹配：

Maven:

Jakarta EE
: ```XML
: <dependency>
: <groupId>jakarta.persistence</groupId>
: <artifactId>jakarta.persistence-api</artifactId>
: <version>3.2.0</version>
: </dependency>
:
: ```

Java EE
: ```XML
: <dependency>
: <groupId>javax.persistence</groupId>
: <artifactId>javax.persistence-api</artifactId>
: <version>2.2</version>
: </dependency>
:
: ```

Gradle (Groovy):

Jakarta EE
: ```GROOVY
: implementation 'jakarta.persistence:jakarta.persistence-api:3.2.0'
:
: ```

Java EE
: ```GROOVY
: implementation 'javax.persistence:javax.persistence-api:2.2'
:
: ```

Gradle (Kotlin):

Jakarta EE
: ```KOTLIN
: implementation("jakarta.persistence:jakarta.persistence-api:3.2.0")
:
: ```

Java EE
: ```KOTLIN
: implementation("javax.persistence:javax.persistence-api:2.2")
:
: ```

3. 按 `Ctrl+Shift+O` (Windows), `Ctrl+Shift+O` (macOS), `Ctrl+Shift+O` (IntelliJ IDEA Classic (macOS)), `Ctrl+Shift+O` (macOS System Shortcuts), `Ctrl+Shift+O` (XWin), `Ctrl+Shift+O` (GNOME), `Ctrl+Shift+O` (KDE), `Ctrl+Shift+O` (Emacs), `Ctrl+Shift+O` (Sublime Text), `Ctrl+Shift+O` (Sublime Text (macOS)), `Ctrl+Shift+O` (Visual Studio), `Ctrl+Shift+O` (Visual Studio (macOS)), `Ctrl+Shift+O` (NetBeans), `Ctrl+Shift+O` (Eclipse), `Ctrl+Shift+O` (Eclipse (macOS)) 导入更改。

有关使用构建工具的更多信息，请参阅 [Maven](maven-support.html) 或 [Gradle](gradle.html)。

Procedure: 共享 facet 设置

您可以通过创建自定义 Facet，并将带有  `.iml`  扩展程序的模块文件添加到版本控制系统来更改和共享设置。

例如，为了在您的团队中共享选定的数据源用于 JPA，您可以创建一个 JPA facet 并提交其设置。

1. 在主菜单中，转到  `文件 | 项目结构`  或按 `Ctrl+Alt+Shift+S` (Windows), `⌘ ;` (macOS), `⌘ ;` (IntelliJ IDEA Classic (macOS)), `⌘ ⇧ Comma` (macOS System Shortcuts), `Ctrl+Alt+Shift+S` (XWin), `Ctrl+Alt+Shift+S` (GNOME), `Ctrl+Alt+Shift+S` (KDE), `Ctrl+Alt+Shift+S` (Emacs), `Ctrl+Alt+Shift+S` (Sublime Text), `⌘ ;` (Sublime Text (macOS)), `Ctrl+Alt+Shift+S` (Visual Studio), `⌘ ;` (Visual Studio (macOS)), `Ctrl+Alt+Shift+S` (NetBeans), `Ctrl+Alt+Shift+S` (Eclipse), `⌘ ;` (Eclipse (macOS))。 然后选择   模块  。

2. 请确保已选择要添加 Facet 的模块，然后点击模块列表上方的 !["添加"按钮](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app-client.expui.general.add.svg)。 在可用 Facet 列表中，选择   JPA  。

![添加 JPA Facet](https://resources.jetbrains.com.cn/help/img/idea/2026.3/add_jpa_facet.png)

右侧将会显示   描述符  部分。

3. 在   描述符  部分，点击 !["添加"按钮](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app-client.expui.general.add.svg)并选择描述符类型。 创建一个新文件或指定现有文件的路径。

4. 重新打开项目。 之后，更改将显示在已添加 Facet 的模块的  `.iml`  文件中。

![模块文件中的 JPA 面向](https://resources.jetbrains.com.cn/help/img/idea/2026.3/jpa_facet_iml.png)

5. [将 .iml 文件添加](adding-files-to-version-control.html#add-files-to-vcs)到版本控制系统。