本文详解 vert.x 中 cors 配置失效的根本原因及正确解决方案，重点说明 routerbuilder 生成的 openapi 路由与 corshandler 的执行顺序问题，并提供可直接落地的代码示例与最佳实践。
本文详解 vert.x 中 cors 配置失效的根本原因及正确解决方案，重点说明 routerbuilder 生成的 openapi 路由与 corshandler 的执行顺序问题，并提供可直接落地的代码示例与最佳实践。
在 Vert.x 中集成 OpenAPI（通过 RouterBuilder）时，一个常见却易被忽视的问题是：CORS 头未生效，导致前端报错 No 'Access-Control-Allow-Origin' header is present。根本原因并非配置语法错误，而是路由注册顺序不当 —— RouterBuilder.createRouter() 生成的路由会覆盖或后置于手动添加的 CorsHandler，致使预检（OPTIONS）和实际请求均未经过 CORS 处理器。
✅ 正确做法：将 CorsHandler 提前注册为顶层路由处理器
必须确保 CorsHandler 作为最外层、最优先执行的中间件，作用于所有后续子路由（包括 OpenAPI 自动生成的路由）。因此，不应在 builder.createRouter() 返回的 router 上挂载 CorsHandler，而应在独立创建的顶层 Router 上先注册 CorsHandler，再将 OpenAPI router 作为子路由挂载。
以下是修正后的核心代码片段（适配您的 HttpServerVerticle）：
@Override
public void start(Promise<void> startPromise) {
ApiServiceApiHandler apiHandler = new ApiServiceApiHandler(new ApiServiceApiImpl());
RouterBuilder.create(vertx, specFile)
.map(builder -> {
builder.setOptions(
new RouterBuilderOptions().setRequireSecurityHandlers(false)
);
vertx.eventBus().registerDefaultCodec(DBUserRequest.class, new LocalEventBusCodec(DBUserRequest.class));
vertx.eventBus().registerDefaultCodec(ArrayList.class, new LocalEventBusCodec(ArrayList.class));
apiHandler.mount(builder);
// ✅ Step 1: 创建顶层 Router（非 builder.createRouter()）
Router router = Router.router(vertx);
// ✅ Step 2: 立即注册 CorsHandler —— 必须在 subRouter 之前！
router.route()
.handler(CorsHandler.create("http://localhost:4287")
.allowedMethod(HttpMethod.GET)
.allowedMethod(HttpMethod.POST)
.allowedMethod(HttpMethod.OPTIONS)
.allowCredentials(true)
// ⚠️ 注意：allowedHeader 中不应包含 "Access-Control-*" 类响应头
// 它们是服务端自动设置的；应允许客户端发送的请求头，如：
.allowedHeader("Content-Type")
.allowedHeader("Authorization")
.allowedHeader("X-Requested-With"));
// ✅ Step 3: 将 OpenAPI 路由挂载为子路由（路径默认为 "/"）
router.route().subRouter(builder.createRouter());
// 全局错误处理器仍作用于顶层 router
router.errorHandler(400, new ExceptionHandler());
router.errorHandler(405, new ExceptionHandler());
router.errorHandler(404, new ExceptionHandler());
return router;
})
.compose(router -> vertx.createHttpServer(options)
.requestHandler(router)
.listen(config().getInteger(ConfigConstants.PROPERTY_SERVICE_HTTP_PORT)))
.onSuccess(server -> {
logger.info("HTTP verticle deployed successfully on port " + server.actualPort());
startPromise.complete();
})
.onFailure(startPromise::fail);
}</void>
? 关键注意事项
- allowedHeader 含义澄清：CorsHandler.allowedHeader(...) 指定的是客户端请求中允许携带的请求头字段（如 Content-Type, Authorization），而非服务端要返回的响应头。Access-Control-Allow-* 响应头由 Vert.x 自动注入，无需也不应出现在 allowedHeader 列表中。
- Credentials 支持：若前端设置了 credentials: 'include'，则 allowCredentials(true) 必须启用，且 origin 不能为通配符 * —— 您当前的 "http://localhost:4287" 是合规的。
- 生产环境建议：避免硬编码 origin。可使用正则匹配（如 CorsHandler.create("https?://localhost(:\d+)?")）或动态白名单（结合 allowedOriginFunction）提升安全性。
- OPTIONS 预检处理：Vert.x 的 CorsHandler 已内置对 OPTIONS 请求的自动响应，无需额外定义 options 路由。
✅ 验证方式
启动应用后，使用 curl 或浏览器开发者工具检查响应头：
curl -H "Origin: http://localhost:4287" -I http://localhost:8081/api
应看到包含以下响应头：
Access-Control-Allow-Origin: http://localhost:4287 Access-Control-Allow-Credentials: true Access-Control-Allow-Methods: GET,POST,OPTIONS Access-Control-Allow-Headers: Content-Type,Authorization,X-Requested-With
遵循上述结构与原则，即可彻底解决 Vert.x + OpenAPI 场景下的 CORS 失效问题，确保前后端跨域通信稳定可靠。
