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

发布时间:2026/11/19 4:40:52

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),仅供参考
延伸阅读

更多相关文章

2026/11/15 15:07:38

唐杰说的 AI 员工要上岗,Agent 的 Base URL 填 TaoToken

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

2026/11/15 17:52:37

OpenClaw 跑多智能体协作任务,Key 用 TaoToken

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

2026/11/19 4:35:53

焊工特种作业操作证在手,值不值得考?周口人这样说

焊工特种作业操作证在手,值不值得考?周口人这样说 怕考不过白交培训费?别急,焊工特种作业操作证在最新政策下,考试难度、报名门槛、考试内容都有新变化,这篇文章给你讲透彻,避免你走弯路,花冤枉钱。 焊工证到底值不值得考?周口人的真实经历告诉你…

2026/11/19 4:35:53

特种作业操作证去那领?上岗必备的转证流程和避坑指南

特种作业操作证去那领?上岗必备的转证流程和避坑指南 之前考的证在外省能不能转过来?这几乎是每个特种作业人员都问过的问题,尤其是像你在郑州金水区从事市政公用工程的同行,跨省工作、项目变动频繁,证书归属地的问题就变得尤为重要。今天就结合一个真实…

2026/11/19 4:35:53

耒阳哪里能考电工证通过率揭秘:工地太忙根本没时间复习考试怎么办

耒阳哪里能考电工证通过率揭秘:工地太忙根本没时间复习考试怎么办 工地太忙根本没时间复习考试,这种焦虑你肯定不陌生。特种作业操作证是进入施工现场、从事电工等高风险岗位的“通行证”,但现实是,大多数人都是在忙碌的施工节奏中被“临时抱佛脚”,考试…

2026/11/19 4:35:53

新蔡办电工证2026河南最新政策怎么考?怕被中介坑看这篇就够了

新蔡办电工证2026河南最新政策怎么考?怕被中介坑看这篇就够了 你是不是也在担心 新蔡办电工证 到底要去哪儿报?网上一搜全是中介广告,真假难辨,一不小心就花了冤枉钱,还拿不到证?别急,2026河南最新政策已经明确,咱们来一步步帮你搞清楚怎么…

2026/11/19 4:35:53

水电工作业自查多久拿证怕考不过白交培训费

水电工作业自查多久拿证怕考不过白交培训费 怕考不过白交培训费?水电工作业自查多久拿证,这可能是你最关心的事。别急,今天就来聊聊怎么避开那些“坑”,稳稳拿到证书,省心又省钱。 一、水电工作业自查到底是什么?…

2026/11/19 4:30:48

在网上办理的电工证考试真题与备考技巧

电工证在网上办理怕考不过白交培训费?郑州报考避坑指南全解析 怕考不过白交培训费?这是很多河南电工考生最担心的事,尤其是在郑州这样报考人数多、培训机构鱼龙混杂的地方。如果你正在考虑在网上办理电工证,又担心考试不过、材料不全、流程复杂,这篇文章…

2026/11/18 21:12:58

电工证考试口诉怎么准备值不值得考

电工证考试口诉怎么准备值不值得考 实操考试心里没底怕挂科,这是大多数准备考电工证的人心里最真实的感受。尤其是面对【电工证考试口诉】环节,很多人不知道该怎么准备,甚至担心自己说不好就被淘汰。其实,只要掌握方法, 值不值得考…

2026/11/18 21:55:23

桑植县考电工证千万别踩坑!报名全流程教你避坑

桑植县考电工证千万别踩坑!报名全流程教你避坑 你是不是也遇到过这种情况:想考个电工证,但不知道从哪儿下手,怕被中介坑,怕花冤枉钱,更怕考了证还不能用?别急,这正是你该看这篇文章的原因。在桑植县考电工证,确实有很多人被坑过,但只要你知道流程、…

2026/11/19 0:04:42

深圳电工证培训考场模拟考试题库:郑州报考避坑指南

深圳电工证培训考场模拟考试题库:郑州报考避坑指南 证书过期了不知道怎么复审延期,很多人在遇到这个问题的时候才意识到特种作业证的重要性。其实,不管是电工证、焊工证还是高处作业证,这些证书不仅是上岗的“通行证”,更是法律对安全操作的硬性要求。尤…

2026/11/19 0:04:42

天津电工证查询入口多少钱能报上名

天津电工证查询入口多少钱能报上名 学历不高怕报不上名?别急,天津电工证查询入口其实没你想的那么难。今天咱们就来聊聊,怎么用最低的门槛、最少的钱,把电工证拿下来,还能查得到、用得上。 电工证到底值不值?先搞清楚它的作用…

2026/11/18 12:37:05

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

在智慧养宠时代,基于视觉的宠物身份识别技术正逐步从实验室走向家庭应用。然而,与配合度高的人类不同,宠物是典型的“非合作生物识别对象”——它们不会主动配合摄像头调整姿态,更无法控制光照环境。实际应用中,我们常…

2026/11/18 1:15:04

SSM电子书店源码全解析:结构、原理、部署与排错实战

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

还想了解更多?直接咨询顾问

免费诊断 + 免费方案 + 透明报价。

全国咨询热线400-8866-253
免费获取方案
☎咨询二维码 ☎ ↑