Jetty使用AbstractHandler异步处理时重复请求触发IllegalStateException问题

你遇到的Jetty重复调用请求、startAsync()抛异常的问题，核心来自两个常见配置错误：

1. ContextHandler未显式开启异步支持，Jetty默认不允许在Handler中启动异步上下文，会触发异常后重试请求，导致二次调用。
2. Handler链存在多Handler匹配规则，你的业务Handler执行结束后未触发异步标记，Jetty会将请求继续传递给后续匹配的Handler，导致重复执行。

1. 开启ContextHandler异步支持 #

初始化ContextHandler时显式开启异步配置，无需修改请求处理逻辑即可合法调用startAsync()：

ContextHandler contextHandler = new ContextHandler("/your-business-path");
// 核心配置：开启上下文异步支持
contextHandler.setAsyncSupported(true);

2. 规范异步处理流程，符合Jetty生命周期要求 #

你不需要提前调用request.setHandled(true)，只需要在Handler入口增加状态判断，异步处理完成后再标记请求已处理即可：

@Override
public void handle(String target, Request baseRequest, HttpServletRequest request, HttpServletResponse response) throws IOException, ServletException {
    // 前置校验：跳过已处理、已开启异步的请求，避免二次执行
    if (baseRequest.isHandled() || baseRequest.isAsyncStarted()) {
        return;
    }

    // 启动异步上下文
    AsyncContext asyncContext = baseRequest.startAsync();
    // 按需配置异步超时时间，默认30s
    asyncContext.setTimeout(60000);

    // 提交到自定义线程池执行业务逻辑
    yourThreadPoolExecutor.submit(() -> {
        try {
            HttpServletResponse asyncResp = (HttpServletResponse) asyncContext.getResponse();
            // 你的业务逻辑实现
            writeBusinessResponse(asyncResp);
        } catch (Exception e) {
            // 异常处理逻辑
            response.setStatus(HttpServletResponse.SC_INTERNAL_SERVER_ERROR);
        } finally {
            // 业务处理完成后，符合规范设置handled标识，再结束异步上下文
            baseRequest.setHandled(true);
            asyncContext.complete();
        }
    });

    // 此处无需设置handled，Jetty感知到异步已启动，会自动终止Handler链传递
}

3. 校验Handler链配置，避免多Handler匹配 #

如果你使用HandlerCollection挂载多个Handler，确保你的业务ContextHandler优先级高于默认Handler、静态资源Handler等通用Handler，避免同一请求被多个Handler匹配：

Server server = new Server(8080);
HandlerCollection handlerCollection = new HandlerCollection();
// 业务Handler放在最前，优先匹配
handlerCollection.setHandlers(new Handler[]{contextHandler, new DefaultHandler()});
server.setHandler(handlerCollection);

4. 异常兜底校验 #

如果仍存在偶发异常，调用startAsync()前增加状态判断，避免IllegalStateException抛出：

if (baseRequest.isAsyncSupported() && !baseRequest.isAsyncStarted()) {
    AsyncContext asyncContext = baseRequest.startAsync();
    // 异步处理逻辑
}

内容的提问来源于stack exchange，提问作者Akshay Solanki