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,并为自定义标量和字段提供对应实现。

graphql
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 已部署且存在示例数据。

graphql
query UserWithPosts($id: ID!) {
  user(id: $id) {
    id
    name
    posts(limit: 2) {
      id
      title
      author {
        id
        name
      }
    }
  }
}

变量:

json
{
  "id": "u-1"
}

预期结果示例:

json
{
  "data": {
    "user": {
      "id": "u-1",
      "name": "Ada",
      "posts": [
        {
          "id": "p-101",
          "title": "Schema Design",
          "author": {
            "id": "u-1",
            "name": "Ada"
          }
        }
      ]
    }
  }
}

实际 ID、名称和文章数量取决于数据源。验证重点不是这些具体值,而是字段形状必须与 Schema 一致:标量位于叶子节点,对象字段必须继续选择子字段,列表元素必须遵守其元素类型与非空约束。

给未来演进留下空间

对象字段应该围绕业务能力命名,而不是绑定当前存储结构。关系字段通常比暴露外键更适合作为公共 API;需要分页时,也不要长期依赖一个无界的 [Post!]!,而应进一步演进为带游标和分页信息的连接结构。先把类型边界和空值语义定义准确,后续新增字段通常可以保持向后兼容。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

定义标量、对象与字段

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通