API 设计 / 系统课时
定义标量、对象与字段
定义标量、对象与字段
设计 GraphQL Schema 的核心不是把数据库表逐字翻译成类型,而是用标量、对象和字段描述客户端真正能查询的业务模型。本节从一个用户与文章关系出发,说明内置标量、对象字段、列表和非空约束如何组合成可演进的 Schema。
学习目标
- 正确使用
String、Int、Float、Boolean、ID等内置标量。 - 用对象类型和字段表达业务实体以及实体之间的可遍历关系。
- 理解列表与非空修饰符的组合含义,避免给 Schema 加上错误承诺。
标量负责叶子值
GraphQL 查询最终必须落到标量或枚举等叶子值。内置标量中,String 表示文本,Boolean 表示真假,Int 是 32 位有符号整数,Float 表示双精度浮点数,ID 用于稳定标识符;ID 在序列化结果中通常表现为字符串,但语义上强调“标识”而不是普通文本。
日期时间、金额或 URL 这类领域值没有通用内置标量。可以声明自定义标量,例如 DateTime,但服务端仍需要为它实现序列化、解析变量和解析字面量的规则。
用对象和字段表达关系
下面的 SDL 把用户与文章定义为两个对象,并通过 User.posts 与 Post.author 暴露双向关系。Query.user 则提供从根查询进入业务图的入口。以下是片段示例,需要放入支持 GraphQL SDL 的服务端 Schema,并为自定义标量和字段提供对应实现。
scalar DateTime
type User {
id: ID!
name: String!
posts(limit: Int = 10): [Post!]!
}
type Post {
id: ID!
title: String!
publishedAt: DateTime!
author: User!
}
type Query {
user(id: ID!): User
}这里没有把数据库外键字段直接暴露为 authorId 供客户端二次查询,而是提供 author: User!。这正是 GraphQL 对象图的价值:客户端沿字段关系继续选择需要的数据,服务端 resolver 决定这些数据来自数据库、缓存还是远程服务。
读懂列表与非空约束
! 修饰它左侧的类型,列表则用方括号表示,因此 [Post!]! 同时表达两层约束:列表本身不能是 null,列表内部的每个 Post 也不能是 null。它仍然允许空列表 []。
User 与 User! 的差别也很重要。示例中的 Query.user(id: ID!): User 允许“没有找到这个用户”时返回 null;如果改成 User!,resolver 返回空值就会触发 GraphQL 的非空错误传播。非空不是“数据库里通常有值”的描述,而是 API 对客户端的稳定承诺。
用一次查询验证对象图
假设服务端已经为上述字段实现 resolver,可以用一条查询同时读取用户、文章以及文章作者,不需要客户端手工拼接多个 REST 请求。以下是片段示例,依赖前述 Schema 已部署且存在示例数据。
query UserWithPosts($id: ID!) {
user(id: $id) {
id
name
posts(limit: 2) {
id
title
author {
id
name
}
}
}
}变量:
{
"id": "u-1"
}预期结果示例:
{
"data": {
"user": {
"id": "u-1",
"name": "Ada",
"posts": [
{
"id": "p-101",
"title": "Schema Design",
"author": {
"id": "u-1",
"name": "Ada"
}
}
]
}
}
}实际 ID、名称和文章数量取决于数据源。验证重点不是这些具体值,而是字段形状必须与 Schema 一致:标量位于叶子节点,对象字段必须继续选择子字段,列表元素必须遵守其元素类型与非空约束。
给未来演进留下空间
对象字段应该围绕业务能力命名,而不是绑定当前存储结构。关系字段通常比暴露外键更适合作为公共 API;需要分页时,也不要长期依赖一个无界的 [Post!]!,而应进一步演进为带游标和分页信息的连接结构。先把类型边界和空值语义定义准确,后续新增字段通常可以保持向后兼容。