GraphQL Yoga 入门指南：构建你的第一个GraphQL Schema

前言

GraphQL作为一种现代化的API查询语言，正在改变我们构建和使用API的方式。本文将基于GraphQL Yoga项目，带你从零开始构建一个完整的GraphQL Schema，并理解其核心概念和工作原理。

GraphQL基础概念回顾

在深入实践之前，让我们先快速回顾几个关键概念：

1. Schema：GraphQL的类型系统，定义了API的能力边界
2. 类型(Type)：GraphQL中的基本构建块，包括标量类型和对象类型
3. 查询(Query)：数据获取操作
4. 变更(Mutation)：数据修改操作
5. 订阅(Subscription)：实时数据推送操作
6. 解析器(Resolver)：实现每个字段具体逻辑的函数

环境准备

首先需要安装必要的依赖包：

npm install graphql@16.10.0 graphql-yoga@5.10.4

这里我们安装了两个核心包：

• graphql：GraphQL的JavaScript实现
• graphql-yoga：一个功能齐全的GraphQL服务器实现

构建第一个GraphQL Schema

1. 定义类型

我们从一个简单的"Hello World"示例开始。创建src/schema.ts文件：

const typeDefinitions = /* GraphQL */ `
  type Query {
    hello: String!
  }
`

这段代码定义了一个查询类型(Query)，其中包含一个hello字段，返回一个非空的字符串。

2. 实现解析器

解析器是实际执行业务逻辑的函数：

const resolvers = {
  Query: {
    hello: () => 'Hello World!'
  }
}

解析器对象的结构与类型定义相对应，Query类型下的每个字段都有一个对应的函数实现。

3. 组合Schema

使用createSchema将类型定义和解析器组合起来：

import { createSchema } from 'graphql-yoga'

export const schema = createSchema({
  resolvers: [resolvers],
  typeDefs: [typeDefinitions]
})

执行GraphQL查询

现在我们有了一个可执行的Schema，可以编写查询来测试它：

import { execute, parse } from 'graphql'
import { schema } from './schema'

async function main() {
  const myQuery = parse(/* GraphQL */ `
    query {
      hello
    }
  `)

  const result = await execute({
    schema,
    document: myQuery
  })

  console.log(result)
}

main()

执行这段代码，你将看到输出：

{ data: { hello: 'Hello World' } }

深入理解Schema

查询执行流程

1. 解析查询：将GraphQL查询字符串转换为抽象语法树(AST)
2. 验证查询：检查查询是否符合Schema定义
3. 执行查询：调用相应的解析器函数获取数据
4. 返回结果：将数据组装成响应格式

Schema设计进阶

让我们看一个更复杂的例子：

type Query {
  users: [User!]!
  user(id: ID!): User
}

type Mutation {
  createUser(name: String!): User!
}

type User {
  id: ID!
  name: String!
}

这个Schema定义了：

• 获取所有用户的查询
• 通过ID获取单个用户的查询
• 创建新用户的变更操作
• User类型及其字段

对应的查询示例：

query {
  users {
    id
    name
  }
  user(id: "1") {
    name
  }
}

mutation {
  createUser(name: "Alice") {
    id
    name
  }
}

类型修饰符详解

GraphQL中的类型可以使用修饰符来增强表达能力：

1. String!：非空字符串
2. [User]：User类型的列表，可以为空
3. [User!]!：非空列表，且列表中的元素也不能为null

理解这些修饰符对于设计健壮的API非常重要。

构建Schema的多种方式

除了本文展示的SDL（Schema Definition Language）方式外，GraphQL Yoga还支持多种构建Schema的方法：

1. 代码优先(Code-first)：直接在代码中定义类型
2. 注释驱动：通过代码注释生成Schema
3. 类装饰器：使用装饰器语法定义类型

每种方式各有优缺点，开发者可以根据项目需求选择最适合的方式。

总结

本文带你从零开始构建了一个完整的GraphQL Schema，并深入理解了其核心概念。GraphQL Yoga提供了简单易用的API，使得构建GraphQL服务变得轻松愉快。在后续文章中，我们将介绍如何将这个Schema转换为真正的HTTP服务，并添加更多高级功能。

记住，好的Schema设计是GraphQL API成功的关键。花时间精心设计你的类型系统，将为后续开发节省大量时间。