Express写接口—接口的跨域问题-CORS中间件

'# Express写接口—接口的跨域问题-CORS中间件

一、背景与问题

在现代Web开发中，前后端分离架构已成为主流。前端应用通常运行在独立的域名下（如https://frontend.example.com），而后端接口服务运行在另一个域名下（如https://api.example.com）。当前端需要调用后端接口时，浏览器会触发跨域请求（Cross-Origin Request），此时会受到同源策略（Same-Origin Policy）的限制。

同源策略要求请求的协议、域名、端口必须完全一致。如果前端尝试调用不同源的接口，浏览器会阻止请求，除非服务器显式允许跨域访问。这种限制虽然保护了安全，但也给前后端分离开发带来了障碍。

为了解决这个问题，浏览器引入了CORS（Cross-Origin Resource Sharing）机制，而Express作为Node.js中最流行的Web框架，提供了多种处理CORS的方案。本文将深入探讨CORS的工作原理、实现方式、常见问题及最佳实践。

二、基本原理

1. 同源策略与CORS的矛盾

同源策略的核心是：浏览器不允许跨域请求，除非服务器明确允许。CORS通过在响应头中添加特定字段，向浏览器表明该接口可以被跨域访问。

关键响应头字段包括：

Access-Control-Allow-Origin：指定允许访问的源（域名）。可设置为具体域名（如https://frontend.example.com）或通配符*。
Access-Control-Allow-Methods：指定允许的HTTP方法（GET/POST/PUT/DELETE等）。
Access-Control-Allow-Headers：指定允许的请求头字段（如Content-Type）。
Access-Control-Allow-Credentials：是否允许携带凭证（如Cookie）。
Access-Control-Expose-Headers：指定可以暴露给前端的响应头字段。

2. 预检请求（Preflight Request）

对于非简单请求（如使用Content-Type: application/json、PUT、DELETE等），浏览器会先发送一个预检请求（OPTIONS），询问服务器是否允许跨域请求。服务器必须在响应中明确允许这些请求，否则后续请求会被拦截。

预检请求的条件包括：

请求方法是否为GET、POST、HEAD（简单方法）。
请求头是否包含Content-Type等特殊字段。
是否需要携带凭证（如Cookie）。

三、环境准备

确保已安装Node.js和Express，创建项目结构如下：

mkdir cors-demo
cd cors-demo
npm init -y
npm install express cors

项目结构建议：

cors-demo/
├── app.js
├── package.json
└── tests/
    ├── client.html
    └── client.js

四、核心实现

1. 基础CORS中间件使用

Express官方推荐使用cors库，它封装了CORS的复杂逻辑。以下代码展示了如何配置CORS中间件：

// app.js
const express = require('express');
const cors = require('cors');
const app = express();

// 配置CORS中间件
app.use(cors({
  origin: 'https://frontend.example.com', // 允许的源
  methods: ['GET', 'POST'],               // 允许的方法
  allowedHeaders: ['Content-Type'],       // 允许的请求头
  credentials: true,                      // 允许携带凭证
}));

// 示例接口
app.get('/api/data', (req, res) => {
  res.json({ message: 'Hello from server!' });
});

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
});

关键代码解释：

origin：指定允许的源，若设置为*则允许任意源，但需注意安全风险。
credentials: true：当需要携带Cookie时，必须设置此参数，并且origin必须明确指定。
allowedHeaders：控制哪些请求头可以被服务器处理。

2. 自定义CORS中间件

若需更精细控制CORS策略，可以手动实现中间件：

// app.js
const express = require('express');
const app = express();

// 自定义CORS中间件
function corsMiddleware(req, res, next) {
  const allowedOrigin = 'https://frontend.example.com';
  const allowedMethods = ['GET', 'POST'];
  const allowedHeaders = ['Content-Type'];

  // 处理预检请求
  if (req.method === 'OPTIONS') {
    res.setHeader('Access-Control-Allow-Origin', allowedOrigin);
    res.setHeader('Access-Control-Allow-Methods', allowedMethods.join(', '));
    res.setHeader('Access-Control-Allow-Headers', allowedHeaders.join(', '));
    res.setHeader('Access-Control-Allow-Credentials', 'true');
    res.status(204).send();
    return;
  }

  // 正常请求
  res.setHeader('Access-Control-Allow-Origin', allowedOrigin);
  res.setHeader('Access-Control-Allow-Methods', allowedMethods.join(', '));
  res.setHeader('Access-Control-Allow-Headers', allowedHeaders.join(', '));
  res.setHeader('Access-Control-Allow-Credentials', 'true');
  next();
}

app.use(corsMiddleware);

// 示例接口
app.get('/api/data', (req, res) => {
  res.json({ message: 'Hello from server!' });
});

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
});

关键代码解释：

预检请求（OPTIONS）需要单独处理，否则后续请求会被拦截。
Access-Control-Allow-Credentials设置为true时，origin必须明确指定，不能使用*。

3. 处理复杂请求的CORS配置

对于需要携带凭证的复杂请求，需额外配置：

// app.js
const express = require('express');
const cors = require('cors');
const app = express();

// 配置CORS中间件（带凭证）
app.use(cors({
  origin: 'https://frontend.example.com',
  methods: ['GET', 'POST'],
  allowedHeaders: ['Content-Type'],
  credentials: true,
}));

// 示例接口
app.get('/api/data', (req, res) => {
  res.json({ message: 'Hello from server!' });
});

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
});

关键代码解释：

credentials: true允许请求携带Cookie，但此时origin必须明确指定，否则浏览器会拒绝请求。

五、完整案例

1. 前端测试页面

创建tests/client.html文件，测试跨域请求：

<!-- tests/client.html -->
<!DOCTYPE html>
<html>
<head>
  <title>CORS Test</title>
</head>
<body>
  <h1>CORS Test Page</h1>
  <button onclick="fetchData()">Fetch Data</button>
  <div id="result"></div>

  <script>
    async function fetchData() {
      const response = await fetch('http://localhost:3000/api/data', {
        method: 'GET',
        headers: {
          'Content-Type': 'application/json'
        }
      });
      const data = await response.json();
      document.getElementById('result').innerText = JSON.stringify(data);
    }
  </script>
</body>
</html>

2. 启动服务并测试

启动Express服务器：
```
node app.js
```
在浏览器中打开tests/client.html，点击按钮发送请求。
若配置正确，会看到响应内容{"message": "Hello from server!"}。

3. 常见错误排查

错误1：请求被拦截

原因：服务器未正确设置Access-Control-Allow-Origin头。
解决：检查CORS中间件配置，确保origin设置正确。

错误2：预检请求失败

原因：服务器未响应预检请求（OPTIONS），或响应头不完整。
解决：确保中间件正确处理预检请求，返回所有必要的CORS头。

错误3：携带Cookie失败

原因：Access-Control-Allow-Credentials未设置为true。
解决：在客户端请求中设置withCredentials: true，并确保服务器配置credentials: true。

六、源码解析

以express-cors中间件为例，其核心逻辑如下：

// cors.js (简化版)
function cors(options) {
  return (req, res, next) => {
    const { origin, methods, allowedHeaders, credentials } = options;

    if (req.method === 'OPTIONS') {
      res.setHeader('Access-Control-Allow-Origin', origin);
      res.setHeader('Access-Control-Allow-Methods', methods.join(', '));
      res.setHeader('Access-Control-Allow-Headers', allowedHeaders.join(', '));
      res.setHeader('Access-Control-Allow-Credentials', credentials ? 'true' : 'false');
      res.status(204).send();
      return;
    }

    res.setHeader('Access-Control-Allow-Origin', origin);
    res.setHeader('Access-Control-Allow-Methods', methods.join(', '));
    res.setHeader('Access-Control-Allow-Headers', allowedHeaders.join(', '));
    res.setHeader('Access-Control-Allow-Credentials', credentials ? 'true' : 'false');
    next();
  };
}

关键点：

预检请求和正常请求的逻辑分离。
credentials参数控制是否允许携带凭证。
allowedHeaders限制哪些请求头可以被服务器处理。

七、进阶使用

1. 动态设置CORS策略

在生产环境中，可以根据请求来源动态设置CORS策略：

app.use((req, res, next) => {
  const origin = req.headers.origin;
  const allowedOrigins = ['https://frontend.example.com', 'https://admin.example.com'];

  if (allowedOrigins.includes(origin)) {
    res.setHeader('Access-Control-Allow-Origin', origin);
  } else {
    res.setHeader('Access-Control-Allow-Origin', '*');
  }

  res.setHeader('Access-Control-Allow-Methods', 'GET, POST');
  res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
  res.setHeader('Access-Control-Allow-Credentials', 'true');

  next();
});

2. 结合代理服务器

在开发环境中，可以通过Nginx或Vite等工具配置代理服务器，避免在应用层处理CORS：

# Nginx配置示例
location /api/ {
  proxy_pass https://api.example.com;
  proxy_set_header Origin $http_origin;
  add_header 'Access-Control-Allow-Origin' $http_origin;
  add_header 'Access-Control-Allow-Methods' 'GET, POST';
  add_header 'Access-Control-Allow-Headers' 'Content-Type';
}

优点：

避免在应用层处理复杂逻辑。
更容易统一管理CORS策略。

八、性能与工程实践

1. 性能优化

避免通配符*：在生产环境中，尽量指定具体域名，避免通配符带来的性能损耗。
缓存预检请求：浏览器通常会缓存预检请求的响应，但需注意缓存策略。
避免不必要的头字段：仅设置必要的CORS头，减少响应体积。

2. 异常处理

在CORS中间件中，应加入异常处理逻辑：

app.use((err, req, res, next) => {
  if (err instanceof Error) {
    console.error(err.stack);
    res.status(500).json({ error: 'Internal Server Error' });
  }
  next();
});

3. 安全性考虑

避免Access-Control-Allow-Origin: *：当接口需要携带凭证时，必须明确指定域名。
限制允许的HTTP方法和头字段：防止恶意请求滥用接口。
防止CSRF攻击：通过Access-Control-Allow-Credentials: true启用凭证，但需配合CSRF防护机制。

九、常见问题与踩坑

1. 预检请求失败

现象：浏览器发送OPTIONS请求，但服务器未正确响应。

原因：

未处理OPTIONS请求。
响应头缺少必要的CORS字段。

解决：确保中间件正确处理OPTIONS请求，并返回完整头信息。

2. 携带Cookie失败

现象：请求成功但Cookie未被发送。

原因：

未设置withCredentials: true。
服务器未设置Access-Control-Allow-Credentials: true。

解决：在客户端请求中设置withCredentials: true，并确保服务器配置正确。

3. 跨域请求被拦截

现象：请求返回No 'Access-Control-Allow-Origin' header。

原因：服务器未设置Access-Control-Allow-Origin头。

解决：检查中间件配置，确保该头被正确设置。

十、最佳实践

1. 推荐使用场景

前后端分离架构：前端和后端运行在不同域名时。
微服务架构：多个服务之间需要互相调用。
开发环境：通过代理服务器简化跨域配置。

2. 不推荐使用场景

同一域名下的接口调用：无需CORS处理。
使用代理服务器时：直接通过代理转发请求，无需应用层处理CORS。
需要高度安全控制的接口：避免使用通配符*，并严格限制允许的源。

3. 安全性建议

避免使用Access-Control-Allow-Origin: *，尤其是当接口需要携带凭证时。
对敏感接口添加额外的验证机制（如Token验证）。
定期审查CORS策略，确保没有配置错误。

十一、总结

CORS是解决跨域请求的核心机制，但其配置需要谨慎处理。Express通过cors中间件提供了简单且灵活的解决方案，但开发者仍需深入理解其工作原理，以避免常见错误。在实际项目中，应根据业务需求选择合适的配置方式，并结合安全性和性能优化策略。对于复杂场景，可以考虑使用代理服务器或自定义中间件，以获得更细粒度的控制。最终，合理配置CORS能够有效提升前后端协作效率，同时保障系统的安全性和稳定性。

Express写接口—接口的跨域问题-CORS中间件

一、背景与问题

二、基本原理

1. 同源策略与CORS的矛盾

2. 预检请求（Preflight Request）

三、环境准备

四、核心实现

1. 基础CORS中间件使用

2. 自定义CORS中间件

3. 处理复杂请求的CORS配置

五、完整案例

1. 前端测试页面

2. 启动服务并测试

3. 常见错误排查

六、源码解析

七、进阶使用

1. 动态设置CORS策略

2. 结合代理服务器

八、性能与工程实践

1. 性能优化

2. 异常处理

3. 安全性考虑

九、常见问题与踩坑

1. 预检请求失败

2. 携带Cookie失败

3. 跨域请求被拦截

十、最佳实践

1. 推荐使用场景

2. 不推荐使用场景

3. 安全性建议

十一、总结

评论已关闭

推荐阅读