主题对照

GraphQL 模式、查询与执行

比较 GraphQL SDL 的类型、字段、输入约束、Query 与 Mutation,及选择集、片段、变量、解析器、错误和 HTTP 承载的执行边界。

43 张卡片 · 3 本书

本层 43 张卡片 · 含下级覆盖 43 张卡片

本主题的卡片

Microservice APIs · Designing and building GraphQL APIs

GraphQL按需查询字段

GraphQL 是面向 API 的查询语言,客户端可声明所需字段,并在一次请求中沿对象关系取得多个资源的部分数据。它适合客户端只需大对象少数字段或需组合关联数据的场景;是否减少传输量,还取决于查询设计与服务端实际返回内容。

查看卡片与原书出处

Microservice APIs · 8 Designing GraphQL APIs

SDL声明查询模式

GraphQL 模式用 Schema Definition Language(SDL)描述客户端可查询的数据类型及其字段,是接口的类型契约。查询执行时还需要服务端运行时解析字段;SDL 说明可请求什么,不自动提供数据。参见 [[GraphQL按需查询字段]]。

查看卡片与原书出处

Microservice APIs · 8 Designing GraphQL APIs

标量定义字段值类型

GraphQL 标量描述字段返回的基本值类型,内建 String、Int、Float、Boolean、ID。字段声明形如 name: String,让查询方知道值的类型边界。ID 表示标识值,并不能仅靠类型声明保证业务数据全局唯一;唯一性还需由数据模型和写入规则维护。

查看卡片与原书出处

Microservice APIs · 8 Designing GraphQL APIs

感叹号声明非空字段

GraphQL 字段类型后加 ! 表示该位置不能返回 null,例如 name: String!。这让客户端可按非空契约使用字段;服务端若无法满足约束,查询执行会产生错误并按模式规则处理结果,不能把 ! 当成自动补值机制。

查看卡片与原书出处

Microservice APIs · 8 Designing GraphQL APIs

对象类型组合资源字段

GraphQL 对象类型用 type 声明一个资源的字段集合,每个字段再标注标量或其他对象类型。例如 Cake 可列出名称、价格和可用状态。对象类型定义可查询结构;它与数据库表可相关,却不要求一张对象类型直接对应一张表。

查看卡片与原书出处

Microservice APIs · 8 Designing GraphQL APIs

自定义标量需实现行为

内建标量不足以表达日期时间等值时,可在 GraphQL SDL 中声明 scalar Datetime,再在服务端实现解析、校验和序列化。声明只给出类型名称,不会自动建立日期时间规则;具体格式和失败处理属于运行时契约。

查看卡片与原书出处

Microservice APIs · 8 Designing GraphQL APIs

列表与元素分别约束非空

GraphQL 列表用 [T] 表示;! 放在元素类型后约束元素非空,放在列表类型后约束列表本身非空。因此 [T!] 允许整个列表为 null,[T]! 允许列表含 null,[T!]! 两者都不允许。空列表 [] 仍满足所有这些非空约束。

查看卡片与原书出处

Microservice APIs · 8 Designing GraphQL APIs

边字段连接对象类型

GraphQL 对象字段可指向另一对象类型,形成从当前类型出发的可查询关系;例如原料的 supplier 指向供应商。关系默认沿字段声明方向可遍历,若要反向遍历,需在另一类型上也声明相应字段。边是 API 查询结构,不等同于数据库自动建立外键。

查看卡片与原书出处

Microservice APIs · 8 Designing GraphQL APIs

关系对象保存连接属性

两种对象的关系若本身带有数据,就可用中间对象类型描述连接,而非只列目标对象。例如产品配方连接原料时,还需保存数量和计量单位,IngredientRecipe 将这些属性与原料一起提供给查询方。参见 [[边字段连接对象类型]]。

查看卡片与原书出处

Microservice APIs · 8 Designing GraphQL APIs

接口与联合表达不同复用

GraphQL 接口规定多个对象类型必须共同提供的字段,适合需要统一查询共同属性时使用;联合类型把不同对象类型列为一种可能返回的集合,并不声明共同字段。蛋糕和饮料可实现相同产品接口,同时组成 Product 联合,以不同方式服务类型复用与多态查询。

查看卡片与原书出处

Microservice APIs · 8 Designing GraphQL APIs

枚举限制字段取值

GraphQL 枚举用 enum 声明有限的合法值,可让字段只接受约定选项。例如计量单位限定为升、千克或件,避免同一字段混入随意拼写。枚举适合稳定且可列举的集合;若值需要频繁由业务数据扩展,应先评估维护成本。

查看卡片与原书出处

Microservice APIs · 8 Designing GraphQL APIs

Query根类型组织读取

GraphQL 用 Query 根类型声明可读取的入口字段;每个字段可带参数并标注返回类型,例如按 ID 取一个对象或按条件取集合。参数让客户端表达过滤、排序与分页需求,字段选择再决定返回对象的具体数据。参见 [[GraphQL按需查询字段]]。

查看卡片与原书出处

Microservice APIs · 8 Designing GraphQL APIs

输入类型聚合操作参数

GraphQL 的 input 类型把一组查询或变更参数封装为可复用的输入结构,避免操作签名随过滤项增加而难读。输入类型专供请求参数使用,可设置字段类型、非空约束与默认值;设计创建和更新时,需分别检查哪些字段真正必填。

查看卡片与原书出处

Microservice APIs · 8 Designing GraphQL APIs

Mutation根类型组织变更

GraphQL 用 Mutation 根类型声明会改变服务端状态的操作,例如新增、更新或删除资源。每个变更字段同样有参数和返回类型,可把服务器生成的 ID 或更新后对象返回给客户端;它与仅读取数据的 [[Query根类型组织读取]] 分工明确。

查看卡片与原书出处

Microservice APIs · 9 Consuming GraphQL APIs

模拟服务先验证契约

模拟服务按 API 契约提供与真实服务相同的接口,并返回虚构数据。后端尚未实现时,客户端可据此开发和验证请求形状;模拟响应通常不持久化,不能把它的成功当作真实业务行为已正确实现。

查看卡片与原书出处

Microservice APIs · 9 Consuming GraphQL APIs

选择集明确返回字段

GraphQL 查询使用选择集列出希望返回的字段;对象字段还要继续选择其子字段。客户端由此控制结果的形状,遗漏必需的选择集会触发查询错误。

查看卡片与原书出处

Microservice APIs · 9 Consuming GraphQL APIs

响应分别承载数据与错误

GraphQL 响应以 data 承载查询结果,以 errors 数组承载错误;错误项可给出消息与查询文档位置。诊断时应读取错误位置和消息,而非只看 HTTP 请求是否完成;部分执行场景还可能同时出现数据与错误。

查看卡片与原书出处

Microservice APIs · 9 Consuming GraphQL APIs

内联片段按实际类型选字段

联合类型返回值可能落在不同对象类型上。内联片段用 ... on 类型 限定字段选择,让查询分别读取各具体类型的专属字段;若这些类型还实现同一接口,也可在接口片段中选共有字段。

查看卡片与原书出处

Microservice APIs · 9 Consuming GraphQL APIs

命名片段复用字段选择

命名片段把一组字段选择定义在指定类型上,查询通过片段展开复用。多处需要相同字段时,可集中维护这些选择,减少重复并保持查询主体易读;复用仍受片段类型条件约束。

查看卡片与原书出处

Microservice APIs · 9 Consuming GraphQL APIs

输入对象传递成组过滤条件

当查询参数定义为 GraphQL 输入类型时,调用方传入与该类型字段对应的输入对象,如 products(input: {maxPrice: 10})。对象内部字段遵循模式的类型与必填约束,便于把成组过滤条件作为一个参数传递。

查看卡片与原书出处

Microservice APIs · 9 Consuming GraphQL APIs

嵌套选择沿对象关系取值

GraphQL 对象字段指向另一对象时,查询要在该字段下继续写嵌套选择集。沿产品、配方原料、供应商的字段连接逐层选择,能在一次查询中取得相关对象的指定字段;实际成本仍取决于服务端解析方式。

查看卡片与原书出处

Microservice APIs · 9 Consuming GraphQL APIs

同一操作可请求多个根字段

一个 GraphQL 查询操作可以同时选择多个根字段,例如产品列表与原料列表,并在一次请求中获得各自结果。这样可减少网络往返;服务端解析成本及错误处理仍需分别观察。

查看卡片与原书出处

Microservice APIs · 9 Consuming GraphQL APIs

别名区分同字段不同参数

GraphQL 别名把响应字段写为 别名: 字段名。同一个根字段以不同参数读取两份数据时,需要不同响应名来避免字段冲突;别名也能让结果键更贴近客户端语义。

查看卡片与原书出处

Microservice APIs · 9 Consuming GraphQL APIs

字段参数用括号传入

GraphQL 字段参数写在字段名后的括号中,按 名称: 值 传入,例如 ingredient(id: "asdf")。模式声明为非空的参数不可省略;无参数字段省略括号,空括号会形成语法错误。调用前应对照模式确认参数名和类型。

查看卡片与原书出处

Microservice APIs · 9 Consuming GraphQL APIs

变更操作用mutation声明

GraphQL 变更操作以 mutation 声明意图,再调用模式中的变更字段。返回标量时直接选择字段;返回对象或联合类型时还须写选择集,并按可用类型选择字段。客户端应把改变服务器状态的调用与读取查询区分。

查看卡片与原书出处

Microservice APIs · 9 Consuming GraphQL APIs

变量把操作与参数值分开

GraphQL 操作可在名称后声明 $变量: 类型,字段参数引用该变量;具体值通过独立的 JSON 变量对象传入。这样能复用同一操作文档并避免把每次输入硬编码进查询文本,仍需符合声明的类型与非空约束。

查看卡片与原书出处

Microservice APIs · 9 Consuming GraphQL APIs

HTTP请求承载查询文档

GraphQL 查询文档可作为 HTTP 请求的数据发送:GET 通常将 query 放入 URL 参数并进行百分号编码,POST 可放入请求体。客户端需要按服务端支持的传输方式构造请求;变更操作应检查服务端对方法的约束。

查看卡片与原书出处

Microservice APIs · 10 Building GraphQL APIs with Python

先由模式列出实现职责

实现 GraphQL API 前,先从模式逐项列出对象类型、根查询、变更操作和返回类型。普通对象需产出符合字段约束的数据;联合类型还要能判定每个结果的具体类型。这样可把契约中的要求转为解析器和类型判定任务。

查看卡片与原书出处

Microservice APIs · 10 Building GraphQL APIs with Python

解析器提供字段实际值

GraphQL 解析器是为模式中的字段求值的函数。根查询或变更字段解析器从数据源取得结果,对象字段解析器再提供嵌套值;仅声明模式不会凭空产生业务数据。设计时应让解析器输出符合模式的值。

查看卡片与原书出处

Microservice APIs · 10 Building GraphQL APIs with Python

可执行模式绑定定义与解析器

模式文本经解析和校验后,需要与字段解析器的绑定一起组成可执行模式,GraphQL 服务才能按契约执行请求。若只加载类型定义而未绑定业务解析器,非空字段可能因无法提供值而报错。

查看卡片与原书出处
辅助阅读:卢曼编号

按卢曼编号阅读

点击箭头逐层展开,点击卡片标题查看详情。路径上下文仅用于连接层级,不计入主题卡片数。

未编号或编号待整理

来源书籍

来源书籍

Microservice APIs

系统架构类

Skill 版本:v11

书籍类型:工程实践

清单覆盖 6/7

238 张卡片

来源书籍

微服务实战

Skill 版本:v23

书籍类型:未标注

389 张卡片