UD5工具箱
常见问题解答
GraphQL 是什么？它与 REST API 有什么区别？
GraphQL 是一种 API 查询语言，允许客户端精确指定需要的数据结构。与 REST API 的主要区别包括：REST 使用多个端点（如 /users、/posts、/comments），每个端点返回固定的数据结构；GraphQL 使用单一端点（通常是 /graphql），客户端通过查询语句描述所需的数据。REST 容易出现过度获取（返回了不需要的字段）或不足获取（需要多次请求才能获取所有数据）；GraphQL 按需获取，一次请求获取所有需要的数据。REST 的版本管理通常通过 URL 路径（如 /v1/users、/v2/users）；GraphQL 通过 Schema 的演进来管理 API 变化，无需版本号。REST 使用 HTTP 方法区分操作（GET/POST/PUT/DELETE）；GraphQL 统一使用 POST 方法，通过操作类型（Query/Mutation/Subscription）区分。
如何为需要认证的 API 添加 Token？
切换到编辑器下方的 Headers 标签页，在 Header Name 列输入认证头的名称（通常是 Authorization），在 Value 列输入认证值。常见的认证方式有：Bearer Token 认证，Value 格式为 Bearer your-jwt-token-here；API Key 认证，Header Name 为自定义名称（如 X-API-Key），Value 为你的 API 密钥；Basic Auth 认证，Header Name 为 Authorization，Value 格式为 Basic base64-encoded-credentials。添加的请求头会随每次查询一起发送到 GraphQL 服务器。注意不要在公共环境或分享截图中暴露真实的 Token 值。
遇到 CORS 错误怎么办？
CORS（跨源资源共享）错误是由于浏览器的安全策略限制。当从一个域名（如本工具页面）向另一个域名的 GraphQL 服务器发送请求时，如果服务器没有配置允许跨域访问，浏览器会阻止请求。解决方法需要在 GraphQL 服务器端配置：添加 Access-Control-Allow-Origin 头允许你的域名或 *；对于需要认证的请求，还需要配置 Access-Control-Allow-Headers 允许 Authorization 等自定义头；对于 OPTIONS 预检请求，服务器需要正确响应。如果你无法修改服务器配置，可以考虑使用浏览器 CORS 插件临时禁用安全策略（仅用于开发调试），或者通过本地代理服务器转发请求。
GraphQL 变量是如何定义和使用的？
GraphQL 变量允许将查询中的硬编码值替换为动态参数。定义变量分为两步：第一步，在查询操作名后面用括号定义变量声明，格式为 $variableName: Type!（感叹号表示必填），例如 query GetUser($id: ID!) { user(id: $id) { name email } }。第二步，切换到 Variables 标签页，以 JSON 格式输入变量的值，例如 { "id": "123" }。变量类型可以是 Scalar（String、Int、Float、Boolean、ID）、Enum、Input Object 或这些类型的列表。变量机制使得同一个查询可以复用于不同的参数，提高了代码的可维护性和安全性（避免了字符串拼接导致的注入风险）。
什么是 Schema 内省（Introspection）？
Schema 内省（Introspection）是 GraphQL 的内置能力，允许客户端通过查询来获取 Schema 本身的定义信息。通过执行特殊的 __schema 查询，可以获取所有类型定义、字段列表、参数信息和描述文本。GraphiQL 的文档浏览器正是利用 Introspection 查询自动获取服务器的 Schema 并生成交互式文档。你可以手动执行 Introspection 查询：{ __schema { queryType { name } types { name kind description fields { name type { name kind } } } } }。出于安全考虑，生产环境中的 GraphQL 服务器可能会禁用 Introspection，以防止未授权的 Schema 发现。在这种情况下，文档浏览器将无法自动加载 Schema 信息。
本工具支持哪些快捷键？
本工具支持以下快捷键来提升开发效率：Ctrl+Enter（在 Windows/Linux 上）或 Cmd+Enter（在 Mac 上）执行当前查询；Ctrl+Shift+F 或 Cmd+Shift+F 美化（格式化）当前查询代码；Ctrl+S 或 Cmd+S 手动保存当前查询到历史记录；Ctrl+Z 撤销编辑器中的修改；Ctrl+Shift+Z 或 Ctrl+Y 重做修改；Tab 在编辑器中插入缩进；Ctrl+A 全选编辑器内容。这些快捷键遵循了开发者熟悉的 IDE 操作模式，可以显著提升 GraphQL 查询的编写效率。
查询执行后没有返回数据是什么原因？
查询没有返回数据可能有以下几种原因：第一，服务器端返回了错误，检查结果面板中是否有 errors 字段，其中包含了服务器的错误描述。第二，查询的字段路径不正确，GraphQL 要求字段路径与 Schema 定义完全匹配，任何拼写错误都会导致空结果。第三，参数值类型不匹配，例如将字符串传递给了需要 ID 类型的参数。第四，认证失败，如果 API 需要认证，请确认 Headers 标签页中配置了正确的 Token。第五，网络连接问题，确认端点 URL 正确且服务器可访问。第六，CORS 限制，服务器未配置允许跨域请求。建议先通过文档浏览器确认查询的字段和参数是否正确，然后逐步排查上述问题。