Java Jetty 实战详解：从嵌入式 HTTP 服务到 Spring Boot 容器替换

简介

Jetty 是 Eclipse 基金会维护的 Java Web 服务器，也是一个 Servlet 容器。

它主要能做这些事：

1监听 HTTP 端口
2处理 HTTP 请求和响应
3运行 Servlet / Filter / Listener
4部署 WAR 包
5支持 WebSocket、HTTP/2、HTTP/3
6作为库嵌入到 Java 程序里启动
7作为 Spring Boot 的内嵌容器
8

一句话概括：

1Jetty 既能像 Tomcat 一样单独部署 Web 应用，也能像普通 Java 库一样嵌入到 main 方法里启动。
2

Jetty 最突出的特点是“嵌入式”和“可编程”。

很多中间件、网关、测试工具、微服务框架喜欢用 Jetty，原因很直接：启动快、模块化、代码里就能组装 HTTP 服务，不一定要准备一个完整应用服务器。

Jetty 适合什么场景

常见场景如下：

简单理解：

1Tomcat 更常见于传统 Java Web 容器
2Jetty 更常见于嵌入式服务、工具服务和高度可编程的 Web 底座
3

这不是说 Tomcat 不能嵌入，也不是说 Jetty 不能部署 WAR。

只是两个项目的气质不太一样。

Jetty 和 Tomcat 的区别

Jetty 里很重要的概念是 Handler。

可以把它理解成：

1请求进来后，Jetty 先交给 Handler 树处理。
2

如果使用 Servlet，Servlet 也是挂在 Jetty 的 Handler 体系下面。

版本怎么选

Jetty 版本和 Java、Servlet / Jakarta EE 规范强相关。

新项目常见选择：

1Java 17+
2Jetty 12.0.x 稳定线
3Jakarta EE 10
4jakarta.servlet.*
5

老项目如果还在使用：

1import javax.servlet.http.HttpServlet;
2

不能直接照搬 Jetty 12 的 EE10 示例。

需要选择对应的 EE8 模块，或者先把代码迁移到：

1import jakarta.servlet.http.HttpServlet;
2

Jetty 的两种使用方式

Jetty 常见用法可以分成两类。

独立运行

先下载 Jetty，再部署应用。

大致像这样：

1jetty-home
2jetty-base
3webapps
4start.jar
5

然后把 WAR 包放进去，由 Jetty 启动和管理。

这种方式适合：

• 传统 WAR 项目
• 多个 Web 应用统一部署
• 运维希望容器和应用分开管理

嵌入式运行

把 Jetty 当成 Maven 依赖引进来，在 main 方法里启动。

大致像这样：

1public static void main(String[] args) {
2    Server server = new Server(8080);
3    server.setHandler(...);
4    server.start();
5}
6

这种方式适合：

• 微服务
• 工具程序
• 单个 Jar 包部署
• 测试服务
• 内部管理端口

Spring Boot 内嵌 Jetty 本质上也是嵌入式模式。

核心架构

Jetty 处理请求的大致流程：

1Client
2  |
3  v
4Connector
5  |
6  v
7Server
8  |
9  v
10Handler
11  |
12  v
13Servlet / Filter / WebSocket / 自定义处理逻辑
14

几个核心对象：

最小结构：

1Server
2  |
3  v
4ServerConnector :8080
5  |
6  v
7Handler
8

Servlet 结构：

1Server
2  |
3  v
4ServletContextHandler /api
5  |
6  ├── UserServlet /users/*
7  └── LogFilter /*
8

Maven 依赖

下面示例基于 Jetty 12.0.x 和 Jakarta EE 10。

版本号可以统一放到 properties：

1<properties>
2    <maven.compiler.source>17</maven.compiler.source>
3    <maven.compiler.target>17</maven.compiler.target>
4    <jetty.version>12.0.37</jetty.version>
5    <jackson.version>2.17.2</jackson.version>
6</properties>
7

最小 Handler 服务只需要 jetty-server：

1<dependency>
2    <groupId>org.eclipse.jetty</groupId>
3    <artifactId>jetty-server</artifactId>
4    <version>${jetty.version}</version>
5</dependency>
6

如果要写 Servlet，需要引入 EE10 Servlet 模块：

1<dependency>
2    <groupId>org.eclipse.jetty.ee10</groupId>
3    <artifactId>jetty-ee10-servlet</artifactId>
4    <version>${jetty.version}</version>
5</dependency>
6

如果要部署 WAR，需要引入 WebApp 模块：

1<dependency>
2    <groupId>org.eclipse.jetty.ee10</groupId>
3    <artifactId>jetty-ee10-webapp</artifactId>
4    <version>${jetty.version}</version>
5</dependency>
6

Demo 里为了输出 JSON，再加 Jackson：

1<dependency>
2    <groupId>com.fasterxml.jackson.core</groupId>
3    <artifactId>jackson-databind</artifactId>
4    <version>${jackson.version}</version>
5</dependency>
6

完整依赖：

1<dependencies>
2    <dependency>
3        <groupId>org.eclipse.jetty</groupId>
4        <artifactId>jetty-server</artifactId>
5        <version>${jetty.version}</version>
6    </dependency>
7
8    <dependency>
9        <groupId>org.eclipse.jetty.ee10</groupId>
10        <artifactId>jetty-ee10-servlet</artifactId>
11        <version>${jetty.version}</version>
12    </dependency>
13
14    <dependency>
15        <groupId>org.eclipse.jetty.ee10</groupId>
16        <artifactId>jetty-ee10-webapp</artifactId>
17        <version>${jetty.version}</version>
18    </dependency>
19
20    <dependency>
21        <groupId>com.fasterxml.jackson.core</groupId>
22        <artifactId>jackson-databind</artifactId>
23        <version>${jackson.version}</version>
24    </dependency>
25</dependencies>
26

第一个 Demo：不用 Servlet 的 HTTP 服务

Jetty 12 推荐直接使用 Handler.Abstract 写底层 HTTP 处理逻辑。

这个 Demo 只做一件事：

1访问 http://localhost:8080/hello
2返回一段 JSON
3

启动类：

1package com.example.jettydemo;
2
3import org.eclipse.jetty.http.HttpHeader;
4import org.eclipse.jetty.io.Content;
5import org.eclipse.jetty.server.Request;
6import org.eclipse.jetty.server.Response;
7import org.eclipse.jetty.server.Server;
8import org.eclipse.jetty.server.ServerConnector;
9import org.eclipse.jetty.server.Handler;
10import org.eclipse.jetty.util.Callback;
11
12public class HelloHandlerServer {
13
14    public static void main(String[] args) throws Exception {
15        Server server = new Server();
16
17        ServerConnector connector = new ServerConnector(server);
18        connector.setHost("0.0.0.0");
19        connector.setPort(8080);
20        connector.setIdleTimeout(30_000);
21        server.addConnector(connector);
22
23        server.setHandler(new Handler.Abstract() {
24            @Override
25            public boolean handle(Request request, Response response, Callback callback) {
26                String path = request.getHttpURI().getPath();
27
28                if (!"/hello".equals(path)) {
29                    response.setStatus(404);
30                    response.getHeaders().put(HttpHeader.CONTENT_TYPE, "application/json;charset=UTF-8");
31                    Content.Sink.write(response, true, "{\"message\":\"not found\"}", callback);
32                    return true;
33                }
34
35                response.setStatus(200);
36                response.getHeaders().put(HttpHeader.CONTENT_TYPE, "application/json;charset=UTF-8");
37                Content.Sink.write(response, true, "{\"message\":\"Hello Jetty\"}", callback);
38                return true;
39            }
40        });
41
42        server.start();
43        System.out.println("Jetty started: http://localhost:8080/hello");
44        server.join();
45    }
46}
47

测试：

1curl http://localhost:8080/hello
2

返回：

1{"message":"Hello Jetty"}
2

访问不存在的路径：

1curl http://localhost:8080/abc
2

返回：

1{"message":"not found"}
2

这个例子没有 Servlet，没有 Spring MVC，也没有注解路由。

请求是直接交给 Handler 处理的。

这种方式适合做非常轻量的接口，比如：

• 健康检查
• 本地管理端口
• 内部指标接口
• 简单代理服务
• 不想引入 Web 框架的小工具

Handler 为什么要返回 boolean

handle 方法返回 true 表示请求已经被当前 Handler 处理。

1return true;
2

如果是 Handler 组合结构，返回值会影响后续 Handler 是否继续处理。

同时，响应写完后需要通知 callback。

1Content.Sink.write(response, true, body, callback);
2

这行代码里，Content.Sink.write 会在写入完成后处理 callback。

如果手动处理异步写入，需要确保最后调用：

1callback.succeeded();
2

或异常时调用：

1callback.failed(error);
2

否则请求可能一直挂着。

第二个 Demo：Servlet 版 REST 接口

很多 Java Web 项目还是 Servlet 模型。

Jetty 可以不用 WAR 包，直接用 ServletContextHandler 在代码里注册 Servlet。

这个 Demo 实现三个接口：

返回对象

1package com.example.jettydemo.dto;
2
3public record ApiResult<T>(int code, String message, T data) {
4
5    public static <T> ApiResult<T> ok(T data) {
6        return new ApiResult<>(200, "success", data);
7    }
8
9    public static <T> ApiResult<T> fail(int code, String message) {
10        return new ApiResult<>(code, message, null);
11    }
12}
13

Servlet

1package com.example.jettydemo.servlet;
2
3import com.example.jettydemo.dto.ApiResult;
4import com.fasterxml.jackson.databind.ObjectMapper;
5import jakarta.servlet.ServletException;
6import jakarta.servlet.http.HttpServlet;
7import jakarta.servlet.http.HttpServletRequest;
8import jakarta.servlet.http.HttpServletResponse;
9
10import java.io.IOException;
11import java.util.List;
12import java.util.Map;
13
14public class UserServlet extends HttpServlet {
15
16    private final ObjectMapper objectMapper = new ObjectMapper();
17
18    @Override
19    protected void doGet(HttpServletRequest request, HttpServletResponse response)
20            throws ServletException, IOException {
21        response.setContentType("application/json;charset=UTF-8");
22
23        String id = request.getParameter("id");
24        if (id == null || id.isBlank()) {
25            ApiResult<List<Map<String, Object>>> result = ApiResult.ok(List.of(
26                    Map.of("id", 1, "name", "张三"),
27                    Map.of("id", 2, "name", "李四")
28            ));
29            objectMapper.writeValue(response.getWriter(), result);
30            return;
31        }
32
33        ApiResult<Map<String, Object>> result = ApiResult.ok(
34                Map.of("id", Long.parseLong(id), "name", "用户" + id)
35        );
36        objectMapper.writeValue(response.getWriter(), result);
37    }
38
39    @Override
40    protected void doPost(HttpServletRequest request, HttpServletResponse response)
41            throws ServletException, IOException {
42        response.setContentType("application/json;charset=UTF-8");
43
44        String name = request.getParameter("name");
45        if (name == null || name.isBlank()) {
46            response.setStatus(HttpServletResponse.SC_BAD_REQUEST);
47            objectMapper.writeValue(response.getWriter(), ApiResult.fail(400, "name 不能为空"));
48            return;
49        }
50
51        ApiResult<Map<String, Object>> result = ApiResult.ok(
52                Map.of("id", System.currentTimeMillis(), "name", name)
53        );
54        objectMapper.writeValue(response.getWriter(), result);
55    }
56}
57

启动类

1package com.example.jettydemo;
2
3import com.example.jettydemo.servlet.UserServlet;
4import org.eclipse.jetty.ee10.servlet.ServletContextHandler;
5import org.eclipse.jetty.server.Server;
6import org.eclipse.jetty.server.ServerConnector;
7
8public class ServletApiServer {
9
10    public static void main(String[] args) throws Exception {
11        Server server = new Server();
12
13        ServerConnector connector = new ServerConnector(server);
14        connector.setPort(8080);
15        connector.setIdleTimeout(30_000);
16        server.addConnector(connector);
17
18        ServletContextHandler context = new ServletContextHandler();
19        context.setContextPath("/api");
20        context.addServlet(UserServlet.class, "/users");
21
22        server.setHandler(context);
23        server.start();
24
25        System.out.println("Jetty Servlet API started: http://localhost:8080/api/users");
26        server.join();
27    }
28}
29

测试：

1curl http://localhost:8080/api/users
2

返回：

1{
2  "code": 200,
3  "message": "success",
4  "data": [
5    {
6      "id": 1,
7      "name": "张三"
8    },
9    {
10      "id": 2,
11      "name": "李四"
12    }
13  ]
14}
15

查询单个用户：

1curl 'http://localhost:8080/api/users?id=100'
2

新增用户：

1curl -X POST 'http://localhost:8080/api/users?name=王五'
2

加一个 Filter：接口耗时日志

Servlet 项目常见需求是记录请求日志。

可以写一个 Filter：

1package com.example.jettydemo.servlet;
2
3import jakarta.servlet.Filter;
4import jakarta.servlet.FilterChain;
5import jakarta.servlet.ServletException;
6import jakarta.servlet.ServletRequest;
7import jakarta.servlet.ServletResponse;
8import jakarta.servlet.http.HttpServletRequest;
9
10import java.io.IOException;
11
12public class AccessLogFilter implements Filter {
13
14    @Override
15    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
16            throws IOException, ServletException {
17        long start = System.currentTimeMillis();
18
19        try {
20            chain.doFilter(request, response);
21        } finally {
22            HttpServletRequest httpRequest = (HttpServletRequest) request;
23            long cost = System.currentTimeMillis() - start;
24            System.out.println(httpRequest.getMethod() + " " + httpRequest.getRequestURI() + " " + cost + "ms");
25        }
26    }
27}
28

注册 Filter：

1package com.example.jettydemo;
2
3import com.example.jettydemo.servlet.AccessLogFilter;
4import com.example.jettydemo.servlet.UserServlet;
5import jakarta.servlet.DispatcherType;
6import org.eclipse.jetty.ee10.servlet.FilterHolder;
7import org.eclipse.jetty.ee10.servlet.ServletContextHandler;
8import org.eclipse.jetty.server.Server;
9import org.eclipse.jetty.server.ServerConnector;
10
11import java.util.EnumSet;
12
13public class ServletApiServer {
14
15    public static void main(String[] args) throws Exception {
16        Server server = new Server();
17
18        ServerConnector connector = new ServerConnector(server);
19        connector.setPort(8080);
20        server.addConnector(connector);
21
22        ServletContextHandler context = new ServletContextHandler();
23        context.setContextPath("/api");
24        context.addServlet(UserServlet.class, "/users");
25        context.addFilter(new FilterHolder(new AccessLogFilter()), "/*", EnumSet.of(DispatcherType.REQUEST));
26
27        server.setHandler(context);
28        server.start();
29        server.join();
30    }
31}
32

访问接口后，控制台会打印：

1GET /api/users 12ms
2

这一套写法和 web.xml 里配置 Servlet / Filter 的效果类似，只是改成了 Java 代码注册。

第三个 Demo：用 WebAppContext 部署 WAR

如果项目已经是标准 WAR 包，可以用 WebAppContext。

目录假设如下：

1/opt/apps/user-center.war
2

启动类：

1package com.example.jettydemo;
2
3import org.eclipse.jetty.ee10.webapp.WebAppContext;
4import org.eclipse.jetty.server.Server;
5import org.eclipse.jetty.server.ServerConnector;
6
7public class WarServer {
8
9    public static void main(String[] args) throws Exception {
10        Server server = new Server();
11
12        ServerConnector connector = new ServerConnector(server);
13        connector.setPort(8080);
14        server.addConnector(connector);
15
16        WebAppContext webAppContext = new WebAppContext();
17        webAppContext.setContextPath("/user-center");
18        webAppContext.setWar("/opt/apps/user-center.war");
19
20        server.setHandler(webAppContext);
21        server.start();
22
23        System.out.println("WAR started: http://localhost:8080/user-center");
24        server.join();
25    }
26}
27

访问：

1http://localhost:8080/user-center
2

ServletContextHandler 和 WebAppContext 的区别：

独立 Jetty 部署 WAR

Jetty 也可以像传统应用服务器一样独立运行。

常见目录概念：

1JETTY_HOME：Jetty 安装目录
2JETTY_BASE：业务配置和应用目录
3

JETTY_HOME 放 Jetty 自身文件。

JETTY_BASE 放项目配置、模块启用文件、webapps、日志等。

这种设计方便升级 Jetty：

1升级时替换 JETTY_HOME
2业务配置继续留在 JETTY_BASE
3

创建 base 目录：

1mkdir jetty-base
2cd jetty-base
3

启用 HTTP 和 EE10 部署模块：

1java -jar $JETTY_HOME/start.jar --add-modules=http,ee10-deploy
2

这会创建类似目录：

1jetty-base/
2├── resources/
3├── start.d/
4│   ├── http.ini
5│   └── ee10-deploy.ini
6└── webapps/
7

复制 WAR：

1cp /opt/apps/user-center.war webapps/
2

启动：

1java -jar $JETTY_HOME/start.jar
2

访问：

1http://localhost:8080/user-center
2

WAR 文件名通常会影响访问路径。

比如：

1webapps/user-center.war -> /user-center
2webapps/root.war        -> /
3

如果需要自定义 context path，可以使用 Jetty context XML。

示例 webapps/user-center.xml：

1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://jetty.org/configure_10_0.dtd">
3<Configure class="org.eclipse.jetty.ee10.webapp.WebAppContext">
4    <Set name="contextPath">/uc</Set>
5    <Set name="war">/opt/apps/user-center.war</Set>
6</Configure>
7

这样访问路径就是：

1http://localhost:8080/uc
2

Jetty Maven 插件

开发传统 Web 项目时，可以用 Jetty Maven 插件快速启动。

Jetty 12 以后，Maven 插件也按 EE 版本拆包。

Jakarta EE 10 项目使用：

1<build>
2    <plugins>
3        <plugin>
4            <groupId>org.eclipse.jetty.ee10</groupId>
5            <artifactId>jetty-ee10-maven-plugin</artifactId>
6            <version>12.0.37</version>
7            <configuration>
8                <scan>2</scan>
9                <webApp>
10                    <contextPath>/</contextPath>
11                </webApp>
12            </configuration>
13        </plugin>
14    </plugins>
15</build>
16

启动：

1mvn jetty:run
2

常见目标：

scan 表示扫描变更的间隔秒数。

1<scan>2</scan>
2

表示每 2 秒检查一次变更，发现变化后重新部署。

Jetty Maven 插件适合开发和测试，不适合生产部署。

生产环境更适合：

• 独立 Jetty
• 嵌入式 Jetty
• Spring Boot 可执行 Jar
• 容器镜像

Spring Boot 替换 Tomcat 为 Jetty

Spring Boot Web 默认使用 Tomcat。

替换成 Jetty，只需要排除 Tomcat，再引入 Jetty starter。

1<dependency>
2    <groupId>org.springframework.boot</groupId>
3    <artifactId>spring-boot-starter-web</artifactId>
4    <exclusions>
5        <exclusion>
6            <groupId>org.springframework.boot</groupId>
7            <artifactId>spring-boot-starter-tomcat</artifactId>
8        </exclusion>
9    </exclusions>
10</dependency>
11
12<dependency>
13    <groupId>org.springframework.boot</groupId>
14    <artifactId>spring-boot-starter-jetty</artifactId>
15</dependency>
16

Controller 不需要改：

1package com.example.bootjetty.controller;
2
3import org.springframework.web.bind.annotation.GetMapping;
4import org.springframework.web.bind.annotation.RequestMapping;
5import org.springframework.web.bind.annotation.RestController;
6
7import java.util.Map;
8
9@RestController
10@RequestMapping("/api")
11public class HealthController {
12
13    @GetMapping("/health")
14    public Map<String, Object> health() {
15        return Map.of(
16                "status", "UP",
17                "container", "Jetty"
18        );
19    }
20}
21

启动后，控制台里会看到 Jetty 相关日志。

访问：

1curl http://localhost:8080/api/health
2

返回：

1{
2  "status": "UP",
3  "container": "Jetty"
4}
5