当前位置：首页 > 文章列表 > 文章 > java教程 > Jetty404问题解决与Handler配置教程

Jetty404问题解决与Handler配置教程

2025-11-27 15:54:35 0浏览收藏

文章小白一枚，正在不断学习积累知识，现将学习到的知识记录一下，也是将我的所得分享给大家！而今天这篇文章《Jetty 404问题解析与Handler配置教程》带大家来了解一下##content_title##，希望对大家的知识积累有所帮助，从而弥补自己的不足，助力实战开发！

解决Jetty 404：理解与正确配置服务器Handler

本教程深入探讨Jetty服务器启动时常见的404错误，特别是由于未正确将`ServletContextHandler`关联到`Server`实例导致的问题。文章将详细解释Jetty的Handler机制，并通过具体代码示例演示如何正确配置和挂载Handler，确保Web应用程序能够被Jetty服务器正确识别和处理，从而避免资源未找到的错误。

Jetty服务器与Handler机制概述

Jetty是一个轻量级、高性能的开源Java Web服务器和Servlet容器，常用于嵌入式应用或作为独立的服务器运行。在Jetty中，Handler是处理HTTP请求的核心组件。当Jetty服务器接收到一个请求时，它会通过一个或多个Handler来处理这个请求，例如解析请求、路由到正确的Servlet、提供静态资源等。

ServletContextHandler是Jetty中最常用的Handler之一，它负责管理一个Web应用程序的上下文。一个ServletContextHandler可以配置一个上下文路径（context path），并在此路径下注册Servlet、过滤器、监听器等Web组件。它是将Java Web应用部署到Jetty服务器的关键。

剖析Jetty 404错误：Handler未挂载的根源

在使用Jetty嵌入式服务器时，一个常见的错误是服务器启动后，无论访问哪个路径都返回404 Not Found错误，即使代码中已经明确配置了ServletContextHandler和ServletHolder。

考虑以下初始配置代码：

import org.eclipse.jetty.server.Server;
import org.eclipse.jetty.servlet.ServletContextHandler;
import org.eclipse.jetty.servlet.ServletHolder;
import org.glassfish.jersey.server.ResourceConfig;
import org.glassfish.jersey.servlet.ServletContainer;

public class JettyApp {
    public static void main(String[] args) throws Exception {
        // 1. 初始化Jetty服务器，监听8080端口
        Server server = new Server(8080);

        // 2. 创建ServletContextHandler，并设置上下文路径为 "/example"
        ServletContextHandler handler = new ServletContextHandler(ServletContextHandler.SESSIONS);
        handler.setContextPath("/example"); // 注意这里设置的是handler的contextPath

        // 3. 配置Jersey ResourceConfig，扫描API包并注册CORS配置
        ResourceConfig config = new ResourceConfig();
        config.packages("api"); // 假设你的API类在"api"包下
        // config.register(new CORSConfig()); // 注册CORS过滤器等

        // 4. 创建ServletHolder，将Jersey应用包装成Servlet
        ServletHolder holder = new ServletHolder(new ServletContainer(config));
        // 将此Servlet映射到 "/api/*" 路径
        handler.addServlet(holder, "/api/*");

        // 5. 启动和停止服务器的逻辑
        try {
            server.start(); // 服务器启动
            server.join();  // 阻塞主线程，直到服务器停止
        } finally {
            server.stop();
            server.destroy();
        }
    }
}

上述代码看似完整地配置了Jetty服务器、ServletContextHandler和ServletHolder，但运行时访问 http://localhost:8080/example/api/your_resource 或 http://localhost:8080/api/your_resource 仍然会得到404错误。

问题根源在于： 尽管创建了ServletContextHandler实例 handler，但这个 handler 对象并没有被告知给 Server 实例。Server 对象并不知道它应该使用哪个Handler来处理传入的请求。它就像你创建了一个处理请求的机器，但没有把它连接到主电源上，所以它无法工作。

解决方案：正确挂载Handler到Server

解决此问题的关键一步是在服务器启动之前，明确地将ServletContextHandler实例挂载到Server实例上。这通过调用 server.setHandler(handler); 方法实现。

修正后的代码如下：

import org.eclipse.jetty.server.Server;
import org.eclipse.jetty.servlet.ServletContextHandler;
import org.eclipse.jetty.servlet.ServletHolder;
import org.glassfish.jersey.server.ResourceConfig;
import org.glassfish.jersey.servlet.ServletContainer;

public class JettyApp {
    public static void main(String[] args) throws Exception {
        Server server = new Server(8080);

        ServletContextHandler handler = new ServletContextHandler(ServletContextHandler.SESSIONS);
        handler.setContextPath("/example"); // 设置Web应用的上下文路径

        ResourceConfig config = new ResourceConfig();
        config.packages("api");
        // config.register(new CORSConfig());

        ServletHolder holder = new ServletHolder(new ServletContainer(config));
        handler.addServlet(holder, "/api/*"); // Servlet在上下文路径下的映射

        // *** 关键的修正：将ServletContextHandler挂载到Server上 ***
        server.setHandler(handler);

        try {
            server.start();
            server.join();
        } finally {
            server.stop();
            server.destroy();
        }
    }
}

通过添加 server.setHandler(handler); 这一行代码，Server实例现在知道了它应该使用handler来处理所有传入的HTTP请求。当请求到达时，Server会将请求传递给这个handler，handler再根据其内部配置（如上下文路径和Servlet映射）来路由和处理请求。

深入理解路径匹配：Context Path与Servlet Path

理解ServletContextHandler的contextPath和ServletHolder的pathSpec之间的协同作用对于正确配置Jetty至关重要：

ServletContextHandler的contextPath (/example): 这是Web应用程序在服务器上的根路径。所有属于这个Web应用程序的请求都必须以此路径开头。例如，如果contextPath是/example，那么请求必须是 http://localhost:8080/example/...。
*ServletHolder的pathSpec (`/api/)**: 这是在特定ServletContextHandler内部，Servlet所响应的路径模式。它是一个相对于contextPath的路径。例如，如果contextPath是/example，而pathSpec是/api/*，那么Jersey Servlet将处理所有形如http://localhost:8080/example/api/...` 的请求。

因此，如果你的API路径是 /api/users，那么完整的访问URL应该是 http://localhost:8080/example/api/users。

完整Jetty嵌入式服务器配置示例

为了提供一个更全面的视角，以下是一个稍微扩展的Jetty嵌入式服务器配置示例，它包含了常见的组件和最佳实践：

import org.eclipse.jetty.server.Server;
import org.eclipse.jetty.server.ServerConnector;
import org.eclipse.jetty.servlet.ServletContextHandler;
import org.eclipse.jetty.servlet.ServletHolder;
import org.glassfish.jersey.server.ResourceConfig;
import org.glassfish.jersey.servlet.ServletContainer;

// 假设你有这样的一个API资源类
// package api;
// import javax.ws.rs.GET;
// import javax.ws.rs.Path;
// import javax.ws.rs.Produces;
// import javax.ws.rs.core.MediaType;
// @Path("/hello")
// public class MyResource {
//     @GET
//     @Produces(MediaType.TEXT_PLAIN)
//     public String getHello() {
//         return "Hello from Jetty Jersey!";
//     }
// }

public class FullJettyServerExample {

    public static void main(String[] args) throws Exception {
        // 1. 创建Jetty Server实例
        Server server = new Server();

        // 2. 配置HTTP连接器，监听8080端口
        ServerConnector http = new ServerConnector(server);
        http.setPort(8080);
        server.addConnector(http);

        // 3. 创建ServletContextHandler，用于托管Web应用
        // SESSIONS 参数表示启用会话管理
        ServletContextHandler servletContextHandler = new ServletContextHandler(ServletContextHandler.SESSIONS);
        servletContextHandler.setContextPath("/app"); // 设置Web应用的上下文路径

        // 4. 配置Jersey ResourceConfig
        // 扫描 "api" 包下的JAX-RS资源类
        ResourceConfig jerseyConfig = new ResourceConfig();
        jerseyConfig.packages("api"); // 确保你的API类（如MyResource）在"api"包下
        // jerseyConfig.register(new CORSFilter()); // 如果需要，可以注册CORS过滤器

        // 5. 创建ServletHolder，将Jersey应用包装成Servlet
        ServletHolder jerseyServletHolder = new ServletHolder(new ServletContainer(jerseyConfig));
        // 将Jersey Servlet映射到 "/api/*" 路径，相对于上下文路径 "/app"
        servletContextHandler.addServlet(jerseyServletHolder, "/api/*");

        // *** 关键步骤：将ServletContextHandler挂载到Server上 ***
        server.setHandler(servletContextHandler);

        // 6. 启动服务器
        try {
            server.start();
            System.out.println("Jetty server started on port 8080. Access your API at http://localhost:8080/app/api/hello");
            server.join(); // 阻塞主线程，直到服务器停止
        } catch (Exception e) {
            System.err.println("Error starting Jetty server: " + e.getMessage());
            e.printStackTrace();
        } finally {
            // 7. 停止和销毁服务器资源
            if (server.isRunning()) {
                server.stop();
                server.destroy();
                System.out.println("Jetty server stopped.");
            }
        }
    }
}

运行上述代码后，如果 api 包下存在 MyResource 类，你可以通过访问 http://localhost:8080/app/api/hello 来验证API是否正常工作。

Jetty Handler配置的注意事项与最佳实践

Handler链与HandlerCollection: 如果你需要配置多个Web应用上下文，或者需要处理静态资源、默认Servlet等多种类型的请求，可以将多个Handler组织在一个HandlerCollection中，然后将HandlerCollection设置为Server的主Handler。

// 示例：使用HandlerCollection管理多个Context
HandlerCollection handlers = new HandlerCollection();
handlers.addHandler(servletContextHandler1); // 第一个Web应用
handlers.addHandler(servletContextHandler2); // 第二个Web应用
// ... 可以添加其他Handler，如DefaultHandler处理未匹配请求
server.setHandler(handlers);

资源配置 (ResourceConfig): 对于JAX-RS (如Jersey) 应用，ResourceConfig是配置API资源、提供者、过滤器等的核心。确保packages()方法指向正确的包名，以便JAX-RS能够发现你的API端点。
错误排查: 当遇到404或其他错误时，首先检查Jetty的启动日志。Jetty会输出详细的启动信息，包括哪些Handler被注册、哪些上下文路径被激活等。同时，确保你的API资源类所在的包名与ResourceConfig.packages()中指定的包名一致。
生命周期管理: server.start()启动服务器，server.join()会阻塞当前线程直到服务器停止。在finally块中调用server.stop()和server.destroy()是良好的实践，确保在程序退出时释放所有资源。
CORS配置: 在生产环境中，跨域资源共享（CORS）是一个常见需求。如示例所示，你可能需要注册一个CORS过滤器（例如Jersey提供的org.glassfish.jersey.server.filter.CorsFilter或自定义实现）到ResourceConfig中，以允许来自不同域的请求访问你的API。

总结

Jetty嵌入式服务器的强大之处在于其灵活性，但这也要求开发者对Jetty的核心组件有清晰的理解。导致Jetty 404错误的一个常见但容易被忽视的原因，就是未能正确地将ServletContextHandler或其他处理请求的Handler实例挂载到Server上。通过调用 server.setHandler(handler);，我们明确地告诉Jetty服务器如何处理传入的HTTP请求。理解这一机制，并结合上下文路径与Servlet路径的正确配置，将帮助开发者高效地构建和部署基于Jetty的Web应用程序。

好了，本文到此结束，带大家了解了《Jetty404问题解决与Handler配置教程》，希望本文对你有所帮助！关注golang学习网公众号，给大家分享更多文章知识！