本教程深入探讨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，但运行时访问 https://www.php.cn/link/29e71551bb5b6c041b895a9fdb6db557your_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将处理所有形如https://www.php.cn/link/29e71551bb5b6c041b895a9fdb6db557...` 的请求。
因此，如果你的API路径是 /api/users，那么完整的访问URL应该是 https://www.php.cn/link/29e71551bb5b6c041b895a9fdb6db557users。
完整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应用程序。
