UD5工具箱
核心概念与术语详解
GraphQL
GraphQL 是一种用于 API 的查询语言和运行时，由 Facebook 于 2012 年内部开发，2015 年开源。与 REST API 不同，GraphQL 使用单一端点处理所有请求，客户端通过查询语言精确描述需要的数据结构。GraphQL 的核心优势包括：客户端按需获取数据，避免过度获取和不足获取；强类型系统，每个字段都有明确的类型定义；一次请求获取多个资源的数据，减少网络往返；内置的 Schema 自省机制，支持动态发现 API 能力。GraphQL 支持三种操作类型：Query（查询读取数据）、Mutation（变更修改数据）、Subscription（订阅实时数据推送）。
Schema（模式定义语言 - SDL）
GraphQL Schema 定义了 API 的类型系统和能力。Schema 使用 Schema Definition Language（SDL）编写，包含 Query、Mutation 和 Subscription 三种根类型。每个类型定义了若干字段，字段有明确的名称、参数和返回类型。Scalar 类型是基础数据类型（String、Int、Float、Boolean、ID），Object 类型由多个字段组成，Interface 和 Union 定义了多态类型，Enum 定义了枚举值，Input 类型用于 Mutation 的输入参数。Schema 是客户端和服务器之间的契约，确保了类型安全和数据一致性。
Query（查询）
Query 是 GraphQL 中用于读取数据的操作类型。查询的结构决定了返回数据的结构——客户端可以精确指定需要哪些字段、如何筛选、如何排序。例如 { users { name email posts { title } } } 会返回所有用户及其文章标题。查询支持嵌套字段、参数、别名（alias）、片段（fragment）和指令（directive）等高级特性。Query 是只读操作，不会修改服务器端的数据。
Mutation（变更）
Mutation 是 GraphQL 中用于修改数据的操作类型。与 Query 类似，Mutation 也可以指定返回字段，用于获取修改后的数据。Mutation 通常按照顺序执行（而非并行），确保操作之间的依赖关系。例如 mutation { updateUser(id: "1", input: { name: "New Name" }) { id name updatedAt } }。Mutation 的输入参数通常使用 Input 类型定义，支持嵌套和列表。
Subscription（订阅）
Subscription 是 GraphQL 中用于实时数据推送的操作类型。与 Query 和 Mutation 不同，Subscription 建立长连接（通常使用 WebSocket），当服务器端数据发生变化时自动推送更新到客户端。常用于实时聊天、通知推送、协作编辑等场景。Subscription 的查询语法与 Query 相同，但返回的是事件触发时的数据流。在本工具中，由于浏览器端的限制，Subscription 的支持可能因服务器配置而异。
Resolver（解析器）
Resolver 是服务器端负责解析和返回每个字段数据的函数。当客户端请求某个字段时，GraphQL 引擎会调用对应的 Resolver 函数来获取数据。Resolver 可以来自数据库查询、REST API 调用、内存计算或任何其他数据源。Resolver 函数通常接收四个参数：parent（父字段的解析结果）、args（字段参数）、context（请求上下文，如认证信息）和 info（查询的元信息）。灵活的 Resolver 机制使得 GraphQL 可以聚合来自不同数据源的数据。
Introspection（内省）
Introspection 是 GraphQL 的内置能力，允许客户端查询 Schema 本身的定义信息。通过特殊的 __schema 和 __type 查询，可以获取所有类型、字段、参数和描述信息。这正是 GraphiQL 文档浏览器的底层机制——它通过 Introspection 查询自动获取 Schema 定义并生成交互式文档。Introspection 在生产环境中可能被出于安全原因禁用。查询 Schema 的示例：{ __schema { types { name kind } } }。
Fragment（片段）
Fragment 是 GraphQL 中用于复用查询片段的机制。通过定义 Fragment 可以避免在多个查询中重复编写相同的字段选择集。例如：fragment UserFields on User { name email avatar }，然后在查询中使用 { users { ...UserFields } }。Fragment 支持条件应用（使用 @include 和 @skip 指令），可以根据变量动态决定是否包含某些字段。Fragment 是构建大型、可维护的 GraphQL 查询的重要工具。
Alias（别名）
Alias 允许在一次查询中多次请求同一个字段但使用不同的参数，并为每次请求指定不同的名称。例如：{ smallPic: profile Pic(size: 100) largePic: profile Pic(size: 500) }。如果不使用别名，两次请求同名字段会导致冲突。别名使得一次查询可以获取同一字段的不同视图，减少了请求次数，提高了效率。