本文旨在解决 jetty 服务器中常见的 404 not found 错误，尤其在使用 `servletcontexthandler` 配置 web 应用时。核心问题通常是未将 `servletcontexthandler` 正确绑定到 `server` 实例。教程将提供正确的代码示例，并解释 jetty 的 handler 机制，确保 web 应用能够被服务器正确处理。
Jetty Handler 机制概述
Jetty 服务器是一个高度模块化的 Web 服务器，其核心功能之一是通过 Handler 接口来处理传入的 HTTP 请求。Server 实例本身并不直接处理请求，而是将请求委托给一个或一组 Handler。Handler 负责解析请求、生成响应，或者将请求进一步传递给其他 Handler。
在构建 Web 应用程序时，ServletContextHandler 是一个常用的 Handler 类型，它用于提供一个标准的 Servlet API 环境。这包括注册 Servlet、Filter、Listener，以及管理 Web 应用程序的上下文路径。当您希望在 Jetty 上运行基于 Servlet 的应用（例如使用 Jersey 实现 RESTful API）时，ServletContextHandler 是必不可少的。
问题诊断：为何出现 404 Not Found
在 Jetty 服务器中，如果配置了 ServletContextHandler 但仍遇到 404 Not Found 错误，最常见的原因是 Server 实例并未被告知如何使用您创建的 ServletContextHandler。
考虑以下示例代码：
Server server = new org.eclipse.jetty.server.Server(8080);
ServletContextHandler handler = new ServletContextHandler(server, "/example");
ResourceConfig config = new ResourceConfig();
config.packages("api");
config.register(new CORSConfig());
ServletHolder holder = new ServletHolder(new ServletContainer(config));
handler.addServlet(holder, "/api/*");
try {
server.start();
server.join();
} finally {
server.stop();
server.destroy();
}在这段代码中，您成功地创建了一个 Server 实例，并初始化了一个 ServletContextHandler 来处理 /example 路径下的请求，并为其添加了一个 Jersey ServletContainer 来处理 /api/* 的子路径。然而，问题在于 Server 实例和 ServletContextHandler 实例之间缺乏明确的关联。当 server.start() 被调用时，Jetty 服务器启动，但它没有被告知应该使用哪个 Handler 来处理传入的 HTTP 请求。因此，任何到达服务器的请求都无法找到对应的处理器，从而导致 404 Not Found 错误。
解决方案：正确绑定 Handler 到 Server
解决此问题的关键在于将您配置好的 ServletContextHandler 明确地设置给 Server 实例。这通过调用 server.setHandler(handler); 方法来实现。这个方法告诉 Jetty 服务器，当有请求到来时，应该使用 handler 这个 ServletContextHandler 来进行处理。
修正后的代码示例
以下是经过修正的 Jetty 服务器配置代码，它将确保您的 ServletContextHandler 能够被服务器正确识别和使用：
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 JettyServerConfig {
public static void main(String[] args) throws Exception {
// 1. 创建 Jetty Server 实例，监听 8080 端口
Server server = new Server(8080);
// 2. 创建 ServletContextHandler，并指定上下文路径为 "/example"
// 这意味着所有针对 /example/* 的请求都将由这个 handler 处理
ServletContextHandler handler = new ServletContextHandler(ServletContextHandler.SESSIONS);
handler.setContextPath("/example"); // 设置上下文路径
// 3. 配置 Jersey ResourceConfig
// 指定 Jersey 资源类所在的包名
ResourceConfig config = new ResourceConfig();
config.packages("api"); // 假设您的 RESTful 资源类在 "api" 包下
// 注册其他组件，例如 CORS 过滤器
config.register(new CORSConfig()); // 假设 CORSConfig 是一个自定义的 CORS 过滤器或提供者
// 4. 创建 Jersey ServletContainer 的 ServletHolder
// ServletHolder 负责将 Jersey 应用集成到 Jetty
ServletHolder holder = new ServletHolder(new ServletContainer(config));
// 5. 将 ServletHolder 添加到 ServletContextHandler
// 指定该 Servlet 将处理 "/api/*" 路径下的请求
// 结合上下文路径，最终的访问路径将是 /example/api/*
handler.addServlet(holder, "/api/*");
// 6. 核心修复：将 ServletContextHandler 绑定到 Server 实例
// 这一步是确保 Server 知道如何处理请求的关键
server.setHandler(handler);
try {
// 7. 启动 Jetty 服务器
server.start();
// 8. 阻塞当前线程，直到服务器停止
server.join();
} finally {
// 9. 确保服务器在程序退出时被停止和销毁
server.stop();
server.destroy();
}
}
// 假设 CORSConfig 是一个用于注册 CORS 过滤器的类
// 实际项目中可能是一个实现了 ContainerRequestFilter/ContainerResponseFilter 的类
static class CORSConfig extends org.glassfish.jersey.server.filter.CorsFilter {
public CORSConfig() {
// 示例：允许所有源，所有方法，所有头部
// 实际生产环境中应更严格配置
setAllowedOrigins(java.util.Collections.singletonList("*"));
setAllowedMethods(java.util.Collections.singletonList("*"));
setAllowedHeaders(java.util.Collections.singletonList("*"));
}
}
}代码解析与路径理解
- Server server = new Server(8080);: 初始化一个 Jetty 服务器，它将监听 8080 端口。
- ServletContextHandler handler = new ServletContextHandler(ServletContextHandler.SESSIONS);: 创建一个 ServletContextHandler。这里使用了 ServletContextHandler.SESSIONS 来启用会话管理。
- handler.setContextPath("/example");: 设置此 ServletContextHandler 的上下文路径为 /example。这意味着所有以 /example 开头的请求都将首先由这个 handler 处理。
- *`handler.addServlet(holder, "/api/");**: 在/example上下文内部，将ServletHolder（承载 JerseyServletContainer）映射到/api/*` 路径模式。
- server.setHandler(handler);: 这是解决 404 问题的关键行。 它将配置好的 ServletContextHandler 注册到 Server 实例，使得服务器知道如何处理针对 /example 上下文的请求。
访问路径解析： 根据上述配置，您的 Jersey RESTful API 将可以通过以下 URL 模式访问： http://localhost:8080/example/api/*
例如，如果您的 api 包中有一个资源类 MyResource 包含 @Path("/hello") 的方法，那么它将通过 http://localhost:8080/example/api/hello 访问。
重要提示： 如果您希望直接通过 http://localhost:8080/api/* 访问您的 API，那么 ServletContextHandler 的上下文路径应该设置为 "/"： handler.setContextPath("/");
注意事项与最佳实践
-
Handler 层次结构： 对于更复杂的应用，可能需要处理多个上下文或特殊路径。Jetty 提供了 HandlerCollection 或 ContextHandlerCollection 来组织多个 Handler。您可以将多个 ServletContextHandler 或其他类型的 Handler 添加到一个 HandlerCollection 中，然后将该 HandlerCollection 设置为 Server 的主 Handler。
// 示例：使用 HandlerCollection 管理多个上下文 HandlerCollection handlers = new HandlerCollection(); handlers.addHandler(contextHandler1); handlers.addHandler(contextHandler2); server.setHandler(handlers);
- 资源扫描： 确保 config.packages("api"); 中的包名是正确的，并且包含了所有 Jersey 资源类 (@Path 注解的类)。如果 Jersey 无法找到您的资源类，即使路径正确也会返回 404。
- 优雅停机： server.join(); 使得主线程阻塞，直到服务器停止。finally 块中的 server.stop(); 和 server.destroy(); 确保服务器资源在应用程序关闭时得到妥善释放。
- 日志配置： 强烈建议配置 Jetty 的日志系统（例如使用 SLF4J 结合 Logback 或 Log4j2），以便在开发和生产环境中获取详细的运行信息和错误诊断。详细的日志输出能够帮助您更快地定位问题。
- 错误处理： 对于 404 等 HTTP 错误，您可以配置自定义的错误页面或错误处理器，以提供更友好的用户体验。ServletContextHandler 允许通过 setErrorHandler() 方法设置自定义错误处理器。
总结
Jetty 服务器的 404 Not Found 错误，尤其是在初始化 ServletContextHandler 后出现，通常是由于未能将该 Handler 明确绑定到 Server 实例所致。通过简单的 server.setHandler(handler); 调用，您可以确保 Jetty 能够正确识别并处理您的 Web 应用程序请求。理解 Jetty 的 Handler 机制以及上下文路径和 Servlet 路径之间的关系，是有效配置和排查 Jetty 应用问题的关键。遵循本文提供的代码示例和最佳实践，将有助于您构建稳定且可维护的 Jetty Web 服务。
