UD5工具箱
什么是 GraphQL Schema 类型图谱？
GraphQL Schema 类型图谱是一种通过可视化图形方式展示 Schema 中各个类型及其关联关系的工具。图谱中的节点表示 Schema 中定义的各种类型（包括对象类型、接口、联合、枚举、输入类型和标量），连线表示类型之间的字段引用、接口实现或联合成员关系。通过这种直观的图形化展示，开发者无需逐行阅读 SDL 代码，就能快速理解整个 API 的数据结构全貌，特别适合分析包含大量类型的复杂 Schema。图谱的颜色编码系统进一步增强了信息的可读性，使开发者能够在大型图谱中快速定位感兴趣的类型。
本工具支持哪些 GraphQL 类型定义？
本工具解析标准的 GraphQL SDL（Schema Definition Language），完整支持以下类型定义方式：type 用于定义返回数据的结构；interface 用于定义可复用的字段规范；union 用于定义多种可能的返回类型；enum 用于定义有限的常量值集合；input 用于定义 mutation 参数的数据结构；scalar 用于定义原子值类型。同时支持 implements 继承关系、字段类型引用和联合成员关系等所有标准的类型关联方式。无论您的 Schema 使用了哪种类型的组合方式，本工具都能正确解析并生成对应的关系图谱。
图谱中的颜色代表什么含义？
本工具采用直观的颜色编码系统来区分不同类型的 GraphQL 定义：蓝色节点表示对象类型（Object Type），这是最常见的类型定义方式，通常用于表示 API 返回的数据实体；绿色节点表示接口（Interface），用于定义可被其他类型实现的字段规范；橙色节点表示联合类型（Union），表示一个字段可能返回的多种类型之一；紫色节点表示枚举类型（Enum），定义一组命名常量值，如状态码或类型分类；红色节点表示输入类型（Input Type），专门用于 mutation 操作的参数定义；灰色节点表示标量类型（Scalar），代表不可再分的原子值。这种一致的配色方案帮助您在浏览复杂的大型图谱时快速定位和区分各类节点。
如何从后端 GraphQL 服务获取 Schema？
通常有以下几种方式获取 Schema 的 SDL 内容：第一种方式是使用 get-graphql-schema 命令行工具，指定服务端点即可自动下载完整的 SDL，例如执行 get-graphql-schema https://api.example.com/graphql > schema.graphql 即可将 Schema 保存为文件；第二种方式是使用 GraphQL Playground 或 Apollo Studio 等开发工具连接到服务端点，通过内省查询（Introspection Query）获取 Schema 并导出为 SDL 格式；第三种方式是直接从项目代码库中复制 .graphql 或 .gql 格式的 Schema 文件内容；第四种方式是从服务器配置或构建脚本中获取 Schema 定义，例如在使用 Apollo Server 或 Hasura 等框架时通常会有对应的 Schema 生成步骤。获取到 SDL 文本后，将其粘贴到本工具的输入框中即可生成关系图谱。
图谱支持导出为图片或 SVG 吗？
当前版本的工具主要提供交互式浏览功能。要保存图谱，您可以使用浏览器或操作系统的截图功能将图谱保存为图片文件。在截图前，建议调整缩放比例和视图位置，确保需要展示的区域完整呈现在截图范围内。对于需要嵌入到文档或演示中的场景，截图是最简单直接的方式。我们计划在未来版本中添加内置的 PNG 和 SVG 导出功能，届时用户可以直接通过工具界面一键导出高质量的图谱文件，无需依赖外部截图工具。SVG 格式的导出将特别适合需要无损缩放的印刷场景。
我的 Schema 数据是否会被上传到服务器？
完全不会。本工具的所有数据处理均在您的浏览器本地完成，包括 SDL 文本解析、类型关系图谱构建和交互式浏览等全部功能。您粘贴到输入框中的 Schema 内容不会通过任何形式发送到任何远程服务器。这种本地优先的设计理念确保了企业级项目中 Schema 定义的机密性和数据安全。即使您的 Schema 中包含内部业务逻辑、敏感字段命名或未公开的 API 结构信息，也可以放心地使用本工具进行分析，因为所有数据始终留在您的设备上。
工具对 Schema 的大小有限制吗？
本工具对 Schema 的大小没有硬性的字符数限制，但图谱的渲染性能取决于 Schema 中类型和字段的数量。对于包含数百个类型定义的大型 Schema，浏览器可能需要较长时间来计算布局和渲染图谱。建议在分析超大 Schema 时，可以先提取其中的核心部分（例如仅包含主要查询和变更类型及其直接依赖的类型）进行可视化，以获得更好的浏览体验。如果遇到性能问题，尝试减少 SDL 输入中的类型数量或关闭其他占用系统资源的应用程序。一般来说，包含 50 到 100 个类型定义的 Schema 能够在大多数现代浏览器中流畅运行。
生成的图谱可以调整布局吗？
图谱生成时会使用自动布局算法计算节点位置，旨在减少连线交叉并呈现清晰的层次结构。生成后，您可以通过鼠标操作调整视图：使用滚轮缩放来查看全局概览或聚焦局部细节，按住鼠标左键拖拽来平移视图。点击任意节点可以在详情面板中查看该类型的完整字段定义。定位功能支持通过类型名称搜索快速跳转到特定节点，避免在大型图谱中手动查找。目前尚不支持自定义节点位置或切换不同的布局算法，但我们计划在未来版本中引入更多布局选项，如层次布局、圆形布局和力导向布局等。
如何理解图谱中连线的方向和含义？
图谱中的连线表示类型之间的依赖和关联关系。当某个类型的字段引用了另一个类型时，连线从字段所属类型指向被引用的类型，表示数据流动或依赖方向。例如如果 User 类型有一个 posts 字段返回 [Post] 类型，那么就会有一条从 User 到 Post 的连线。implements 关系的连线表示接口实现方向，从实现接口的具体类型指向接口定义。联合类型的连线将联合类型与其所有成员类型连接起来。通过观察连线的密度和方向，您可以快速判断 Schema 中哪些类型是核心枢纽（被大量引用），哪些类型是边缘终端（不被其他类型引用），这对于评估 Schema 的设计质量非常有帮助。
支持自定义标量类型吗？
是的，本工具完整支持自定义标量类型（Custom Scalar）。在 GraphQL 中，开发者可以通过 scalar 关键字定义自定义标量类型来表示特殊的业务数据格式，例如 scalar DateTime 表示日期时间、scalar JSON 表示任意 JSON 数据、scalar URL 表示网址等。这些自定义标量在图谱中以灰色节点呈现。虽然图谱无法展示自定义标量的内部序列化逻辑，但它会清晰地标注哪些字段使用了自定义标量类型，帮助您了解 Schema 中特殊数据格式的分布情况。这对于评估 Schema 的复杂度和规划客户端数据解析逻辑非常实用。