graphql-schema

GraphQL 模式设计指南

本指南介绍如何设计直观、高性能且易于维护的 GraphQL 模式最佳实践。模式设计主要是服务端的工作，会直接影响 API 的易用性。

模式设计原则

1. 面向客户端需求进行设计

• 考虑客户端会编写哪些查询
• 围绕用例组织类型，而不是围绕数据库表
• 暴露功能，而不是实现细节

2. 明确表达

• 使用清晰、描述性强的名称
• 有意设置可空性
• 添加描述文档

3. 面向演进进行设计

• 规划向后兼容性
• 移除字段前先弃用
• 避免破坏性更改
• 为每个新增参数或输入字段设置默认值，或将其设为可空。现有客户端不会发送这些字段，因此没有默认值的必填字段会导致其请求无法通过验证。

快速参考

类型定义语法

"""
A user in the system.
"""
type User {
  id: ID!
  email: String!
  name: String
  posts(first: Int = 10, after: String): PostConnection!
  createdAt: DateTime!
}

可空性规则

模式	含义
String	可空——可能为 null
String!	非空——始终有值
[String]	可空列表，元素可空
[String!]	可空列表，元素非空
[String]!	非空列表，元素可空
[String!]!	非空列表，元素非空

最佳实践： 列表使用 [Type!]!——空列表优于 null，且不包含 null 元素。

输入类型与输出类型

# Output type - what clients receive
type User {
  id: ID!
  email: String!
  createdAt: DateTime!
}

# Input type - what clients send
input CreateUserInput {
  email: String!
  name: String
}

# Mutation using input type
type Mutation {
  createUser(input: CreateUserInput!): User!
}

接口模式

interface Node {
  id: ID!
}

type User implements Node {
  id: ID!
  email: String!
}

type Post implements Node {
  id: ID!
  title: String!
}

联合类型模式

union SearchResult = User | Post | Comment

type Query {
  search(query: String!): [SearchResult!]!
}

参考文件

特定主题的详细文档：

• 类型 - 类型设计模式、接口、联合类型和自定义标量
• 命名 - 类型、字段和参数的命名约定
• 分页 - 连接模式和基于游标的分页
• 错误 - 错误建模和结果类型
• 安全 - 模式设计的安全最佳实践

关键规则

类型设计

• 根据领域概念定义类型，而不是根据数据存储方式
• 使用接口表示多个类型共有的字段
• 使用联合类型表示互斥类型
• 保持类型专注（单一职责）
• 避免深层嵌套——尽可能扁平化

字段设计

• 字段名称应从客户端视角出发
• 返回尽可能具体的类型
• 明确标示开销较大的字段（考虑使用参数）
• 使用参数进行筛选、排序和分页

变更设计

• 使用单一输入参数模式：mutation(input: InputType!)
• 在变更响应中返回受影响的对象
• 围绕业务操作建模变更，而不是围绕 CRUD
• 考虑返回成功／错误类型的联合类型

ID 策略

• 尽可能使用全局唯一 ID
• 实现 Node 接口以支持重新获取
• 如有需要，对复合 ID 进行 Base64 编码

基本规则

• 始终为类型和字段添加描述
• 对不可为 null 的字段始终使用非空标记（!）
• 列表始终使用 [Type!]! 模式
• 对可能无限增长的列表始终进行分页，例如 Query.users 或 Post.comments：返回一个连接，并为 first 设置默认页面大小
• 切勿在模式中暴露数据库内部细节
• 未弃用前，切勿破坏向后兼容性
• 切勿添加没有默认值的必填参数或输入字段
• 优先使用专用输入类型，而不是大量参数
• 对固定值优先使用枚举，而不是任意字符串
• 标识符使用 ID 类型，而不是 String 或 Int
• 对领域专用值使用自定义标量（DateTime、Email、URL）