后端【免费下载链接】sailsRealtime MVC Framework for Node.js项目地址https://gitcode.com/gh_mirrors/sa/sails点击查看免费下载本指南深入讲解 Sails 框架内置请求属性req.wantsJSON它用于判断客户端是否期望收到 JSON 格式的响应而非 HTML、XML 等其他格式是 Sails 全部内置自定义响应built-in custom responses进行内容协商的核心依据。读完本文你将掌握req.wantsJSON的判定规则、底层启发式算法、在控制器/响应中的典型用法以及如何结合源码理解并复用它。什么是req.wantsJSONreq.wantsJSON是 Sails 在每个请求上下文中注入的一个布尔标志用于指示发起请求的客户端是否更倾向于收到 JSON 响应与 XML、HTML 等其他格式相对。在 Sails 的 请求对象文档 体系中它属于由 request hook 在路由执行前注入的请求限定符request qualifier之一与req.xhr、req.isSocket、req.accepts()、req.get()等能力同属一套内容协商工具集。官方定位req.wantsJSON提供了一种干净、可复用的指标用于判断服务器应返回 JSON 还是其他内容。它并非所有内容协商问题的正确答案但对绝大多数场景而言是一个简单、开箱即用的首选方案。用法一行属性读取req.wantsJSON是一个只读属性直接读取即可req.wantsJSON;典型的使用场景是在控制器动作action或策略policy中根据客户端偏好分流响应if (req.wantsJSON) { sails.log(This request wants JSON!); } else { // req.wantsJSON 为 falsyundefined说明该请求不想要 JSON。 }从源码看该属性在 lib/hooks/request/qualifiers.js 中通过一组或逻辑链||逐步赋值最终结果是true或false布尔值不会是undefined而在 lib/router/req.js 构造通用请求对象时其默认值为true仅当显式传入_req.wantsJSON false时才为false体现了 Sails 信息不足时偏向 JSON 的设计哲学。判定规则五级启发式算法req.wantsJSON的判定在 lib/hooks/request/qualifiers.js 中实现request hook 会在每个 HTTP/HTTPS 请求的路由处理之前执行_mixinReqQualifiers()见 lib/hooks/request/index.js 中对req.protocol的判断。判定采用短路求值只要命中以下任一条后续检查全部跳过请求即被判定为想要 JSONreq.wantsJSON req.xhr; req.wantsJSON req.wantsJSON || req.isSocket; req.wantsJSON req.wantsJSON || !req.explicitlyAcceptsHTML; req.wantsJSON req.wantsJSON || (req.is(json) req.get(Accept)); req.wantsJSON req.wantsJSON || req.options.wantsJSON;对应文档中的五条规则按优先级从高到低为它看起来像一个 AJAX 请求req.xhr为真请求携带X-Requested-With头时req.xhr为true它是来自 socket 的虚拟请求req.isSocket为真WebSocket 客户端发起的请求一律视为想要 JSON见下方 Notes请求没有显式要求 HTML!req.explicitlyAcceptsHTMLreq.explicitlyAcceptsHTML由源码第 21 行accept.indexOf(html) ! -1计算得出即Accept头中是否出现html字样请求的 Content-Type 为json且同时设置了Accept头req.is(json) req.get(Accept)req.options.wantsJSON为真值路由目标route target的options中显式声明了wantsJSON可强制覆盖前序判定结果。信息不足时的兜底策略技术上req.wantsJSON会检查请求的Content-Type、Accept与X-Requested-With三个头来判断客户端预期。当这些头提供的信息过于稀少时Sails 偏向于 JSONreq.wantsJSON会被置为true。一个典型例子所有主流浏览器在地址栏直接输入 URL 发起请求时会携带Accept: text/plain;头此时req.wantsJSON为false因为不满足上述任何一条而在很多其他场景下客户端意图并不明确此时启发式算法会兜底选择 JSON。关于req.options.wantsJSON第 5 条规则中的req.options对应当前匹配路由目标的 options 对象。这意味着你可以在config/routes.js中为某个路由显式指定// config/routes.js module.exports.routes { get /api/things: { action: thing/find, options: { wantsJSON: true // 强制该路由按 JSON 偏好处理 } } };这一机制让开发者可以在不修改客户端请求头的前提下按路由粒度覆盖内容协商结果是实现API 端点始终返回 JSON的便捷手段。为什么是偏向 JSON设计动机与收益req.wantsJSON的核心价值在于面向未来、减少脆弱性框架级统一修补内容协商的最佳实践会随时间演进例如新型消费设备或企业级 User-Agent 引入新请求头。Sails 可以在框架层面直接修补req.wantsJSON的启发式逻辑所有应用自动受益无需逐个路由手工改动消除重复代码开发者不必在每条路由中手动解析Accept、X-Requested-With等头逻辑集中一处、可读性更高语义清晰true/false的布尔语义比裸读头字符串更直观也便于在模板、策略与响应中统一引用。内置自定义响应中的实际应用文档明确指出req.wantsJSON被 Sails 的全部内置自定义响应所使用。查看仓库中 lib/hooks/responses/defaults 目录下的实现可以看到典型模式——如果请求想要 JSON 或有视图渲染失败就返回 JSON否则渲染 HTML 错误页res.notFound()404 处理notFound.js// Set status code res.status(404); // If the request wants JSON, send back the appropriate status code. if (req.wantsJSON || !res.view) { return res.sendStatus(404); } return res.view(404, {}, function (err, html) { // If a view error occured, fall back to JSON. if (err) { // ...日志处理... return res.sendStatus(404); } return res.send(html); });res.serverError()500 处理serverError.js// Set status code res.status(500); // If appropriate, serve data as JSON. if (req.wantsJSON || !res.view) { // If no data was provided, use res.sendStatus(). if (data undefined) { return res.sendStatus(500); } // ... return res.json(data); } return res.view(500, { error: data }, function (err, html) { // ... });同理res.badRequest()badRequest.js在收到数据时一律以res.json(data)返回 JSON而res.forbidden()、res.negotiate()negotiate.js则按状态码分发到上述响应。结论当客户端偏好 JSON或视图渲染不可用时浏览器请求与 API 请求会分别得到 HTML 错误页与 JSON 错误体——这正是req.wantsJSON在框架默认行为中的直接体现。视图层对req.wantsJSON的反馈回路一个容易被忽视的细节当视图渲染失败时Sails 会在 lib/hooks/views/res.view.js 与第 402 行主动将req.wantsJSON置为true随后转交res.serverError()处理。这确保了视图报错时绝不递归渲染视图、而是回退到 JSON 响应防止无限递归源码第 340 行的req._errorInResView守卫同样为此服务。可见req.wantsJSON不仅在请求入口被判定也会在请求生命周期中被框架内部主动修正。典型实战模式模式一同一动作同时服务页面与 API// api/controllers/user/find.js module.exports { friendlyName: Find users, fn: async function (req, res) { const users await User.find(); if (req.wantsJSON) { return res.json(users); } // 否则渲染服务端视图 return res.view(pages/user/list, { users: users }); } };模式二统一错误处理中间件在自定义响应或策略中复用该标志可保证错误输出格式与客户端预期一致// api/responses/tooManyRequests.js 示例片段 module.exports function tooManyRequests (message) { const req this.req; const res this.res; res.status(429); if (req.wantsJSON) { return res.json({ error: message || Too many requests. }); } return res.view(429, { message: message }); };模式三与低层内容协商工具组合文档 Notes 明确指出低层内容协商仍然可以使用以下工具完成req.is(type)检查请求 Content-Type 是否匹配指定类型见 req.isreq.accepts(types)基于Accept头判断客户端可接受的媒体类型见 req.acceptsreq.xhr判断是否为 AJAX 请求X-Requested-With头req.get(header)读取任意请求头见 req.get。当业务需要精细控制例如同时接受 JSON 与 XML、并按Accept优先级返回时可绕过req.wantsJSON直接组合上述工具。注意事项Notes更低层级的内容协商仍然可以使用req.is()、req.accepts()、req.xhr和req.get()实现。自 Sails v0.10 起来自 WebSocket 客户端的请求始终想要 JSON对应判定规则第 2 条req.wantsJSON req.wantsJSON || req.isSocket;。这意味着 socket 虚拟请求virtual request默认绕过 HTML 视图路径直接走 JSON 通道。源码速查关注点仓库路径判定算法五级启发式lib/hooks/request/qualifiers.js请求限定符的注入时机lib/hooks/request/index.js请求对象默认值lib/router/req.js404 响应的 JSON/HTML 分流lib/hooks/responses/defaults/notFound.js500 响应的 JSON/HTML 分流lib/hooks/responses/defaults/serverError.js视图渲染失败时强制 JSONlib/hooks/views/res.view.jsrequest hook 功能说明lib/hooks/request/README.md请求对象参考文档docs/reference/req/req.md小结req.wantsJSON是 Sails 内容协商体系中简单优先思想的缩影它用一条布尔属性封装了五级启发式判定默认偏向 JSON并在框架内置的 404/400/403/500 等自定义响应与视图渲染失败兜底逻辑中广泛使用。理解其判定顺序AJAX → socket → 未显式要求 HTML → JSON Content-Type Accept →req.options.wantsJSON与源码位置能帮助你在构建同时服务浏览器与 API 客户端的应用时写出既简洁又健壮的响应分发逻辑。赞分享后端【免费下载链接】sailsRealtime MVC Framework for Node.js项目地址https://gitcode.com/gh_mirrors/sa/sails点击查看免费下载相关推荐Qwen Code web_fetch 工具完全指南URL 抓取、Markdown 内容协商与源码级原理解析Qwen Code web_fetch 工具完全指南URL 抓取、Markdown 内容协商与源码级原理解析 本指南系统讲解 Qwen Code 内置 web人工智能AI Agent代码智能体工具调用交互助手CLIQwendaisyUI Hover Gallery 组件完整指南实现原理、CSS 源码解析与电商实战用法daisyUI Hover Gallery 组件完整指南实现原理、CSS 源码解析与电商实战用法 Hover Gallery 是 daisyUI 提供的一款图前端UI组件oapi-codegen与API版本协商内容协商的生成代码实现oapi codegen与API版本协商内容协商的生成代码实现 你是否曾因API版本兼容性问题导致客户端与服务端数据格式不匹配是否在手动处理 Accept开发工具代码生成API设计创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考