# 教程：您的第一个 RESTful web service

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

本教程讲述如何在 IntelliJ IDEA 中创建一个简单的 RESTful 网络服务并将其部署到  Tomcat   GlassFish  应用服务器上。 当您通过网络浏览器访问特定 URL 或以其他方式向该 URL 发送 GET 请求时，该服务将输出  `您好，世界！` 。 请使用本页面顶部的切换器查看其他应用服务器的说明。

您将创建一个新的 Java Enterprise 项目，添加必要的 Java 代码，告诉 IntelliJ IDEA 您的  GlassFish   Tomcat  服务器的位置，然后使用运行配置来构建构件，启动服务器，并将构件部署到服务器上。

您将需要以下内容：

|  相关插件  |     默认情况下， IntelliJ IDEA Ultimate 会捆绑并启用以下必需插件。 如果某些功能无法正常运行，请确保以下插件已启用：        * Jakarta EE 平台    * Jakarta EE：应用服务器    * Jakarta EE：Web/Servlets    * Jakarta EE：RESTful Web 服务 (JAX-RS)    * Tomcat 和 TomEE      按照 [插件](managing-plugins.html) 中的说明安装并启用  GlassFish  插件。     |
|  Java SE Development Kit (JDK) 版本 1.8 或更高版本  |  您可以按照 [Java Development Kit (JDK)](sdk.html#jdk) 中的说明直接从 IntelliJ IDEA 获取 JDK，或手动下载并安装，例如： [Oracle JDK](http://www.oracle.com/technetwork/java/javase/downloads/index.html) 或 [OpenJDK](https://openjdk.java.net/)。  |
|  Tomcat  |     [Tomcat](http://tomcat.apache.org/) 应用服务器版本 7 或更高版本。      > **Note:** > 本教程使用 JDK 21、Jakarta EE 11 和 Tomcat 11。 有关其他 Tomcat、Java 和 Jakarta EE 版本之间兼容性的更多信息，请参阅 [https://tomcat.apache.org/whichversion.html](https://tomcat.apache.org/whichversion.html)。    |
|  GlassFish  |     [GlassFish](https://projects.eclipse.org/projects/ee4j.glassfish) 应用服务器版本 4.0 或更高版本。 您可以从 [官方存储库](https://github.com/eclipse-ee4j/glassfish) 获取最新版本。 对于本教程而言，  Web Profile  子集已足够。      > **Note:** > 本教程使用 Oracle OpenJDK 17、Jakarta EE 9.1 和 GlassFish 6.2.5。 有关其他 GlassFish、Java 和 Jakarta EE 版本之间兼容性的更多信息，请参阅 [https://github.com/eclipse-ee4j/glassfish#compatibility](https://github.com/eclipse-ee4j/glassfish#compatibility)。    |
|  Web 浏览器  |  您将需要一个 Web 浏览器来查看您的 Web 应用程序。  |

Procedure: 创建一个包含 JAX-RS 的新 Jakarta EE 项目

IntelliJ IDEA 包含一个专用向导，用于基于各种 Jakarta EE 实现创建 Jakarta EE 项目。 在本教程中，我们将创建一个简单的 Web 应用程序。

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_step1_rest.png)

3. 按如下方式设置项目设置:

* 名称 ： `JakartaRESTHelloWorld`

* 位置 : 保持原样

* 创建 Git 仓库 : 保持原样

* 模板 : REST 服务

* 应用程序服务器 : <无应用程序服务器>

* 语言 : Java

* 构建系统 ：Maven

* 组 : 保持原样

* 工件 : 保持原样

* JDK : Eclipse Temurin 21

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

4. 从   版本   下拉列表中，选择   Jakarta EE 11  ，因为本教程使用的 Tomcat 11 与其兼容。   Jakarta EE 9.1  ，因为本教程使用的 GlassFish 6.2.5 与其兼容。

由于在上一步中选择了 REST 服务模板，   依赖项   列表中已选择一些规范。 对于本教程，无需选择任何其他依赖项。

![新建 Java 企业项目向导](https://resources.jetbrains.com.cn/help/img/idea/2026.3/jakarta_new_project_step_2_rest_jakarta_9_1.png)

5. 由于在上一步中选择了 REST 服务模板，   依赖项   列表中已选择一些规范。 不过，还需要选择它们的实现：   Eclipse Jersey 服务器   和   Weld SE  。

![已选择 Jakarta 11 的 Jakarta EE 项目向导第二步](https://resources.jetbrains.com.cn/help/img/idea/2026.3/jakarta_new_project_step_2_rest_jakarta_11.png)

6. 点击   创建  。

Procedure: 探索默认项目结构

IntelliJ IDEA 会创建一个包含一些样板代码的项目，您可以成功构建并部署。

> **Tip:**
> 使用   项目   工具窗口浏览并打开您项目中的文件，或按 `Ctrl+Shift+N` (Windows), `⌘ ⇧ O` (macOS), `⌘ ⇧ N` (IntelliJ IDEA Classic (macOS)), `⌘ ⇧ O` (macOS System Shortcuts), `Ctrl+Shift+N` (XWin), `Ctrl+Shift+N` (GNOME), `Ctrl+Shift+N` (KDE), `Ctrl+X, Ctrl+F` (Emacs), `Ctrl+P` (Sublime Text), `⌘ P` (Sublime Text (macOS)), `Ctrl+Shift+T` (Visual Studio), `⌘ ⇧ T` (Visual Studio (macOS)), `Alt+Shift+O` (NetBeans), `Ctrl+Shift+R` (Eclipse), `⌘ ⇧ R` (Eclipse (macOS))，然后输入文件名。

* `pom.xml`  是包含 Maven 配置信息的  项目对象模型 ，其中包括构建项目所需的依赖项和插件。

```XML

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>org.example</groupId>
  <artifactId>RestTomcatHelloWorld</artifactId>
  <version>1.0-SNAPSHOT</version>
  <name>RestTomcatHelloWorld</name>
  <packaging>war</packaging>

  <properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <maven.compiler.target>21</maven.compiler.target>
    <maven.compiler.source>21</maven.compiler.source>
    <junit.version>5.11.0-M2</junit.version>
  </properties>

  <dependencies>
<dependency>
      <groupId>jakarta.servlet</groupId>
      <artifactId>jakarta.servlet-api</artifactId>
      <version>6.1.0</version>
      <scope>provided</scope>
    </dependency><dependency>
      <groupId>org.glassfish.jersey.containers</groupId>
      <artifactId>jersey-container-servlet</artifactId>
      <version>4.0.0-M1</version>
    </dependency>
    <dependency>
      <groupId>org.glassfish.jersey.media</groupId>
      <artifactId>jersey-media-json-jackson</artifactId>
      <version>4.0.0-M1</version>
    </dependency>
<dependency>
      <groupId>org.glassfish.jersey.inject</groupId>
      <artifactId>jersey-cdi2-se</artifactId>
      <version>4.0.0-M1</version>
    </dependency><dependency>
      <groupId>org.jboss.weld.se</groupId>
      <artifactId>weld-se-core</artifactId>
      <version>6.0.0.Beta1</version>
    </dependency>
<dependency>
      <groupId>org.junit.jupiter</groupId>
      <artifactId>junit-jupiter-api</artifactId>
      <version>${junit.version}</version>
      <scope>test</scope>
    </dependency>
      <dependency>
        <groupId>org.junit.jupiter</groupId>
        <artifactId>junit-jupiter-engine</artifactId>
        <version>${junit.version}</version>
        <scope>test</scope>
      </dependency>  </dependencies>

  <build>
    <plugins>
        <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-war-plugin</artifactId>
        <version>3.4.0</version>
      </plugin>
    </plugins>
  </build>
</project>


```

```XML
                
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.example</groupId>
    <artifactId>RestTomcatHelloWorld</artifactId>
    <version>1.0-SNAPSHOT</version>
    <name>RestTomcatHelloWorld</name>
    <packaging>war</packaging>

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <maven.compiler.target>11</maven.compiler.target>
        <maven.compiler.source>11</maven.compiler.source>
        <junit.version>5.9.2</junit.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>jakarta.servlet</groupId>
            <artifactId>jakarta.servlet-api</artifactId>
            <version>5.0.0</version>
            <scope>provided</scope>
        </dependency>
        <dependency>
            <groupId>org.glassfish.jersey.containers</groupId>
            <artifactId>jersey-container-servlet</artifactId>
            <version>3.0.4</version>
        </dependency>
        <dependency>
            <groupId>org.glassfish.jersey.media</groupId>
            <artifactId>jersey-media-json-jackson</artifactId>
            <version>3.0.4</version>
        </dependency>
        <dependency>
            <groupId>org.glassfish.jersey.inject</groupId>
            <artifactId>jersey-cdi2-se</artifactId>
            <version>3.0.4</version>
        </dependency>
        <dependency>
            <groupId>org.jboss.weld.se</groupId>
            <artifactId>weld-se-core</artifactId>
            <version>4.0.3.Final</version>
        </dependency>
        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter-api</artifactId>
            <version>${junit.version}</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter-engine</artifactId>
            <version>${junit.version}</version>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-war-plugin</artifactId>
                <version>3.3.2</version>
            </plugin>
        </plugins>
    </build>
</project>
                
            
```

* `HelloResource.java`  是一个实现 RESTful 网络服务的  根资源类 ，它使用以下 JAX-RS 注解：

* `@Path` 注解识别用于访问此资源的 URI，相对于应用程序根目录。

* `@GET` 注解表明 `hello()` 方法将处理发送到指定 URI 的 HTTP GET 请求。

* `@Produces` 注解指定了方法生成和返回的 MIME 媒体类型。

```JAVA
package com.example.restglassfishhelloworld;

import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;

@Path("/hello-world")
public class HelloResource {
    @GET
    @Produces("text/plain")
    public String hello() {
        return "Hello, World!";
    }
}

```

```JAVA
package com.example.resttomcathelloworld;

import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;

@Path("/hello-world")
public class HelloResource {
    @GET
    @Produces("text/plain")
    public String hello() {
        return "Hello, World!";
    }
}

```

* `HelloApplication.java`  是  `javax.ws.rs.core.Application`  的子类，用于配置应用程序运行资源类中定义的 REST 资源的环境。  `@ApplicationPath`  注释标识了应用根的 URL 映射（默认情况下，它被设置为  `/api` ）。

```JAVA
package com.example.restglassfishhelloworld;

import jakarta.ws.rs.ApplicationPath;
import jakarta.ws.rs.core.Application;

@ApplicationPath("/api")
public class HelloApplication extends Application {

}

```

```JAVA
package com.example.resttomcathelloworld;

import jakarta.ws.rs.ApplicationPath;
import jakarta.ws.rs.core.Application;

@ApplicationPath("/api")
public class HelloApplication extends Application {

}

```

Procedure: 配置应用服务器

让 IntelliJ IDEA 知道  GlassFish   Tomcat  应用服务器的位置。

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. 点击 !["添加"按钮](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app.expui.general.add.svg) 并选择   GlassFish 服务器     Tomcat  。

3. 指定  GlassFish   Tomcat  服务器安装位置的路径。 IntelliJ IDEA 会适当地检测并设置名称和版本。

![GlassFish 应用服务器配置](https://resources.jetbrains.com.cn/help/img/idea/2026.3/rest_ws_glassfish_configure.png)

![Tomcat 应用服务器配置](https://resources.jetbrains.com.cn/help/img/idea/2026.3/rest_ws_tomcat_11_configure.png)

Procedure: 创建运行配置

IntelliJ IDEA 需要一个运行配置来构建工件并将其部署到您的应用服务器。

1. 在主菜单中，转到  `运行 | 编辑配置` 。

2. 在   运行/调试配置  对话框中，点击 !["添加"按钮](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app.expui.general.add.svg)，展开   GlassFish 服务器     Tomcat 服务器  节点，并选择   本地  。

3. 修复出现在运行配置设置对话框底部的任何警告。

![运行配置警告](https://resources.jetbrains.com.cn/help/img/idea/2026.3/rest_ws_glassfish_run_config_warning.png)

很可能，您需要修复以下问题：

* 在 服务器 选项卡上，将 服务器域名 设置为 `domain1` 。

* 在 部署 选项卡上，添加您想要部署的工件： `RestGlassfishHelloWorld:war exploded` `RestTomcatHelloWorld:war exploded`

4. 在   服务器  选项卡上，将 URL 设置为指向 [根资源](#source_code)：

```
http://localhost:8080/RestGlassfishHelloWorld-1.0-SNAPSHOT/api/hello-world

```

```
http://localhost:8080/RestTomcatHelloWorld_war_exploded/api/hello-world

```

![GlassFish 运行配置已完成](https://resources.jetbrains.com.cn/help/img/idea/2026.3/rest_ws_glassfish_run_config_url.png)

![Tomcat 运行配置已完成](https://resources.jetbrains.com.cn/help/img/idea/2026.3/rest_ws_tomcat_11_run_config_url.png)

5. 点击   OK   以保存运行配置。

6. 要运行配置，请按 `Alt+Shift+F10` (Windows), `⌃ ⌥ R` (macOS), `⌥ ⇧ F10` (IntelliJ IDEA Classic (macOS)), `⌃ ⌥ R` (macOS System Shortcuts), `Alt+Shift+F10` (XWin), `Alt+Shift+F10` (GNOME), `Alt+Shift+F10` (KDE), `Alt+Shift+F10` (Emacs), `Alt+Shift+F10` (Sublime Text), `⌃ ⌥ R` (Sublime Text (macOS)), `Ctrl+Alt+Shift+R` (Visual Studio), `⌘ ⌥ ⇧ R` (Visual Studio (macOS)), `Alt+Shift+F10` (NetBeans), `Alt+Shift+F10` (Eclipse), `⌃ ⌥ R` (Eclipse (macOS)) 并选择创建的应用服务器配置。

或者，如果您已在顶部的主工具栏中选择了运行配置，您可以在主工具栏中点击 ![运行图标](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app.expui.run.run.svg)，或按 `Shift+F10` (Windows), `⌃ R` (macOS), `⇧ F10` (IntelliJ IDEA Classic (macOS)), `⌥ ⇧ R` (macOS System Shortcuts), `Shift+F10` (XWin), `Shift+F10` (GNOME), `Shift+F10` (KDE), `Shift+F10` (Emacs), `Shift+F10` (Sublime Text), `Shift+F10` (Sublime Text (macOS)), `Ctrl+F5` (Visual Studio), `⌃ F5` (Visual Studio (macOS)), `F6` (NetBeans), `Alt+Shift+X` (Eclipse), `⌘ ⇧ F11` (Eclipse (macOS)) 来运行它。

此运行配置会构建构件，然后启动  GlassFish   Tomcat 服务器，并将构件部署到服务器。 您应该会在   服务   工具窗口中看到相应的输出。

![在 服務 工具窗口中启动 Tomcat 服务器并部署应用程序](https://resources.jetbrains.com.cn/help/img/idea/2026.3/rest_ws_tomcat_run_tool_window.png)

![已在"服务"工具窗口中启动 GlassFish 服务器并部署应用程序](https://resources.jetbrains.com.cn/help/img/idea/2026.3/rest_ws_glassfish_run_tool_window.png)

完成后，IntelliJ IDEA 会在您的 Web 浏览器中打开指定的 URL。

![在 Web 浏览器中显示的已部署应用程序输出](https://resources.jetbrains.com.cn/help/img/idea/2026.3/rest_all_web_browser_output.png)

如果没有，请尝试自行打开 URL： [http://localhost:8080/RestGlassfishHelloWorld-1.0-SNAPSHOT/api/hello-world](http://localhost:8080/RestGlassfishHelloWorld-1.0-SNAPSHOT/api/hello-world) [http://localhost:8080/RestTomcatHelloWorld_war_exploded/api/hello-world](http://localhost:8080/RestTomcatHelloWorld_war_exploded/api/hello-world)

## 故障排除

### 与 Jakarta EE 的兼容性

如果您得到一个  `404`  错误，请确保在 [创建项目](#create-new-project) 时，选择了与您的 GlassFish 版本兼容的 Jakarta EE 规范版本。

有关详细信息，请参阅 [GlassFish 版本兼容性](https://github.com/eclipse-ee4j/glassfish#compatibility)。

### 较早的 IntelliJ IDEA 版本

如果您使用的是 IntelliJ IDEA 版本 2020.2.2 或更早版本，   新建项目   向导将不会添加 Tomcat 所需的所有必要依赖项。 在这种情况下，打开  `pom.xml` 并添加以下依赖项：

```XML

<dependency>
    <groupId>org.glassfish.jersey.media</groupId>
    <artifactId>jersey-media-json-jackson</artifactId>
    <version>2.31</version>
</dependency>
<dependency>
    <groupId>org.glassfish.jersey.inject</groupId>
    <artifactId>jersey-hk2</artifactId>
    <version>2.31</version>
</dependency>


```

例如，在 2020.2.3 版本中，生成的  `pom.xml`  如下所示：

```XML
               
               <?xml version="1.0" encoding="UTF-8"?>
               <project xmlns="http://maven.apache.org/POM/4.0.0"
                        
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                        xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
                   <modelVersion>4.0.0</modelVersion>

                   <groupId>com.example</groupId>
                   <artifactId>RestTomcatHelloWorld</artifactId>
                   <version>1.0-SNAPSHOT</version>
                   <name>RestTomcatHelloWorld</name>
                   <packaging>war</packaging>

                   <properties>
                       <maven.compiler.target>1.8</maven.compiler.target>
                       <maven.compiler.source>1.8</maven.compiler.source>
                       <junit.version>5.6.2</junit.version>
                   </properties>

                   <dependencies>
                       <dependency>
                           <groupId>javax.ws.rs</groupId>
                           <artifactId>javax.ws.rs-api</artifactId>
                           <version>2.1.1</version>
                           <scope>provided</scope>
                       </dependency>
                       <dependency>
                           <groupId>org.glassfish.jersey.containers</groupId>
                           <artifactId>jersey-container-servlet</artifactId>
                           <version>2.31</version>
                       </dependency>
                       <dependency>
                           <groupId>org.glassfish.jersey.media</groupId>
                           <artifactId>jersey-media-json-jackson</artifactId>
                           <version>2.31</version>
                       </dependency>
                       <dependency>
                           <groupId>org.glassfish.jersey.inject</groupId>
                           <artifactId>jersey-hk2</artifactId>
                           <version>2.31</version>
                       </dependency>
                       <dependency>
                           <groupId>org.glassfish.jersey.core</groupId>
                           <artifactId>jersey-client</artifactId>
                           <version>2.31</version>
                       </dependency>
                       <dependency>
                           <groupId>org.junit.jupiter</groupId>
                           <artifactId>junit-jupiter-api</artifactId>
                           <version>${junit.version}</version>
                           <scope>test</scope>
                       </dependency>
                       <dependency>
                           <groupId>org.junit.jupiter</groupId>
                           <artifactId>junit-jupiter-engine</artifactId>
                           <version>${junit.version}</version>
                           <scope>test</scope>
                       </dependency>
                   </dependencies>

                   <build>
                       <plugins>
                           <plugin>
                               <groupId>org.apache.maven.plugins</groupId>
                               <artifactId>maven-war-plugin</artifactId>
                               <version>3.3.0</version>
                           </plugin>
                       </plugins>
                   </build>
               </project>
               
           
```