React向oas3-tools的Nodejs API发带自定义头POST请求遇CORS网络错误

问题背景 #

React应用发送带自定义version请求头的POST请求到基于oas3-tools的Node.js API时，预检OPTIONS请求未被正确处理，返回NetworkError。不带version头时请求正常，且已尝试两种方式添加CORS中间件，但CORS代码未触发——oas3-tools自带的OPTIONS请求处理逻辑先执行了。

核心原因 #

oas3-tools的路由中间件会优先捕获OPTIONS请求并返回默认响应，导致后续的CORS中间件没有机会处理自定义请求头的授权逻辑。

解决方案 #

方案1：确保CORS中间件在oas3-tools路由之前加载 #

修改Node.js配置，将CORS中间件直接挂载到express app最前面，确保它优先于oas3-tools路由执行：

'use strict'; 
var insertMiddleware = require('./helpers/insertMiddleware.js');
var path = require('path');
var http = require('http');
var oas3Tools = require('oas3-tools');
var serverPort = 8080;
const cors = require('cors');
const express = require('express');

// 先创建基础express实例并挂载CORS
var app = express();
app.use(cors({
  origin: '*', 
  allowedHeaders: ['Accept', 'version'], // 明确指定允许的自定义头，比通配符更严谨
  exposedHeaders: ['version'], // 若前端需要读取响应头中的version则添加
  credentials: true // 涉及Cookie等凭证时开启，按需调整
}));

/* swaggerRouter configuration*/
var options = {
    routing: {
        controllers: path.join(__dirname, './controllers'),
    },
};

// 基于已配置CORS的app生成oas3-tools配置
var expressAppConfig = oas3Tools.expressAppConfig(
  path.join(__dirname, 'api/openapi.yaml'), 
  options,
  app
);

// 启动服务器
http.createServer(app).listen(serverPort, function () {
    console.log('Your server is listening on port %d (http://localhost:%d)', serverPort, serverPort);
    console.log('Swagger-ui is available on http://localhost:%d/docs', serverPort);
});

方案2：直接配置oas3-tools的CORS选项 #

oas3-tools底层支持直接在配置中开启CORS并自定义规则，无需额外挂载中间件：

'use strict';
var path = require('path');
var http = require('http');
var oas3Tools = require('oas3-tools');
var serverPort = 8080;

/* swaggerRouter configuration*/
var options = {
    routing: {
        controllers: path.join(__dirname, './controllers'),
    },
    // 内置CORS配置
    cors: {
        origin: '*',
        allowedHeaders: ['Accept', 'version'],
        methods: ['GET', 'POST', 'OPTIONS', 'PUT', 'DELETE'],
        exposedHeaders: ['version']
    }
};

// 生成app并启动
var expressAppConfig = oas3Tools.expressAppConfig(path.join(__dirname, 'api/openapi.yaml'), options);
var app = expressAppConfig.getApp();

http.createServer(app).listen(serverPort, function () {
    console.log('Your server is listening on port %d (http://localhost:%d)', serverPort, serverPort);
    console.log('Swagger-ui is available on http://localhost:%d/docs', serverPort);
});

方案3：手动拦截OPTIONS请求 #

如果上述方案无效，可直接手动处理OPTIONS请求，返回符合要求的CORS响应头：

'use strict'; 
var path = require('path');
var http = require('http');
var oas3Tools = require('oas3-tools');
var serverPort = 8080;

/* swaggerRouter configuration*/
var options = {
    routing: {
        controllers: path.join(__dirname, './controllers'),
    },
};

var expressAppConfig = oas3Tools.expressAppConfig(path.join(__dirname, 'api/openapi.yaml'), options);
var app = expressAppConfig.getApp();

// 手动处理OPTIONS请求，放在所有路由之前
app.options('*', (req, res) => {
  res.setHeader('Access-Control-Allow-Origin', '*');
  res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS, PUT, DELETE');
  res.setHeader('Access-Control-Allow-Headers', 'Accept, version');
  res.sendStatus(200);
});

http.createServer(app).listen(serverPort, function () {
    console.log('Your server is listening on port %d (http://localhost:%d)', serverPort, serverPort);
    console.log('Swagger-ui is available on http://localhost:%d/docs', serverPort);
});

额外优化建议 #

• React请求中无需手动设置Origin头，浏览器会自动添加，手动设置可能导致跨域校验不匹配
• 生产环境避免使用origin: '*'，指定具体的前端域名更安全
• 明确指定allowedHeaders而非通配符，符合CORS规范且降低安全风险

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