本文介绍在 Vert.x 中通过响应头拦截机制，为 StaticHandler 统一设置 Content-Disposition: attachment，使所有静态文件（如 PDF、图片、DOCX 等）默认触发浏览器下载而非内嵌渲染。
本文介绍在 vert.x 中通过响应头拦截机制，为 statichandler 统一设置 `content-disposition: attachment`，使所有静态文件（如 pdf、图片、docx 等）默认触发浏览器下载而非内嵌渲染。
在 Vert.x Web 应用中，StaticHandler 默认根据文件 MIME 类型决定响应行为：文本类资源（如 HTML、CSS）会被渲染，而二进制资源（如 PDF、图片）可能被浏览器直接显示——这虽符合常规 Web 交互逻辑，但在某些场景下（如提供文档下载服务、规避 XSS 风险、统一客户端处理流程）需要强制所有静态资源以附件形式下载。
Vert.x 并未提供 StaticHandler.setForceDownload(true) 这类开箱即用的配置，但其灵活的路由链机制允许我们在响应即将写出前动态注入 HTTP 头。关键在于利用 HttpServerResponse.headersEndHandler() —— 它在响应头已生成、但尚未发送给客户端时触发，是插入或修改响应头的最后安全时机。
以下是一个生产就绪的实现方案：
public class Server extends AbstractVerticle {
@Override
public void start() throws Exception {
Router router = Router.router(vertx);
router.route().handler(BodyHandler.create());
// 为 /static/* 路由添加前置响应头处理器
router.route("/static/*")
.handler(rc -> {
HttpServerResponse response = rc.response();
// 在响应头即将写入网络前，注入 Content-Disposition
response.headersEndHandler(v -> {
// 可选：仅对成功响应（2xx）设置，避免干扰错误页
if (response.getStatusCode() == 200) {
response.putHeader(HttpHeaders.CONTENT_DISPOSITION, "attachment");
}
});
rc.next(); // 继续执行后续处理器（即 StaticHandler）
})
.handler(StaticHandler.create("data")
.setCachingEnabled(false) // 建议禁用缓存，确保每次下载都是最新内容
.setDirectoryListing(false)); // 禁用目录浏览，提升安全性
vertx.createHttpServer()
.requestHandler(router)
.listen(8080, ar -> {
if (ar.succeeded()) {
System.out.println("Server started on http://localhost:8080");
}
});
}
}✅ 注意事项与最佳实践：
- headersEndHandler 是不可重复调用的，因此务必只注册一次；若需多条件判断，应在该 handler 内统一处理。
- 建议配合 getStatusCode() == 200 判断，避免对 404、500 等错误响应也添加 attachment，导致错误页被下载。
- 若需为不同文件类型指定不同文件名（如 filename="report.pdf"），可结合 rc.request().path() 解析原始请求路径，并使用 response.putHeader("Content-Disposition", "attachment; filename=\"" + safeFilename + "\"")。注意对文件名进行 URL 编码或 ASCII 兼容处理，防止乱码或安全问题。
- StaticHandler 默认启用缓存（ETag/Last-Modified），若资源频繁更新，应显式调用 .setCachingEnabled(false) 或配置合理的 maxAgeSeconds。
通过这一模式，你无需修改资源文件结构或 MIME 映射，即可全局、可控地将静态资源服务转变为“纯下载服务”，兼顾简洁性与工程健壮性。
