GraphQL按需查询字段
GraphQL 是面向 API 的查询语言,客户端可声明所需字段,并在一次请求中沿对象关系取得多个资源的部分数据。它适合客户端只需大对象少数字段或需组合关联数据的场景;是否减少传输量,还取决于查询设计与服务端实际返回内容。
主题对照
比较 GraphQL SDL 的类型、字段、输入约束、Query 与 Mutation,及选择集、片段、变量、解析器、错误和 HTTP 承载的执行边界。
GraphQL 是面向 API 的查询语言,客户端可声明所需字段,并在一次请求中沿对象关系取得多个资源的部分数据。它适合客户端只需大对象少数字段或需组合关联数据的场景;是否减少传输量,还取决于查询设计与服务端实际返回内容。
GraphQL 模式用 Schema Definition Language(SDL)描述客户端可查询的数据类型及其字段,是接口的类型契约。查询执行时还需要服务端运行时解析字段;SDL 说明可请求什么,不自动提供数据。参见 [[GraphQL按需查询字段]]。
GraphQL 标量描述字段返回的基本值类型,内建 String、Int、Float、Boolean、ID。字段声明形如 name: String,让查询方知道值的类型边界。ID 表示标识值,并不能仅靠类型声明保证业务数据全局唯一;唯一性还需由数据模型和写入规则维护。
GraphQL 字段类型后加 ! 表示该位置不能返回 null,例如 name: String!。这让客户端可按非空契约使用字段;服务端若无法满足约束,查询执行会产生错误并按模式规则处理结果,不能把 ! 当成自动补值机制。
GraphQL 对象类型用 type 声明一个资源的字段集合,每个字段再标注标量或其他对象类型。例如 Cake 可列出名称、价格和可用状态。对象类型定义可查询结构;它与数据库表可相关,却不要求一张对象类型直接对应一张表。
内建标量不足以表达日期时间等值时,可在 GraphQL SDL 中声明 scalar Datetime,再在服务端实现解析、校验和序列化。声明只给出类型名称,不会自动建立日期时间规则;具体格式和失败处理属于运行时契约。
GraphQL 列表用 [T] 表示;! 放在元素类型后约束元素非空,放在列表类型后约束列表本身非空。因此 [T!] 允许整个列表为 null,[T]! 允许列表含 null,[T!]! 两者都不允许。空列表 [] 仍满足所有这些非空约束。
GraphQL 对象字段可指向另一对象类型,形成从当前类型出发的可查询关系;例如原料的 supplier 指向供应商。关系默认沿字段声明方向可遍历,若要反向遍历,需在另一类型上也声明相应字段。边是 API 查询结构,不等同于数据库自动建立外键。
两种对象的关系若本身带有数据,就可用中间对象类型描述连接,而非只列目标对象。例如产品配方连接原料时,还需保存数量和计量单位,IngredientRecipe 将这些属性与原料一起提供给查询方。参见 [[边字段连接对象类型]]。
GraphQL 接口规定多个对象类型必须共同提供的字段,适合需要统一查询共同属性时使用;联合类型把不同对象类型列为一种可能返回的集合,并不声明共同字段。蛋糕和饮料可实现相同产品接口,同时组成 Product 联合,以不同方式服务类型复用与多态查询。
GraphQL 枚举用 enum 声明有限的合法值,可让字段只接受约定选项。例如计量单位限定为升、千克或件,避免同一字段混入随意拼写。枚举适合稳定且可列举的集合;若值需要频繁由业务数据扩展,应先评估维护成本。
GraphQL 用 Query 根类型声明可读取的入口字段;每个字段可带参数并标注返回类型,例如按 ID 取一个对象或按条件取集合。参数让客户端表达过滤、排序与分页需求,字段选择再决定返回对象的具体数据。参见 [[GraphQL按需查询字段]]。
GraphQL 的 input 类型把一组查询或变更参数封装为可复用的输入结构,避免操作签名随过滤项增加而难读。输入类型专供请求参数使用,可设置字段类型、非空约束与默认值;设计创建和更新时,需分别检查哪些字段真正必填。
GraphQL 用 Mutation 根类型声明会改变服务端状态的操作,例如新增、更新或删除资源。每个变更字段同样有参数和返回类型,可把服务器生成的 ID 或更新后对象返回给客户端;它与仅读取数据的 [[Query根类型组织读取]] 分工明确。
模拟服务按 API 契约提供与真实服务相同的接口,并返回虚构数据。后端尚未实现时,客户端可据此开发和验证请求形状;模拟响应通常不持久化,不能把它的成功当作真实业务行为已正确实现。
GraphQL 查询使用选择集列出希望返回的字段;对象字段还要继续选择其子字段。客户端由此控制结果的形状,遗漏必需的选择集会触发查询错误。
GraphQL 响应以 data 承载查询结果,以 errors 数组承载错误;错误项可给出消息与查询文档位置。诊断时应读取错误位置和消息,而非只看 HTTP 请求是否完成;部分执行场景还可能同时出现数据与错误。
联合类型返回值可能落在不同对象类型上。内联片段用 ... on 类型 限定字段选择,让查询分别读取各具体类型的专属字段;若这些类型还实现同一接口,也可在接口片段中选共有字段。
命名片段把一组字段选择定义在指定类型上,查询通过片段展开复用。多处需要相同字段时,可集中维护这些选择,减少重复并保持查询主体易读;复用仍受片段类型条件约束。
当查询参数定义为 GraphQL 输入类型时,调用方传入与该类型字段对应的输入对象,如 products(input: {maxPrice: 10})。对象内部字段遵循模式的类型与必填约束,便于把成组过滤条件作为一个参数传递。
GraphQL 对象字段指向另一对象时,查询要在该字段下继续写嵌套选择集。沿产品、配方原料、供应商的字段连接逐层选择,能在一次查询中取得相关对象的指定字段;实际成本仍取决于服务端解析方式。
一个 GraphQL 查询操作可以同时选择多个根字段,例如产品列表与原料列表,并在一次请求中获得各自结果。这样可减少网络往返;服务端解析成本及错误处理仍需分别观察。
GraphQL 别名把响应字段写为 别名: 字段名。同一个根字段以不同参数读取两份数据时,需要不同响应名来避免字段冲突;别名也能让结果键更贴近客户端语义。
GraphQL 字段参数写在字段名后的括号中,按 名称: 值 传入,例如 ingredient(id: "asdf")。模式声明为非空的参数不可省略;无参数字段省略括号,空括号会形成语法错误。调用前应对照模式确认参数名和类型。
GraphQL 变更操作以 mutation 声明意图,再调用模式中的变更字段。返回标量时直接选择字段;返回对象或联合类型时还须写选择集,并按可用类型选择字段。客户端应把改变服务器状态的调用与读取查询区分。
GraphQL 操作可在名称后声明 $变量: 类型,字段参数引用该变量;具体值通过独立的 JSON 变量对象传入。这样能复用同一操作文档并避免把每次输入硬编码进查询文本,仍需符合声明的类型与非空约束。
GraphQL 查询文档可作为 HTTP 请求的数据发送:GET 通常将 query 放入 URL 参数并进行百分号编码,POST 可放入请求体。客户端需要按服务端支持的传输方式构造请求;变更操作应检查服务端对方法的约束。
实现 GraphQL API 前,先从模式逐项列出对象类型、根查询、变更操作和返回类型。普通对象需产出符合字段约束的数据;联合类型还要能判定每个结果的具体类型。这样可把契约中的要求转为解析器和类型判定任务。
GraphQL 解析器是为模式中的字段求值的函数。根查询或变更字段解析器从数据源取得结果,对象字段解析器再提供嵌套值;仅声明模式不会凭空产生业务数据。设计时应让解析器输出符合模式的值。
模式文本经解析和校验后,需要与字段解析器的绑定一起组成可执行模式,GraphQL 服务才能按契约执行请求。若只加载类型定义而未绑定业务解析器,非空字段可能因无法提供值而报错。
点击箭头逐层展开,点击卡片标题查看详情。路径上下文仅用于连接层级,不计入主题卡片数。
来源书籍
系统架构类
书籍类型:工程实践
清单覆盖 6/7
238 张卡片
来源书籍
书籍类型:未标注
47 张卡片
来源书籍
书籍类型:未标注
389 张卡片