Jetty的Handler是处理客户端请求的核心组件，所有进入服务器的请求都会经过Handler链的匹配与处理，若Handler配置不符合请求路由规则，就会直接返回404错误。很多开发者在本地调试或生产部署时，都会遇到应用启动正常但访问接口返回404的情况，本质都是Handler的路由逻辑出现了偏差。
Jetty Handler的核心工作机制
Jetty的Handler采用链式结构，请求会按照Handler的添加顺序依次传递，直到某个Handler能够处理该请求为止。常见的Handler类型包括ContextHandler、ServletContextHandler、WebAppContext等，不同类型的Handler负责不同粒度的请求匹配。
其中ServletContextHandler是最常用的Handler类型，它内部会维护Servlet、Filter的映射关系，能够将请求路径匹配到对应的Servlet处理逻辑。如果请求的路径没有在Handler的映射规则中找到对应处理项，Jetty就会返回404状态码。
常见导致404的Handler配置错误
1. 上下文路径设置错误
如果给ServletContextHandler设置了错误的上下文路径，那么所有请求的访问前缀都需要匹配该路径，否则无法进入对应的Handler处理。比如设置了上下文路径为/api，但访问时用了/app/test路径，就会直接404。
2. Handler未正确添加到Server
初始化Handler后如果没有将其设置到Server实例中，或者设置的Handler链顺序错误，都会导致请求无法到达目标Handler。比如把处理静态资源的Handler放在了业务Handler前面，且静态资源路径覆盖了业务路径，也会引发404。
3. Servlet映射路径不匹配
在ServletContextHandler中添加Servlet时，如果映射路径设置错误，比如需要匹配/user/list但只设置了/list，那么访问完整路径时就会找不到对应的Servlet，返回404。
正确的Handler配置方案
基础Servlet应用配置示例
以下是配置ServletContextHandler处理简单Servlet请求的正确代码：
import org.eclipse.jetty.server.Server;
import org.eclipse.jetty.servlet.ServletContextHandler;
import org.eclipse.jetty.servlet.ServletHolder;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;
// 自定义测试Servlet
class TestServlet extends HttpServlet {
@Override
protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException {
resp.setContentType("text/plain;charset=utf-8");
resp.getWriter().write("请求处理成功");
}
}
public class JettyHandlerDemo {
public static void main(String[] args) throws Exception {
// 初始化Jetty服务器，端口设置为8080
Server server = new Server(8080);
// 创建Servlet上下文Handler，设置上下文路径为根路径
ServletContextHandler contextHandler = new ServletContextHandler(ServletContextHandler.SESSIONS);
contextHandler.setContextPath("/");
// 添加TestServlet，映射路径为/test
contextHandler.addServlet(new ServletHolder(new TestServlet()), "/test");
// 将Handler设置到服务器
server.setHandler(contextHandler);
// 启动服务器
server.start();
System.out.println("Jetty服务器启动成功，访问地址：http://127.0.0.1:8080/test");
server.join();
}
}
Web应用部署配置示例
如果是部署完整的War包应用，需要使用WebAppContext，配置方式如下：
import org.eclipse.jetty.server.Server;
import org.eclipse.jetty.webapp.WebAppContext;
public class JettyWebAppDemo {
public static void main(String[] args) throws Exception {
Server server = new Server(8080);
WebAppContext webAppContext = new WebAppContext();
// 设置Web应用的War包路径，也可以是解压后的目录路径
webAppContext.setWar("D:/demo/webapp.war");
// 设置上下文路径
webAppContext.setContextPath("/webapp");
// 设置临时目录，避免文件冲突
webAppContext.setTempDirectory(new java.io.File("D:/jetty-temp"));
server.setHandler(webAppContext);
server.start();
System.out.println("Web应用部署成功，访问地址：http://127.0.0.1:8080/webapp");
server.join();
}
}
404问题排查步骤
遇到Jetty返回404时，可以按照以下步骤快速排查：
- 首先检查Server是否正确设置了目标Handler，没有遗漏setHandler步骤
- 确认Handler的上下文路径和访问路径的前缀是否匹配
- 检查Servlet或接口的映射路径是否和请求的完整路径一致
- 查看Jetty启动日志，确认Handler和Servlet是否成功注册
- 如果是Web应用，检查War包内的web.xml或注解配置是否正确
只要按照上述规则正确配置Handler的层级、上下文路径和映射规则，就能避免绝大多数配置类404错误，保障应用请求正常处理。