本教程可帮助您:

  • 获得对 GraphQL 原理的基本理解
  • 定义一个表示数据集结构的 GraphQL 模式
  • 运行 Apollo Server 实例,该实例允许您针对架构执行查询

本教程假定您熟悉命令行和 JavaScript,并且您安装了最新版本的 Node.js (12+)。

本教程将引导您完成阿波罗服务器的安装和配置。如果您刚刚开始使用 GraphQL 或 Apollo 平台,我们建议您先完成全栈教程

步骤 1:创建新项目

  1. 从您首选的开发目录中,为新项目创建一个目录并进入其中:cd

    1
    2
    
    mkdir graphql-server-example
    cd graphql-server-example
    
  2. 使用(或您喜欢的其他包管理器,例如 Yarn)初始化新的 Node.js 项目:npm

    1
    
    npm init --yes
    

您的项目目录现在包含一个文件。package.json

步骤 2:安装依赖项

运行 Apollo Server 的应用程序需要两个顶级依赖项:

  • apollo-server 是 Apollo Server 本身的核心库,它可以帮助您定义数据的形状以及如何获取数据。
  • graphql 是用于构建 GraphQL 模式并对其执行查询的库。

运行以下命令以安装这两个依赖项,并将它们保存在项目的目录中:node_modules

1
npm install apollo-server graphql

同时在项目的根目录中创建一个空文件:index.js

1
touch index.js

为简单起见,将包含此示例应用程序的所有代码。index.js

步骤 3:定义您的 GraphQL 模式

每个 GraphQL 服务器(包括 Apollo Server)都使用一个模式来定义客户端可以查询的数据结构。在此示例中,我们将创建一个服务器,用于按标题和作者查询一组图书。

在您的首选编辑器中打开,然后将以下内容粘贴到其中:index.js

索引.js

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
const { ApolloServer, gql } = require('apollo-server');

// A schema is a collection of type definitions (hence "typeDefs")
// that together define the "shape" of queries that are executed against
// your data.
const typeDefs = gql`
  # Comments in GraphQL strings (such as this one) start with the hash (#) symbol.

  # This "Book" type defines the queryable fields for every book in our data source.
  type Book {
    title: String
    author: String
  }

  # The "Query" type is special: it lists all of the available queries that
  # clients can execute, along with the return type for each. In this
  # case, the "books" query returns an array of zero or more Books (defined above).
  type Query {
    books: [Book]
  }
`;

此代码段定义了一个简单、有效的 GraphQL 模式。客户端将能够执行名为 的查询,我们的服务器将返回一个包含零个或多个 s 的数组。books``Book

第 4 步:定义数据集

现在我们已经定义了*数据的结构,*我们可以定义数据本身。Apollo Server 可以从您连接到的任何源(包括数据库、REST API、静态对象存储服务,甚至是另一个 GraphQL 服务器)获取数据。出于本教程的目的,我们将只对一些示例数据进行硬编码。

在 的底部添加以下内容:index.js

索引.js

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
const books = [
  {
    title: 'The Awakening',
    author: 'Kate Chopin',
  },
  {
    title: 'City of Glass',
    author: 'Paul Auster',
  },
];

此代码段定义了客户端可以查询的简单数据集。请注意,数组中的两个对象都与我们在架构中定义的类型的结构匹配。Book

步骤 5:定义冲突解决程序

我们已经定义了我们的数据集,但 Apollo Server 不知道它在执行查询时应该使用该数据集。为了解决此问题,我们创建了一个解析程序

解析器告诉 Apollo Server 如何获取与特定类型关联的数据。由于我们的数组是硬编码的,因此相应的解析器非常简单。Book

在 的底部添加以下内容:index.js

索引.js

1
2
3
4
5
6
7
// Resolvers define the technique for fetching the types defined in the
// schema. This resolver retrieves books from the "books" array above.
const resolvers = {
  Query: {
    books: () => books,
  },
};

步骤 6:创建 ApolloServer 的实例

我们已经定义了架构、数据集和解析程序。现在,我们只需要在初始化 Apollo Server 时向它提供此信息。

在 的底部添加以下内容:index.js

索引.js

1
2
3
4
5
6
7
8
// The ApolloServer constructor requires two parameters: your schema
// definition and your set of resolvers.
const server = new ApolloServer({ typeDefs, resolvers });

// The `listen` method launches a web server.
server.listen().then(({ url }) => {
  console.log(`🚀  Server ready at ${url}`);
});

步骤 7:启动服务器

我们已准备好启动我们的服务器!从项目的根目录运行以下命令:

1
node index.js

您应看到以下输出:

1
🚀 Server ready at http://localhost:4000/

我们已启动并运行!

步骤 8:执行第一个查询

现在,我们可以在服务器上执行 GraphQL 查询。要执行第一个查询,我们可以使用 Apollo Sandbox

在浏览器中访问。此时将显示 Apollo Server 的默认登录页面:http://localhost:4000

Apollo Server default landing page

单击“查询您的服务器”以打开沙盒。

您还可以:

  • 选择**“下次自动重定向到工作室**”,前提是您希望在每次访问时自动打开沙盒localhost:4000
  • 直接在 studio.apollographql.com/sandbox 打开沙盒

Apollo Sandbox

沙盒 UI 包括:

  • 用于编写和执行查询的操作面板(中间)
  • 用于查看查询结果的响应面板(右侧)
  • 用于架构浏览、搜索和设置的选项卡(左侧)
  • 用于连接到其他 GraphQL 服务器的 URL 栏(左上角)

我们的服务器支持名为 的单个查询。让我们来执行它!books

下面是用于执行查询的 GraphQL 查询字符串books

1
2
3
4
5
6
query GetBooks {
  books {
    title
    author
  }
}

将此字符串粘贴到“操作”面板中,然后单击右上角的蓝色按钮。结果(来自我们的硬编码数据集)显示在响应面板中:

Sandbox response panel

注意:如果将服务器部署到设置为 的环境,则默认情况下禁用自省。这会阻止 Apollo Sandbox 正常工作。要启用自省,请在 ApolloServer 构造函数的选项中设置。NODE_ENV``production``introspection: true

GraphQL 最重要的概念之一是,客户端可以选择仅查询他们需要的字段。从查询字符串中删除,然后再次执行。响应将更新为仅包含每本书的字段!author``title

组合示例

您可以在 CodeSandbox 上查看和分叉这个完整的示例:

Edit server-getting-started

今后的步骤

此示例应用程序是使用 Apollo Server 的良好起点。请查看以下资源,了解有关架构、解析程序和部署的基础知识的详细信息: