GraphQL API 开发教程

1. 简介

GraphQL 是一种用于 API 的查询语言，它允许客户端精确地请求所需的数据，而不是服务器返回固定的数据结构。与传统的 RESTful API 相比，GraphQL 提供了更灵活、高效的数据获取方式。本教程将带你从零开始，学习如何在 Node.js 环境中开发一个 GraphQL API。

2. 环境准备

在开始之前，确保你已经安装了 Node.js 和 npm。你可以通过以下命令检查安装情况：

node -v
npm -v

如果没有安装，可以从 Node.js 官网 下载并安装。

3. 创建项目

首先，创建一个新的项目目录并初始化 npm：

mkdir graphql-api
cd graphql-api
npm init -y

接下来，安装必要的依赖包：

npm install express express-graphql graphql

4. 创建第一个 GraphQL 服务器

4.1 创建服务器文件

在项目根目录下创建一个 server.js 文件，并添加以下代码：

const express = require('express');
const { graphqlHTTP } = require('express-graphql');
const { buildSchema } = require('graphql');

// 定义 GraphQL 模式
const schema = buildSchema(`
  type Query {
    hello: String
  }
`);

// 定义根解析器
const root = {
  hello: () => {
    return 'Hello, GraphQL!';
  },
};

// 创建 Express 应用
const app = express();

// 配置 GraphQL 中间件
app.use('/graphql', graphqlHTTP({
  schema: schema,
  rootValue: root,
  graphiql: true, // 启用 GraphiQL 工具
}));

// 启动服务器
app.listen(4000, () => {
  console.log('GraphQL server running at http://localhost:4000/graphql');
});

4.2 运行服务器

在终端中运行以下命令启动服务器：

node server.js

打开浏览器并访问 http://localhost:4000/graphql，你将看到 GraphiQL 界面，这是一个用于测试 GraphQL 查询的交互式工具。

4.3 测试查询

在 GraphiQL 界面中，输入以下查询并点击“运行”按钮：

{
  hello
}

你应该会看到返回的结果：

{
  "data": {
    "hello": "Hello, GraphQL!"
  }
}

5. 定义更复杂的模式

5.1 添加类型和字段

让我们扩展一下模式，添加一个 User 类型和一些字段：

const schema = buildSchema(`
  type User {
    id: ID
    name: String
    email: String
  }

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

5.2 实现解析器

接下来，实现解析器来处理这些查询：

const users = [
  { id: '1', name: 'Alice', email: '[email protected]' },
  { id: '2', name: 'Bob', email: '[email protected]' },
];

const root = {
  user: ({ id }) => {
    return users.find(user => user.id === id);
  },
  users: () => {
    return users;
  },
};

5.3 测试新查询

在 GraphiQL 中测试新的查询：

{
  user(id: "1") {
    name
    email
  }
}

你应该会看到返回的结果：

{
  "data": {
    "user": {
      "name": "Alice",
      "email": "[email protected]"
    }
  }
}

6. 实践练习

6.1 添加 Mutation

GraphQL 不仅支持查询，还支持修改数据的 Mutation。让我们添加一个 Mutation 来创建新用户：

const schema = buildSchema(`
  type User {
    id: ID
    name: String
    email: String
  }

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

  type Mutation {
    createUser(name: String!, email: String!): User
  }
`);

const root = {
  user: ({ id }) => {
    return users.find(user => user.id === id);
  },
  users: () => {
    return users;
  },
  createUser: ({ name, email }) => {
    const newUser = { id: String(users.length + 1), name, email };
    users.push(newUser);
    return newUser;
  },
};

6.2 测试 Mutation

在 GraphiQL 中测试新的 Mutation：

mutation {
  createUser(name: "Charlie", email: "[email protected]") {
    id
    name
    email
  }
}

你应该会看到返回的结果：

{
  "data": {
    "createUser": {
      "id": "3",
      "name": "Charlie",
      "email": "[email protected]"
    }
  }
}

7. 总结

通过本教程，你已经学会了如何在 Node.js 中创建一个简单的 GraphQL API。你了解了如何定义模式、实现解析器，并通过 GraphiQL 工具进行测试。接下来，你可以继续深入学习 GraphQL 的高级特性，如订阅（Subscriptions）、联合类型（Union Types）和接口（Interfaces）等。

8. 进一步学习

• GraphQL 官方文档: https://graphql.org/learn/
• Apollo Server: 一个流行的 GraphQL 服务器库，支持更多的功能和扩展性。
• TypeScript 与 GraphQL: 结合 TypeScript 可以提供更强的类型安全性和开发体验。

希望本教程能帮助你入门 GraphQL API 开发，祝你在未来的学习和实践中取得更多成就！