GraphQL API设计终极指南：Shopify生产环境经验的23个黄金法则
【免费下载链接】graphql-design-tutorial项目地址: https://gitcode.com/gh_mirrors/gr/graphql-design-tutorial
GraphQL已成为现代API开发的首选技术之一，而Shopify作为全球领先的电子商务平台，在GraphQL API设计方面积累了宝贵的生产环境经验。本指南将分享Shopify团队总结的23个黄金法则，帮助你设计出高效、可扩展且用户友好的GraphQL API。无论你是刚开始接触GraphQL的新手，还是希望优化现有API的开发者，这些经过实战检验的原则都能为你的项目带来显著提升。
一、设计前期准备：奠定坚实基础
从宏观视角开始设计
在深入具体字段之前，先建立对象及其关系的高层视图至关重要。这类似于实体关系模型，但要结合GraphQL的特性。这种方法能帮助你避免过早陷入细节，确保整体架构的合理性。
Rule #1: 始终先从对象及其关系的高层视图开始，然后再处理具体字段。
隐藏实现细节
API的目的与实现不同，通常处于不同的抽象级别。实现细节（如数据库连接表）不应出现在API设计中。例如，Shopify在设计产品集合API时，避免暴露CollectionMembership这种实现层面的连接表，而是直接展示产品与集合的关系。
Rule #2: 永远不要在API设计中暴露实现细节。
围绕业务领域设计
API设计应基于业务领域，而非实现、用户界面或遗留API。Shopify的经验表明，即使是手动和自动集合这类在实现上有差异的概念，在API层面也应统一为Collection类型，因为它们的核心业务功能都是产品分组。
Rule #3: 围绕业务领域设计API，而非实现、用户界面或遗留API。
二、类型与字段设计：打造清晰的数据模型
遵循"宁缺毋滥"原则
添加字段比移除字段容易得多。GraphQL模式可以通过添加元素轻松演进，但更改或删除元素是破坏性的，难度大得多。因此，只在有实际需求和用例时才暴露模式元素。
Rule #4: 添加字段比移除字段更容易。
实现Node接口
大多数主要的可识别业务对象（如产品、集合等）应实现Node接口。这向客户端暗示该对象是持久化的，可通过给定ID检索，便于客户端准确高效地管理本地缓存。
interface Node { id: ID! } type Collection implements Node { id: ID! # 其他字段... }Rule #5: 主要业务对象类型应始终实现Node接口。
使用子对象组织相关字段
将密切相关的字段分组到子对象中，能提供清晰的语义指示并解决空值问题。例如，Shopify将集合规则相关的字段组合到CollectionRuleSet子对象中，既提高了可读性，又解决了手动集合中规则相关字段的空值问题。
Rule #6: 将密切相关的字段分组到子对象中。
合理处理列表分页
对于可能返回大量数据的列表字段，务必考虑分页。Shopify采用Relay Connection规范实现分页，确保API在处理大量数据时保持高效。
type ProductConnection { edges: [ProductEdge!]! pageInfo: PageInfo! } type ProductEdge { cursor: String! node: Product! } type PageInfo { hasNextPage: Boolean! hasPreviousPage: Boolean! }Rule #7: 始终检查列表字段是否应该分页。
使用对象引用而非ID字段
在REST API中常见的ID字段链接方式在GraphQL中是反模式。应直接包含对象引用，避免客户端进行额外的请求。例如，使用image: Image而非imageId: ID。
Rule #8: 始终使用对象引用而非ID字段。
精心命名并善用自定义标量
字段名称应基于语义而非实现或遗留API命名。同时，对于具有特定语义值的字段，使用自定义标量类型能提供更多上下文和语义信息。例如，使用HTML标量类型表示包含HTML内容的描述字段。
Rule #9: 基于语义选择字段名称，而非实现或遗留API中的名称。Rule #10: 当暴露具有特定语义值的内容时，使用自定义标量类型。
对固定值集使用枚举
对于只能取特定值集的字段，使用枚举类型能提高API的清晰度和类型安全性。例如，集合规则中的字段和关系类型适合用枚举表示。
enum CollectionRuleField { TAG TITLE TYPE INVENTORY PRICE VENDOR }Rule #11: 对只能取特定值集的字段使用枚举。
三、业务逻辑与数据提供：平衡功能与灵活性
提供业务逻辑而非仅数据
API应提供业务逻辑，而不仅仅是数据。复杂计算应在服务器上进行，确保单一数据源和逻辑一致性。例如，Shopify在集合API中提供hasProduct(id: ID!): Boolean!字段，避免客户端遍历所有产品来检查是否包含特定产品。
Rule #12: API应提供业务逻辑，而不仅仅是数据。复杂计算应在服务器上进行，集中一处，而非在多个客户端上实现。
同时提供原始数据
即使有相关的业务逻辑，也应提供原始数据。你无法预测客户端可能需要的所有逻辑，提供原始数据能确保客户端在需要时可以自行实现逻辑。
Rule #13: 即使有相关的业务逻辑，也要提供原始数据。
四、变更操作设计：确保安全与高效
为不同逻辑操作编写单独变更
不要将所有更新操作都塞进一个大型update变更中。将不同的逻辑操作拆分为单独的变更，如publish、unpublish、addProducts等，使服务器实现和客户端使用都更清晰。
Rule #14: 为资源的不同逻辑操作编写单独的变更。
谨慎处理关系变更
变更关系（如添加/删除产品到集合）是复杂的，没有简单的通用规则。需考虑关系大小、是否有序、是否强制以及双方是否有ID等因素，选择最适合的变更方式。
Rule #15: 变更关系非常复杂，无法简单概括为一个简洁的规则。
考虑批量操作
为关系变更编写单独变更时，考虑让变更支持同时操作多个元素，如addProducts而非addProduct，这能为客户端提供便利。
Rule #16: 为关系编写单独变更时，考虑让变更支持同时操作多个元素是否有用。
为变更命名添加对象前缀
为便于按字母顺序分组相关变更，使用对象名作为变更名称的前缀，如collectionDelete而非deleteCollection。
Rule #17: 为变更名称添加它们所变更的对象作为前缀，以便按字母顺序分组。
五、输入与输出设计：优化客户端体验
仅在语义上必需时才使输入字段为必填
输入字段的!表示"必填"，即客户端必须提供才能继续请求。仅在语义上确实需要时才将输入字段设为必填。
Rule #18: 仅在语义上确实需要变更继续时，才使输入字段为必填。
明智选择输入类型强度
当格式明确且客户端验证复杂时，使用较弱的输入类型（如String而非Email），让服务器处理所有非平凡验证。当格式可能模糊且客户端验证简单时，使用较强的类型（如DateTime而非String）。
Rule #19: 当格式明确且客户端验证复杂时，使用较弱的输入类型。这让服务器一次性运行所有非平凡验证，并以单一格式在单一位置返回错误，简化客户端。Rule #20: 当格式可能模糊且客户端验证简单时，使用较强的输入类型。这提供了清晰度，并鼓励客户端使用更严格的输入控件。
结构化输入以减少重复
即使需要放宽某些字段的必填性约束，也要结构化变更输入以减少重复。例如，为create和update变更使用相同的输入对象类型。
Rule #21: 结构化变更输入以减少重复，即使这需要放宽某些字段的必填性约束。
分离选择与变更数据参数
对于更新变更，选择条目和提供变更数据的参数必须分开。选择条目的参数应是非空的，除非有必要使其成为可选过滤器。
Rule #22: 对于更新变更，选择条目的参数必须与提供变更数据的参数分开。选择条目的参数应是非空的，除非有必要使其成为可选过滤器。
通过payload提供用户错误
变更应通过payload上的userErrors字段提供用户/业务级错误。顶层查询错误条目保留给客户端和服务器级错误。
type CollectionCreatePayload { userErrors: [UserError!]! collection: Collection } type UserError { message: String! field: [String!] }Rule #23: 变更应通过变更payload上的userErrors字段提供用户/业务级错误。顶层查询错误条目保留给客户端和服务器级错误。
总结
Shopify的这23条GraphQL API设计黄金法则，是基于近三年生产环境模式创建和演进的经验总结。它们并非教条，而是在大多数情况下有效的设计指南。记住，最好的API设计需要迭代、实验和对业务领域的深入理解。通过应用这些原则，你将能够构建出更强大、更灵活且更易于使用的GraphQL API，为你的用户提供出色的开发体验。
要开始使用这些原则，可以先克隆项目仓库：git clone https://gitcode.com/gh_mirrors/gr/graphql-design-tutorial，然后根据教程实践这些设计理念，打造属于你自己的高质量GraphQL API。
【免费下载链接】graphql-design-tutorial项目地址: https://gitcode.com/gh_mirrors/gr/graphql-design-tutorial
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
