在上一篇文章《实战：构建一个GraphQL API之项目需求分析》中，我们详细讨论了项目的需求，定义了API的目标和功能。现在，我们进入这一系列教程的重要一步——构建基本的API结构。在本篇中，我们将从零开始搭建GraphQL API的基本框架，并确保我们的代码结构清晰且便于扩展。

技术栈选择

在开始之前，我们首先确认即将使用的技术栈：

• Node.js：作为后端运行时环境。
• Express：作为Web框架。
• Apollo Server：用于构建GraphQL服务器。
• MongoDB：作为数据库（如果需要持久化数据）。

为了后续的教程简便起见，我们以基于Node.js和Express的环境为基础，构建一个简单的GraphQL API。

环境搭建

首先，我们需要初始化一个新的Node.js项目。打开终端并执行以下命令：

1
2
3

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

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

1

npm install express apollo-server-express graphql mongoose

• express：轻量级的Web框架。
• apollo-server-express：在Express上集成Apollo GraphQL服务器。
• graphql：用于定义GraphQL的核心库。
• mongoose：MongoDB的对象建模工具。

构建基本API结构

1. 创建项目文件结构

为了使代码结构清晰，我们可以创建如下的文件结构：

1
2
3
4
5
6
7

graphql-api/
├── src/
│   ├── models/
│   ├── schemas/
│   ├── resolvers/
│   └── index.js
└── package.json

2. 定义数据模型

在src/models/目录中，我们将定义一个简单的模型，例如User。在src/models/User.js中添加以下代码：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

const mongoose = require('mongoose');

const userSchema = new mongoose.Schema({
    name: {
        type: String,
        required: true,
    },
    email: {
        type: String,
        required: true,
        unique: true,
    },
});

module.exports = mongoose.model('User', userSchema);

这段代码定义了一个表示用户的模型，包含name和email字段。

3. 定义GraphQL Schema

在src/schemas/目录下，我们定义GraphQL的Schema。在src/schemas/userSchema.js中添加：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

const { gql } = require('apollo-server-express');

const userSchema = gql`
    type User {
        id: ID!
        name: String!
        email: String!
    }

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

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

module.exports = userSchema;

这里，我们定义了一个User类型以及两种操作：

• Query用于读取数据。
• Mutation用于创建新用户。

4. 编写Resolvers

在src/resolvers/目录中，创建一个文件userResolvers.js并添加如下代码：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

const User = require('../models/User');

const userResolvers = {
    Query: {
        users: async () => await User.find(),
        user: async (_, { id }) => await User.findById(id),
    },
    Mutation: {
        createUser: async (_, { name, email }) => {
            const user = new User({ name, email });
            return await user.save();
        },
    },
};

module.exports = userResolvers;

在这里，我们创建了对应Query和Mutation的resolver，通过Mongoose与MongoDB进行交互。

5. 将所有部分整合在一起

在src/index.js中整合API的所有部分：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

const express = require('express');
const { ApolloServer } = require('apollo-server-express');
const mongoose = require('mongoose');
const userSchema = require('./schemas/userSchema');
const userResolvers = require('./resolvers/userResolvers');

const startServer = async () => {
    const app = express();
    
    mongoose.connect('mongodb://localhost:27017/graphql_api', { useNewUrlParser: true, useUnifiedTopology: true });

    const server = new ApolloServer({
        typeDefs: userSchema,
        resolvers: userResolvers
    });

    server.applyMiddleware({ app });

    app.listen({ port: 4000 }, () => {
        console.log(`🚀 Server ready at http://localhost:4000${server.graphqlPath}`);
    });
};

startServer();

在这个文件中，我们:

• 连接到MongoDB。
• 创建并启动Apollo Server。
• 将GraphQL API绑定到Express应用上。

测试基本API

至此，我们已成功构建了一个基础的GraphQL API架构。可以通过运行以下命令启动服务器：

1

node src/index.js

访问 http://localhost:4000/graphql，可以使用Apollo Studio进行API的测试。

在GraphQL Playground中，可以尝试以下查询以获取用户列表：

1
2
3
4
5
6
7

query {
  users {
    id
    name
    email
  }
}

和以下mutation来创建一个新用户：

1
2
3
4
5
6
7

mutation {
  createUser(name: "Alice", email: "alice@example.com") {
    id
    name
    email
  }
}

小结

在本篇文章中，我们成功地构建了一个基本的GraphQL API结构。我们定义了数据模型、GraphQL schema和resolver，并将它们无缝集成到一个Express应用中。随着项目的不断发展，我们可以根据需求进一步扩展和优化我们的API。

在下一篇文章《实战：构建一个GraphQL API之部署与测试》中，我们将讨论如何将这个API部署到云端、进行测试以及监控其性能等内容，请继续关注！

在上一篇中，我们已经完成了构建基本的 GraphQL API 结构。现在，我们将进入这一系列教程的另一个重要部分：部署和测试我们的 GraphQL API。通过本文，你将学习到如何将你的 API 部署到云服务，并运用测试工具确保其稳定性和可用性。

部署 GraphQL API

选择部署平台

在部署 GraphQL API 之前，首先需要选择一个合适的云服务平台。常见的选择包括：

• Heroku
• AWS（Amazon Web Services）
• GCP（Google Cloud Platform）
• DigitalOcean

本教程将以 Heroku 为例，演示如何快速部署你的 GraphQL API。

在 Heroku 上部署

1. 安装 Heroku CLI

   如果你还没有安装 Heroku CLI，可以从 Heroku 官方网站 下载并安装。

2. 登录 Heroku

   打开终端并输入以下命令进行登录：

   1	heroku login

3. 创建 Heroku 应用

   在你的项目根目录中，使用以下命令创建一个新的 Heroku 应用：

   1	heroku create your-app-name

4. 配置环境变量

   如果你的 API 依赖于环境变量（例如数据库连接字符串），可以使用以下命令设置这些变量：

   1	heroku config:set DATABASE_URL=your_database_url

5. 构建并部署

   确保你的项目包含一个 Procfile，该文件定义了应用程序的入口点。例如，对于 Node.js 应用，可以这样设置：

   1	web: node index.js

   然后，使用以下命令将代码推送到 Heroku：

   1 2 3

   git add . git commit -m "Deploying GraphQL API" git push heroku master

6. 开启应用

   部署完成后，可以使用以下命令启动你的应用：

   1	heroku open

现在，你的 GraphQL API 已经成功部署并可以通过 Heroku 提供的 URL 访问。

测试 GraphQL API

在确保 API 成功部署之后，接下来的步骤是进行全面的测试。测试可以帮助我们发现潜在的bug，并确保 API 的稳定性和性能。

使用 Postman 进行手动测试

1. 安装 Postman

   如果还没有安装，可以从 Postman 官网 下载并安装。

2. 创建新的请求

   打开 Postman，选择 POST 方法并输入你的 GraphQL API URL，例如：

   1	https://your-app-name.herokuapp.com/graphql

3. 设置请求头

   在请求头中添加 Content-Type：

   1 2	Key: Content-Type Value: application/json

4. 构造请求体

   在请求体中输入你的 GraphQL 查询，例如：

   1 2 3

   { "query": "{ users { id name } }" }

5. 发送请求并观察响应

   点击 “Send” 按钮发送请求并检查返回的数据，以确保 API 正常工作。

使用 Jest 进行自动化测试

为了实现更高效的测试，建议编写自动化测试用例。我们将使用 Jest 来实现这一点。

1. 安装 Jest

   在你的项目中安装 Jest：

   1	npm install --save-dev jest

2. 编写测试代码

   创建一个名为 test.js 的测试文件，输入如下内容：

   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

   const request = require('supertest'); const app = require('./index'); // 引入你的应用 describe('GraphQL API', () => { it('should fetch users', async () => { const res = await request(app) .post('/graphql') .send({ query: '{ users { id name } }', }); expect(res.statusCode).toEqual(200); expect(res.body.data.users).toBeDefined(); }); });

3. 运行测试

   在终端中运行以下命令来执行测试：

   1

   npx jest

测试通过后，你将看到相应的提示，这表明你的 GraphQL API 在正常工作。

小结

在本篇教程中，我们完成了 GraphQL API 的部署和测试。通过在 Heroku 上部署我们的 API，并使用 Postman 及 Jest 进行手动和自动化测试，我们确保了 API 的可用性和稳定性。下一篇将继续探索 GraphQL API 的性能优化与最佳实践。希望你跟着这个系列持续加油，提升你的 GraphQL API 开发技能！