Sails.js 请求对象 `req.originalUrl` 详解：获取未被重写前的原始请求 URL

Sails.js 请求对象req.originalUrl详解获取未被重写前的原始请求 URL【免费下载链接】sailsRealtime MVC Framework for Node.js项目地址: https://gitcode.com/gh_mirrors/sa/sailsreq.originalUrl是 Sails.js 请求对象req上的一个字符串属性用于保留客户端最初请求的 URL即使req.url在内部路由、策略policy或中间件中被重写你依然可以拿到原始地址。本文以 Sails.js 仓库中的官方参考文档为主线结合 请求对象构造源码 与 单元测试 深入讲解该属性的语义、底层实现与典型应用场景帮助你在开发控制器、策略与自定义中间件时准确判断用户到底访问了哪个地址。属性定义与官方语义根据 Sails.js 对 Express 4.x API 的引用req.originalUrl的定义如下该属性与req.url非常相似但它保留了原始请求 URL允许你在内部路由时自由重写req.url。用一句话概括req.originalUrl是req.url的不可变快照它只反映客户端最初发起的请求地址而在一次请求的完整生命周期中req.url则可能被框架内部或开发者自己的代码改写。Sails.js 在绝大多数情况下都建议优先使用req.url。只有当req.url被修改过例如在某个策略或中间件里为了把请求转到内部路由而重写它时req.originalUrl才会体现出不可替代的价值——它始终给你那个最初被请求的 URL。基本用法req.originalUrl是一个只读字符串属性直接访问即可无需任何参数req.originalUrl; // /search与req.url相同它包含路径和查询字符串query string后缀但不包含 URL 片段fragment / hash即#之后的部分。例如// 客户端请求: GET /search?qworlds%20largest%20dogs req.originalUrl; // /search?qworlds%20largest%20dogs req.url; // /search?qworlds%20largest%20dogs在未发生任何重写的情况下req.originalUrl与req.url的值完全一致二者的差异只会出现在req.url被修改之后。源码实现req.originalUrl从哪来在 Sails.js 中通用的请求对象由 lib/router/req.js 中的buildRequest(_req)工厂函数构造。该函数是 Sails 实现传输无关transport-agnostic中间件支持的基础既服务于 socket.io 等 hook也服务于应用级与内核级测试。构造过程中originalUrl的赋值逻辑位于 lib/router/req.js#L150req defaultsDeep(req, { params: [], query: (_req _req.query) || require(querystring).parse(parsedUrl.query) || {}, body: (_req _req.body) || {}, param: function(paramName, defaultValue) { /* ... */ }, wantsJSON: (_req _req.wantsJSON false) ? false : true, method: GET, originalUrl: _req.originalUrl || _req.url, path: _req.path || parsedUrl.pathname }, _req||{});从源码结构可以看出两个关键点回退链originalUrl优先取传入的_req.originalUrl若上层例如真实的 HTTP 服务器没有提供该字段则回退为_req.url。也就是说即使底层请求对象根本没有originalUrl概念Sails 也能保证req.originalUrl始终是一个可用的字符串。与req.url同源当请求进入 Sails 时req.url由_req.url携带见 lib/router/req.js#L76 构造 MockReq 时的url字段而originalUrl正是以它作为初始快照。二者在请求生命周期的起点指向同一个地址。此外构造请求时 Sails 还会用parseurl解析原始 URL以便从中分离出路径与查询字符串lib/router/req.js#L38-L40这与req.path、req.query的取值同源。测试验证单元测试如何锁定行为Sails 仓库在 test/unit/req.test.js 中对req.originalUrl的行为有明确的断言。测试用buildReq({url: /hello?abc123foobar})构造一个虚拟请求然后校验各属性it(.originalUrl, function() { req.originalUrl.should.be.an.String; req.originalUrl.should.equal(/hello?abc123foobar); });与之并列的断言还验证了test/unit/req.test.js#L87-L95req.path为/hello仅路径不含查询字符串req.url为/hello?abc123foobar路径 查询字符串req.query被解析为{ abc: 123, foo: bar }。这组测试从侧面印证了一个事实在未重写的情况下req.originalUrl、req.url与路径 查询串三者保持严格一致而req.path则是剥离查询串后的纯路径。典型应用场景当req.url被重写时Sails 内部的路由与中间件机制中req.url确实存在被改写的可能性。例如在 lib/router/index.js 的路由处理流程中框架会基于req.url提取并合并查询参数lib/router/index.js#L508-L510var queryStringPos req.url.indexOf(?); if (queryStringPos ! -1) { req.query _.merge(req.query, QS.parse(req.url.substr(queryStringPos 1))); }同时lib/router/bind.js 中的skipRegexesWrapper也会用req.url.match(regexes[i])判断 URL 是否命中某些正则lib/router/bind.js#L445-L449用以跳过特定路由的处理器。这类对req.url的读取与潜在改写正是req.originalUrl存在的意义。常见的真实场景包括场景一策略policy中的内部重定向在某个策略里将请求改写后转发给内部路由// api/policies/redirect-legacy.js module.exports function (req, res, next) { // 将旧路径重写为新的内部路由 req.url /search?q req.param(q); return next(); };此时在后续的 action 中req.url已经是/search?...但req.originalUrl仍保留用户最初请求的旧地址。若需要在日志、统计或鉴权逻辑中判断用户最初访问了哪里就必须读取req.originalUrl。场景二自定义中间件中的请求改写与策略类似在config/http.js中注册的自定义中间件也可能修改req.url以匹配内部路由。凡是你希望重写后仍然知道原始地址的地方都应该访问req.originalUrl。场景三日志与审计在记录请求日志时同时输出两个字段可以完整还原请求的来龙去脉sails.log.info(Original URL: %s | Current URL: %s, req.originalUrl, req.url);注意事项默认情况下请优先使用req.url正如官方文档反复强调的绝大多数业务代码并不关心原始 URLreq.url才是当前路由实际使用的地址。查询字符串包含在内req.originalUrl与req.url一样包含?之后的查询字符串与仅含路径的req.path不同。需要纯路径时请使用req.path对应源码中path: _req.path || parsedUrl.pathname的逻辑见 lib/router/req.js#L151。URL 片段hash不可用#之后的部分由浏览器端处理不会随 HTTP 请求发送到服务器因此req.originalUrl与req.url都取不到它如果你用res.redirect()返回 302 响应用户代理会在跳转后的地址上自动保留并追加原 URL 片段。始终是字符串单元测试中明确断言了req.originalUrl.should.be.an.Stringtest/unit/req.test.js#L98即便底层请求对象未提供该字段也会通过回退_req.url保证其类型与可用性。相关文档与参考req.url与req.originalUrl同源但可被重写的当前请求地址请求对象构造源码originalUrl的回退赋值逻辑第 150 行请求对象单元测试对req.originalUrl等属性的行为断言第 97-100 行Sails 路由器核心实现基于req.url的查询参数解析流程路由绑定源码正则路由包装器对req.url的匹配逻辑【免费下载链接】sailsRealtime MVC Framework for Node.js项目地址: https://gitcode.com/gh_mirrors/sa/sails创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考