SvelteKit 端点新特性：在 `+server.js` 中导出 `QUERY` HTTP 方法

Web框架后端前端【免费下载链接】kitweb development, streamlined项目地址https://gitcode.com/gh_mirrors/kit/kit点击查看免费下载SvelteKit 在本仓库当前代码中引入了一个新的端点能力server.js文件可以导出QUERY函数用于处理QUERYHTTP 方法。本文以.changeset/pre/query-method-server-export.md记录的minor变更feat: support the QUERY HTTP method in server.js为核心结合源码、类型定义、官方路由文档与真实测试用例讲解如何在项目中启用QUERY处理器、它的底层分发逻辑、与预渲染prerender的兼容性约束以及它与页面路由、内容协商之间的边界规则。读完本文你将能安全地在 API 端点中使用QUERY方法并理解 SvelteKit 对它的一切处理细节。这个变更记录了什么.changeset/pre/query-method-server-export.md是仓库中标准的 changeset 变更描述文件其内容如下--- sveltejs/kit: minor --- feat: support the QUERY HTTP method in server.js它声明了两件事影响范围sveltejs/kit包的minor次版本级功能新增而非破坏性变更特性内容server.js端点现在支持导出QUERY处理器。在该分支的代码中这一特性已经完整落地方法枚举、类型定义、运行时分发、文档与测试均已同步更新详见下文各节。对于使用 API 端点且需要携带请求体的安全查询场景即请求参数放在 body 中、而非塞进 URL 的GET请求QUERY是一个语义更合适的 HTTP 方法。QUERY 是什么一种带请求体的查询方法从仓库的类型定义可以确认QUERY已被正式纳入 SvelteKit 认可的方法集合。在 types/private.d.ts 中export type HttpMethod GET | HEAD | POST | PUT | DELETE | PATCH | OPTIONS | QUERY;结合常量定义可以进一步理解它的语义定位。在 constants.js 中export const ENDPOINT_METHODS [ GET, POST, PUT, PATCH, DELETE, OPTIONS, HEAD, QUERY ]; export const MUTATIVE_METHODS [POST, PUT, PATCH, DELETE]; /** methods whose responses depend on the request body, so they can never be prerendered */ export const BODY_DEPENDENT_METHODS [...MUTATIVE_METHODS, QUERY]; export const PAGE_METHODS [GET, POST, HEAD];关键信息有三点QUERY被列入ENDPOINT_METHODS即它是端点server.js可导出的合法方法之一它被归入BODY_DEPENDENT_METHODS——源码注释明确写道响应依赖请求体的方法因此永远不能被预渲染它不在PAGE_METHODSGET/POST/HEAD之列说明QUERY只属于 API 端点与页面渲染无关。仓库中的真实测试用例也印证了QUERY 携带请求体这一行为。见 endpoint-output/query/server.jsimport { text } from sveltejs/kit; export function GET() { return text(get); } /** type {import(./$types).RequestHandler} */ export async function QUERY({ request }) { return text(query: ${await request.text()}); }该处理器通过await request.text()读取请求体并回显验证了QUERY请求允许且应当携带 body。这与GET形成互补当查询参数复杂、内容较长例如结构化过滤条件时不再需要把它们编码进 URL。如何编写一个处理 QUERY 方法的端点与其它端点方法完全一致你只需要在src/routes/.../server.js中按方法名导出异步函数/// file: src/routes/api/search/server.js import { json } from sveltejs/kit; /** type {import(./$types).RequestHandler} */ export async function QUERY({ request, url }) { // 从请求体中读取结构化查询条件 const body await request.json(); // ...执行查询逻辑... return json({ results, matched: body.filters.length }); }要点归纳处理器接收标准的RequestEvent其中request是原生Request对象可读取 bodyurl、params、locals等照常可用返回值必须是Response对象可以借助sveltejs/kit提供的text、json等辅助函数也可以返回ReadableStream实现流式响应可以使用error与redirect便捷方法若请求方法在端点中没有对应导出例如只导出了QUERY却收到了PUT请求SvelteKit 会返回 405并在Allow响应头中列出实际支持的方法见下文运行时分发一节。官方路由文档同样把QUERY列为端点可导出的方法集合。见 10-routing.md 与 10-routing.mdYourserver.jsfile exports functions corresponding to HTTP verbs likeGET,POST,PATCH,PUT,DELETE,OPTIONS,HEAD, andQUERY...By exportingPOST/PUT/PATCH/DELETE/OPTIONS/HEAD/QUERYhandlers,server.jsfiles can be used to create a complete API.运行时是如何分发 QUERY 请求的端点请求的统一入口是 runtime/server/endpoint.js 中的render_endpoint。它根据请求方法取出对应的导出函数export async function render_endpoint(event, state, mod) { const method /** type {import(types).HttpMethod} */ (event.request.method); let handler mod[method] || mod.fallback; if (method HEAD !mod.HEAD mod.GET) { handler mod.GET; } if (!handler) { return method_not_allowed(mod, method); } // ... }由此可以梳理出三个行为规则直接按方法名取处理器mod[method]即QUERY请求会查找mod.QUERYHEAD的特殊退化当请求为HEAD且端点未导出HEAD时回退使用GET处理器QUERY不受此逻辑影响405 兜底找不到对应处理器时调用method_not_allowed。method_not_allowed实现在 runtime/server/utils.js它返回 405 状态码并通过allowed_methods生成符合 HTTP 规范的Allow响应头export function method_not_allowed(mod, method) { return text(${method} method not allowed, { status: 405, headers: { allow: allowed_methods(mod).join(, ) } }); } /** param {PartialRecordimport(types).HttpMethod, any} mod */ export function allowed_methods(mod) { const allowed ENDPOINT_METHODS.filter((method) method in mod); // if theres no HEAD handler, but we have a GET handler, we respond to // HEAD requests using the GET handler and omit the response body. if (GET in mod !(HEAD in mod)) { allowed.push(HEAD); } return allowed; }注意allowed_methods遍历的是ENDPOINT_METHODS已包含QUERY因此导出了QUERY的端点在收到不支持的方法时Allow头会正确列出QUERY。QUERY 请求永远交给端点处理内容协商规则同一路由下可以同时存在page与server.js此时 SvelteKit 需要判定一个请求是页面请求还是 API 请求。判定函数is_endpoint_request同样位于 runtime/server/endpoint.jsexport function is_endpoint_request(event) { const { method, headers } event.request; // These methods exist exclusively for endpoints if (ENDPOINT_METHODS.includes(method) !PAGE_METHODS.includes(method)) { return true; } // ... }由于QUERY在ENDPOINT_METHODS中却不在PAGE_METHODS中任何QUERY请求都会被无条件判定为端点请求直接交给server.js处理绝不会被当成页面请求。官方文档 10-routing.md 的内容协商一节对此有明确表述PUT/PATCH/DELETE/OPTIONS/QUERYrequests are always handled byserver.jssince they do not apply to pages也就是说QUERY与PUT、PATCH、DELETE、OPTIONS一样是页面不适用的方法不存在歧义分支而GET/POST/HEAD则需依据Accept头是否优先text/html来判断是页面还是端点。与预渲染prerender的兼容性约束QUERY方法的响应依赖请求体因此它被划入BODY_DEPENDENT_METHODS。这一划分直接作用于预渲染流程在 runtime/server/endpoint.js 中如果端点开启了prerender同时又存在请求体依赖方法或fallback处理器则直接抛错const prerender mod.prerender ?? state.prerender_default; if ( prerender (mod.fallback || /** type {import(types).HttpMethod[]} */ (BODY_DEPENDENT_METHODS).some( (method) mod[method] )) ) { throw new Error(Cannot prerender endpoints with body-dependent methods or fallback handlers); }实操建议若server.js导出了QUERY请不要对该路由声明export const prerender true否则构建build阶段会抛出上述错误同理若某个子路由在layout.js/page.js中开启全局预渲染涉及QUERY的端点也需要显式关闭预渲染或用fallback之外的方式规避根据 postbuild/prerender.js 等构建逻辑QUERY与POST等请求体依赖方法都不会被爬虫预取。这与POST等变更型方法的行为一致凡是响应依赖请求内容的端点都不适合静态预渲染。与 Remote Functions 中query的关系值得一提的是仓库中的另一套机制——remote functions$app/server导出的query/form/command/prerender四种远程函数——在客户端会被转换成对生成端点的fetch调用其中query类型的读取操作在服务端通过GET请求执行见 runtime/server/remote-functions.js 中对query.live必须走GET的校验而query.batch则要求POST。也就是说QUERY方法是开发者手工编写server.js端点时可直接导出的 HTTP 方法而 remote functions 的query是框架层的高级抽象二者概念不同、底层请求方法也不同但都服务于从服务端读取数据这一目标。如果你需要手写底层 API 并希望请求参数放在 body 中QUERY方法就是为这种语义准备的。小结server.js对QUERY方法的支持为 SvelteKit 端点补充了带请求体、语义为查询的 HTTP 能力。需要记住的关键事实如下事实证据QUERY是合法的端点导出方法constants.js 的ENDPOINT_METHODSQUERY属于请求体依赖方法不可预渲染constants.js 与 endpoint.js 的构建期校验QUERY请求总是由server.js处理不参与页面协商endpoint.js 与 10-routing.mdHttpMethod类型已包含QUERYtypes/private.d.ts官方有可直接运行的示例endpoint-output/query/server.js在实战中使用时只需在server.js中导出QUERY({ request })即可注意不要对该路由开启预渲染其余行为405 兜底、Allow头生成、流式响应、错误处理都与其它端点方法完全一致。赞分享Web框架后端前端【免费下载链接】kitweb development, streamlined项目地址https://gitcode.com/gh_mirrors/kit/kit点击查看免费下载相关推荐30分钟部署ERPNext中小团队开源ERP实施上手指南30分钟部署ERPNext中小团队开源ERP实施上手指南 进销存在一套 Excel 里开票在另一套收费软件里月底对账还要人肉比对两边流水——系统之间数据不后端企业应用H3 实战用 HTTP QUERY 方法RFC 10008在请求体中传递复杂查询H3 实战用 HTTP QUERY 方法RFC 10008在请求体中传递复杂查询 HTTP QUERY 是一种安全、幂等、可缓存的新方法它像 GET 一后端Web框架创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考