Beyond GET and POST: Why the New HTTP QUERY Method (RFC 10008) Matters for Modern APIs 的封面图片

Open Source Genie

自从我们大多数人开始构建 Web 应用程序以来，我们的数据检索选项一直感觉像是一种持续的架构妥协。

在设计搜索端点、复杂的筛选面板或深层嵌套查询时，我们面临一个令人沮丧的分叉路口：

  1. 使用 GET： 它是安全的、幂等的，并且可以被 CDN 和浏览器大量缓存。但它迫使你将庞大的 JSON 对象或复杂的搜索条件序列化到 URL 查询字符串中，存在浏览器长度限制、参数难以阅读以及敏感数据泄露到服务器访问日志的风险。
  2. 使用 POST： 它为你提供了一个干净的请求体来安全地发送丰富的负载。然而，POST 在默认情况下在语义上是非安全的、非幂等的。缓存层、负载均衡器和反向代理将拒绝缓存它，自动网络重试也会变得危险。

我们已经忍受了这些变通方法数十年。但 Web 架构格局正在发生变化。IETF 已正式标准化一个全新的核心方法：QUERY（RFC 10008）。

让我们来剖析它解决了什么、它是如何工作的，以及我们如何在现代 API 设计中思考它。

QUERY 解决的核心问题

从本质上讲，QUERY 引入了一个清晰的、语义化的解决方案：它充当一个“带请求体的安全 GET”。

为了理解为什么这是一个受欢迎的补充，让我们看看在官方规范下核心检索方法之间的比较：

属性 GET QUERY POST
安全（只读） 是 是 可能否
幂等（可重试） 是 是 可能否
有请求体 否 是 是
可缓存 是 是 有限

通过将读取数据的动作与传输大型负载的机制分离，QUERY 解决了几个持续存在的工程难题：

  • 不再有 URL 臃肿： 复杂的筛选器、类数据库的查询语言或深层图结构从 URI 字符串中移出，安全地进入请求体。
  • 默认隐私保护： 敏感的搜索条件（如个人属性、医疗筛选器或专有搜索参数）不再暴露在浏览器历史记录、中间代理日志或服务器访问日志中。
  • 内置效率： 由于 QUERY 被明确声明为可缓存和安全的，现代缓存基础设施可以像对待 GET 请求一样对待它，支持条件请求（如在底层数据集未更改时返回 304 Not Modified）。

架构模式：“等效资源”

伴随着数据密集型查询模式引入的最优雅的方面之一是利用 Location 头部的概念。

当客户端发送一个复杂的 QUERY 负载时，服务器并不仅仅返回即时的 JSON 数组。它还可以响应一个指向一个临时的或持久的资源标识符的 Location 头部，该标识符代表该特定查询的结果。

HTTP/1.1 200 OK
Content-Type: application/json
Location: /api/searches/9f8c-4a1b-8e3d

进入全屏模式 退出全屏模式

一旦服务器完成了初始查询的繁重工作，后续的轮询或分页就可以通过对该 URI 发起一个轻量级的、标准的 GET 请求来完成。它在有状态的查询执行和无状态的资源检索之间架起了一座桥梁。

生产就绪性和实现注意事项

虽然语义清晰性是后端架构的一大胜利，但推出一个全新的 HTTP 方法需要周全的基础设施规划：

  1. 边缘和代理过滤： 许多遗留的 Web 应用防火墙（WAF）、公司防火墙和反向代理被硬编码为阻止未识别的 HTTP 动词。在公共 API 中采用 QUERY 之前，请验证你的 API 网关和边缘基础设施能否优雅地处理自定义方法，而不是抛出 405 Method Not Allowed。
  2. 缓存键生成： 传统的 CDN 仅使用请求路径和查询字符串构建缓存键，完全忽略请求体。如果你缓存一个 QUERY 响应而没有自定义缓存键逻辑以包含请求体的哈希，你就有可能遇到灾难性的缓存碰撞问题（即用户 A 收到用户 B 的搜索结果）。
  3. 客户端生态系统支持： 确保你的上游 HTTP 客户端、移动网络库和内部服务到服务的通信工具支持在发送 QUERY 动词的同时发送请求体。

展望未来

RFC 10008 的引入为我们构建数据密集型、注重隐私且可扩展的系统提供了一个更清晰的词汇表。我们终于有了一等公民来查询数据，而无需滥用 POST 或将 GET 拉伸到其结构极限之外。

在你的技术栈中，你是如何处理现代 API 设计的？你是否计划在即将到来的内部架构中评估 QUERY？让我们在下面的评论区讨论。👇

#WebDev #APIDesign #HTTP #SoftwareArchitecture #Backend #TechStandards