如何在Web服务器线程中使用JavaFX Canvas生成图片并规避线程异常

问题背景 #

我用Javalin搭建了Web服务器，想要通过JavaFX Canvas生成算法图片后返回给HTTP请求。之前把Canvas嵌入Stage中使用完全正常，但直接在服务器线程里独立调用Canvas时，执行以下代码会抛出异常：

public byte[] getResponse() throws IOException {
  WritableImage snapshot = new FlowersFX(width, height).draw().getCanvas().snapshot(null, null);
  ByteArrayOutputStream stream = new ByteArrayOutputStream();
  ImageIO.write(SwingFXUtils.fromFXImage(snapshot, null), "png", stream);
  return stream.toByteArray();
}

抛出的异常 #

java.lang.IllegalStateException: Not on FX application thread; currentThread = JettyServerThreadPool-33
at javafx.graphics@23.0.2/com.sun.javafx.tk.Toolkit.checkFxUserThread(Toolkit.java:294)
at javafx.graphics@23.0.2/com.sun.javafx.tk.quantum.QuantumToolkit.checkFxUserThread(QuantumToolkit.java:481)
at javafx.graphics@23.0.2/javafx.scene.Node.snapshot(Node.java:2255)
at StaticImager/top.bagadbilla.handler.FlowerGeneratorHandler.getResponse(FlowerGeneratorHandler.java:35)
at StaticImager/top.bagadbilla.App.lambda$run$8(App.java:55)

踩过的坑 #

我尝试在服务器启动前调用Platform.startup()，并通过Platform.runLater()创建Canvas，但程序直接卡在future.get()处无限冻结。相关代码如下：

错误的Handler实现 #

public class FlowerGeneratorHandler {
private Canvas canvas;
private final RunnableFuture<Void> future;
public FlowerGeneratorHandler(int width, int height) {
    Runnable runnable = () -> canvas = new FlowersFX(width, height).draw().getCanvas();
    future = new FutureTask<>(runnable, null);
    Platform.runLater(future);
}

public byte[] getResponse() throws IOException, ExecutionException, InterruptedException {

    future.get();
    WritableImage snapshot = canvas.snapshot(null, null);
    ByteArrayOutputStream stream = new ByteArrayOutputStream();
    ImageIO.write(SwingFXUtils.fromFXImage(snapshot, null), "png", stream);
    return stream.toByteArray();
}
}

Javalin的Platform初始化 #

Javalin.create()
    .events(eventConfig -> {
        eventConfig.serverStarting(() -> Platform.startup(() -> {
            System.out.println("Starting platform");
        }));
        eventConfig.serverStopping(Platform::exit);
    })
.....

后来把future直接传入Platform.runLater()，结果原来的线程异常又再次出现。

最终解决办法 #

折腾后发现，不仅Canvas的创建要在FX线程，连canvas.snapshot()也必须在FX应用线程中执行。把生成快照、写入字节流的逻辑全部移到Platform.runLater()的任务里就解决了问题。修改后的代码如下：

public class FlowerGeneratorHandler {
    private final CompletableFuture<byte[]> imageFuture;

    public FlowerGeneratorHandler(int width, int height) {
        imageFuture = new CompletableFuture<>();
        Platform.runLater(() -> {
            try {
                // 所有Canvas相关操作都在FX线程完成
                Canvas canvas = new FlowersFX(width, height).draw().getCanvas();
                WritableImage snapshot = canvas.snapshot(null, null);
                ByteArrayOutputStream stream = new ByteArrayOutputStream();
                ImageIO.write(SwingFXUtils.fromFXImage(snapshot, null), "png", stream);
                // 把结果传给Future
                imageFuture.complete(stream.toByteArray());
            } catch (IOException e) {
                // 异常也传递出去
                imageFuture.completeExceptionally(e);
            }
        });
    }

    public byte[] getResponse() throws ExecutionException, InterruptedException {
        return imageFuture.get();
    }
}

核心要点 #

1. JavaFX的UI组件操作（包括Canvas创建、快照）必须在FX应用线程执行，这是JavaFX线程安全机制的强制要求。
2. 之前的错误要么是快照在非FX线程执行，要么是用FutureTask时结果传递逻辑有问题，换成CompletableFuture更简洁可靠。
3. 服务器启动时要确保Platform.startup()已调用，关闭时记得调用Platform.exit()清理FX线程资源。

内容的提问来源于stack exchange，提问作者p3w pew