ARTICLE DETAIL

资讯详情

深耕郑州网站建设与运营推广的一线实战洞察。

Midway 跨域组件 @midwayjs/cross-domain 实战指南:CORS 与 JSONP 配置、原理与源码解析

Midway 跨域组件 @midwayjs/cross-domain 实战指南:CORS 与 JSONP 配置、原理与源码解析 后端微服务云原生【免费下载链接】midway A Node.js Serverless Framework for front-end/full-stack developers. Build the application for next decade. Works on AWS, Alibaba Cloud, Tencent Cloud and traditional VM/Container. Super easy integrate with React and Vue. 项目地址https://gitcode.com/gh_mirrors/mi/midway点击查看免费下载导读midwayjs/cross-domain是 Midway 框架提供的通用跨域组件一套配置即可同时覆盖midwayjs/koa、midwayjs/express、midwayjs/web与midwayjs/faas四种场景支持cors跨域资源共享与jsonp跨域脚本回调两种模式。读完本文你将掌握组件的一键接入方式、CORS 全部配置项的含义与取值、JSONP 的安全细节与 CSRF 防护以及从源码视角理解这两个中间件的实现原理与运行流程可直接复制配置用于生产环境。一、组件概览与适用场景跨域问题Cross-Origin Resource Sharing是前后端分离架构下的高频需求。Midway 将跨域能力封装为独立组件其核心特征在于多框架通用适用于midwayjs/faas、midwayjs/web、midwayjs/koa和midwayjs/express多种框架无需为每种框架编写不同的跨域处理代码双模式支持既支持基于 HTTP 头协商的cors模式也支持传统 JSONP 回调模式可覆盖浏览器端与旧式前端集成场景自动挂载组件在onReady生命周期中自动为各应用注册中间件开发者只需引入组件即可生效。组件版本信息见 package.json当前版本为4.2.3要求 Node.js 20运行时仅依赖vary一个第三方包体积轻量。二、快速接入安装与引入1. 安装依赖npm i midwayjs/cross-domain --save原文档使用tnpm淘宝 npm安装公网环境替换为npm或pnpm即可包名一致。2. 在 configuration 中引入组件import * as crossDomain from midwayjs/cross-domain; Configuration({ imports: [ // ...other components crossDomain ], }) export class AutoConfiguration {}从源码 configuration.ts 可以看到组件内部通过MidwayApplicationManager.getApplications([koa, faas, express, egg])获取所有相关应用实例并逐一执行app.useMiddleware(CorsMiddleware)完成自动挂载async onReady() { this.applicationManager .getApplications([koa, faas, express, egg]) .forEach(app { app.useMiddleware(CorsMiddleware); }); }这解释了为什么引入组件后无需手动声明中间件——CORS 中间件已被组件在启动阶段全局注册。JSONP 中间件则需要按需在路由上使用见后文这是由 JSONP 的调用形态决定的。三、CORS 配置详解CORS 配置通过src/config/config.default.ts中的cors键提供默认值如下export const cors: PartialCORSOptions { allowMethods: GET,HEAD,PUT,POST,DELETE,PATCH, credentials: false, };在业务项目中可以通过src/config/config.default.ts覆盖默认配置export const cors { allowMethods: string | string[]; origin: string | Function; exposeHeaders: string | string[]; allowHeaders: string | string[]; credentials: boolean | Function; keepHeadersOnError: boolean; maxAge: number; }配置项说明配置项类型默认值说明allowMethodsstring \| string[]GET,HEAD,PUT,POST,DELETE,PATCH允许的 HTTP 方法列表对应响应头Access-Control-Allow-Methodsoriginstring \| Function回显请求Origin允许的源传函数时以请求对象为参数动态计算返回值作为Access-Control-Allow-OriginexposeHeadersstring \| string[]未设置允许前端 JS 读取的响应头白名单对应Access-Control-Expose-HeadersallowHeadersstring \| string[]回显Access-Control-Request-Headers允许的自定义请求头对应Access-Control-Allow-Headerscredentialsboolean \| Functionfalse是否允许携带 Cookie 等凭证传函数时动态计算为true时输出Access-Control-Allow-Credentials: truekeepHeadersOnErrorboolean未设置为true时即使下游处理抛出异常也在错误响应上保留已设置的 CORS 响应头maxAgenumber未设置预检请求结果的缓存秒数对应Access-Control-Max-Age源码级原理CorsMiddleware 是 CORS 能力的核心实现其处理流程可归纳为以下几个关键环节统一抽象中间件对 Express 与 Koa 风格应用分别适配——express app.getNamespace()时以(req, res, next)签名工作否则以(ctx, next)工作再统一收敛到compatibleMiddleware(request, response, next)保证两套生态行为一致。恒置 Vary 头代码首先执行response.vary(Origin)借助vary依赖并在未携带Origin请求头时直接放行避免缓存代理因响应内容随来源变化而产生错误缓存const requestOrigin request.get(origin); response.vary(Origin); if (!requestOrigin) { return await next(); }动态 origin / credentialsorigin与credentials支持函数形态中间件用await Promise.resolve(...)消化异步返回值若函数形式的origin返回空值则直接放行不设置任何 CORS 头。预检请求Preflight处理当请求方法为OPTIONS且携带Access-Control-Request-Method时依次写入Access-Control-Allow-Origin、Access-Control-Allow-Credentials、Access-Control-Max-Age、Access-Control-Allow-Methods并在未显式配置allowHeaders时回显请求方声明的Access-Control-Request-Headers最终以204状态码结束预检if (request.method.toUpperCase() OPTIONS) { if (!request.get(Access-Control-Request-Method)) { return await next(); } // ...设置各类响应头 response.status 204; return ; }普通请求的响应头注入非预检请求会设置Access-Control-Allow-Origin、按需设置Access-Control-Allow-Credentials与Access-Control-Expose-Headers。错误透传时的头保留当keepHeadersOnError为true时中间件捕获下游异常将已设置的 CORS 头合并进err.headers并重新追加Vary: Origin再重新抛出确保错误响应同样携带正确的跨域头。中间件在 index.ts 中被统一导出类型定义CORSOptions位于 interface.ts与上述配置一一对应。四、JSONP 配置详解JSONP 通过src/config/config.default.ts中的jsonp键提供默认值如下export const jsonp: JSONPOptions { callback: jsonp, limit: 512, csrf: false, };在业务项目中按需覆盖export const jsonp { callback: jsonp, limit: 512, }配置项说明配置项类型默认值说明callbackstringjsonp回调函数名的查询参数名即前端请求中?callbackxxx的键名limitnumber512回调函数名的最大长度超出部分会被截断防止超长回调名注入csrfbooleanfalse是否启用 CSRF 校验开启后配合 Midway security 的assertCsrf能力校验失败抛出JSONPCSRFError注意原文档列出的 JSONP 配置只包含callback与limit而当前仓库的默认配置与类型定义见 config.default.ts 与 interface.ts还提供了csrf开关实际使用时可一并配置。源码级原理JSONP 能力由两部分组成路由级中间件JSONPMiddleware与响应格式化服务JSONPService。路由级挂载与 CORS 的全局自动注册不同JSONP 需要在具体路由上声明中间件例如测试夹具 fixtures/koa/src/configuration.ts 中的用法Post(/jsonp, { middleware: [JSONPMiddleware]}) async jsonp() { return { test: 123 }; }CSRF 防护JSONPMiddleware 在进入业务逻辑前若配置csrf: true且当前上下文提供assertCsrf方法Midway security 组件注入则执行校验失败时抛出JSONPCSRFErrorerror.ts这是一个403 Forbidden错误if (csrf context.assertCsrf) { try { context.assertCsrf(); } catch (_) { throw new JSONPCSRFError(); } }响应组装与 XSS 防护JSONPService 负责将业务返回值包装为可执行的 JavaScript设置Content-Type: application/javascript并写入x-content-type-options: nosniff响应头防止浏览器嗅探执行非预期内容从查询参数中取出回调名默认键名jsonp未传时回退为callback并用正则/[^[\]\w$.]/g过滤掉除[、]、字母数字、_、$、.以外的所有字符杜绝回调名中的恶意代码回调名超过limit默认 512时截断最终返回形如/**/ typeof cb function cb({test:123});的脚本字符串先注释掉前导内容再判断函数存在性从而抵御 JSONP XSS 攻击。测试 koa.test.ts 验证了这一行为请求/jsonp?callbackfn得到响应/**/ typeof callback function callback({test:123});且响应头包含x-content-type-options: nosniff。五、CORS 运行行为验证测试用例解读仓库 test 目录 提供了 koa、express、faas 三套独立的测试夹具覆盖了组件在各框架下的真实运行。以 koa.test.ts 为例可以看到关键行为预检请求OPTIONS /cors携带Origin: http://test.midwayjs.org与Access-Control-Request-Method: GET时期望返回204并带Access-Control-Allow-Origin、Access-Control-Allow-Credentials: true、Access-Control-Allow-Methods: Post——对应夹具中配置的allowMethods: Post与credentials: true。普通 GET 请求携带Origin时同样返回Access-Control-Allow-Origin与Access-Control-Allow-Credentials业务正常返回200。无 Origin 放行请求不携带Origin时响应中不含Access-Control-Allow-Origin业务逻辑正常执行——印证了中间件未带 Origin 直接next()的分支。函数式 origin夹具中将origin配置为(req) req.headers.origin验证了函数形态配置在运行时被调用并回显请求来源。这套测试同时覆盖了midwayjs/faas见 faas.test.ts 与 fixtures/faas与midwayjs/express见 express.test.ts是组件多框架通用承诺的实证。六、典型配置示例与注意事项1. 开放型 CORS前后端分离开发环境export const cors { allowMethods: [GET, POST, PUT, DELETE, PATCH, OPTIONS], origin: *, credentials: false, maxAge: 3600, };注意origin: *与credentials: true在浏览器规范中是互斥组合Access-Control-Allow-Origin: *时不能携带凭证如需携带 Cookie 必须使用具体源或函数动态返回来源。2. 白名单 凭证模式生产环境export const cors { origin: (req) { const allowList [https://www.example.com, https://admin.example.com]; return allowList.includes(req.headers.origin) ? req.headers.origin : null; }, credentials: true, allowMethods: GET,POST,PUT,DELETE, allowHeaders: [Content-Type, Authorization, X-Requested-With], exposeHeaders: [Content-Disposition, X-Total-Count], keepHeadersOnError: true, maxAge: 600, };函数式origin返回空值时中间件直接放行且不设置跨域头因此白名单校验失败时浏览器会按跨域错误处理实现服务端可控的源过滤。3. JSONP 开启 CSRF 校验export const jsonp { callback: callback, limit: 128, csrf: true, };开启csrf前需确保应用中已接入 Midway security 组件以提供assertCsrf能力校验失败时返回403JSONPCSRFError。JSONP 仅适合 GET或无需复杂请求头的场景旧式跨域方案新项目建议优先使用 CORS。4. 注意事项汇总组件的 CORS 中间件是全局自动挂载的无需在路由或全局中间件列表中重复声明JSONP 中间件需要按路由声明如{ middleware: [JSONPMiddleware] }且需配合JSONPService使用见 fixtures/koa/src/configuration.ts组件兼容koa、express、faas、webegg等框架底层通过MidwayApplicationManager统一分发configuration.ts配置均在项目自身的src/config/config.default.ts或对应环境配置文件中覆盖类型可参考 interface.ts 中的CORSOptions与JSONPOptions。七、结语midwayjs/cross-domain以极低的接入成本解决了 Midway 生态中跨域这一通用痛点CORS 中间件由组件自动挂载、对 Koa/Express 两套接口做了统一抽象并在预检、动态源、凭证、错误头保留等细节上处理完备JSONP 则在回调名过滤、长度限制、nosniff响应头与可选 CSRF 校验上提供了完整的 XSS 防护。开发者只需按上文配置覆盖默认值即可在midwayjs/koa、midwayjs/express、midwayjs/web与midwayjs/faas各框架下获得一致的跨域能力。赞分享后端微服务云原生【免费下载链接】midway A Node.js Serverless Framework for front-end/full-stack developers. Build the application for next decade. Works on AWS, Alibaba Cloud, Tencent Cloud and traditional VM/Container. Super easy integrate with React and Vue. 项目地址https://gitcode.com/gh_mirrors/mi/midway点击查看免费下载相关推荐Midway HTTP 代理组件midwayjs/http-proxy完全指南接入、多策略配置与源码级原理Midway HTTP 代理组件midwayjs/http proxy完全指南接入、多策略配置与源码级原理 midwayjs/http proxy 是后端微服务云原生Webamp 跨域资源加载实战CORS 配置指南与源码级原理解析Webamp 跨域资源加载实战CORS 配置指南与源码级原理解析 Webamp 是一个在浏览器中重新实现的 Winamp 2 播放器它通过 fetch 和前端音视频3分钟解决Vue跨域难题CORS配置与JSONP实战指南3分钟解决Vue跨域难题CORS配置与JSONP实战指南 你还在为Vue项目中的跨域请求头疼吗前端调试时频繁出现的 Access Control Allow前端上一篇如何用Obsidian模板宝库构建你的终极知识管理系统2025年超全指南 下一篇如何快速释放电脑内存免费高效的Windows Memory Cleaner工具全攻略创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表