请教：Apollo如何在同一端点同时提供Sandbox HTML与GraphQL查询处理器？

安全阿岳

2026-8-12

Apollo同端点同时提供Sandbox与GraphQL查询的实现解析

这其实是Apollo Server基于HTTP请求特征做的条件分支处理——同一个端点（默认是/graphql）会根据请求的方法、头信息，决定返回Sandbox调试页面还是处理GraphQL查询。下面拆解具体逻辑：

1. 核心判断逻辑

Apollo Server的路由处理逻辑会先检查两个关键维度：

请求方法：
- 若是GET请求，再看Accept请求头：
  - 如果Accept包含text/html（比如浏览器直接访问该端点时的默认头），则返回Sandbox的静态HTML页面；
  - 如果Accept是application/json或未明确指定（比如curl、Postman发起的GET查询），则解析URL参数里的query字段，执行GraphQL查询并返回JSON响应。
- 若是POST请求，不管Accept头是什么，都会直接进入GraphQL查询处理流程——这是GraphQL的标准请求方式。

协议：完全基于HTTP/HTTPS，没有引入特殊协议（订阅场景会升级到WebSocket，但那是额外逻辑，和Sandbox无关）。
请求方法：
- GET：承担两个角色——浏览器访问返回Sandbox调试界面；工具类请求通过URL参数传递查询内容执行请求。
- POST：标准GraphQL操作（查询、突变）的请求方式，也是Sandbox界面发起查询时用的方法。

请求体只在POST请求中发挥核心作用：

GET请求：通常不带请求体，GraphQL查询内容通过URL的query参数传递，比如：
```
GET /graphql?query={users{name,email}}
```
浏览器访问时则完全没有请求体，直接触发HTML页面返回。
POST请求：必须携带JSON格式的请求体，标准结构如下：
```
{
  "query": "query GetUser($id: ID!) { user(id: $id) { name email } }",
  "variables": { "id": "123" },
  "operationName": "GetUser"
}
```
Apollo Server会解析这个JSON体，提取查询语句、变量和操作名，执行对应的GraphQL逻辑后返回JSON格式的响应。

请求头是区分逻辑的关键，但不是唯一依据：

Accept头：仅在GET请求中决定返回内容类型——浏览器的Accept头包含text/html，触发Sandbox页面；工具类请求的Accept: application/json触发查询处理。
Content-Type头：POST请求必须设置为application/json（也支持application/graphql等格式，但JSON是行业标准），否则Apollo Server无法正确解析请求体。
其他头：比如Authorization用于身份验证，不管是Sandbox页面加载还是查询请求，都会被Apollo统一处理，不会影响端点逻辑的分支判断。

Sandbox本身是一个预编译的静态HTML页面，包含了Apollo的调试前端代码。当浏览器加载这个页面后，Sandbox会自动通过POST请求向同一个端点发送GraphQL查询——这时候服务器就会切换到查询处理器模式，和普通工具发起的请求没有区别。

你也可以通过Apollo Server的配置修改这个行为，比如关闭Sandbox、自定义端点路径，但默认逻辑就是上述的条件分支处理。

内容的提问来源于stack exchange，提问作者sebastian