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

技术栈选择

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

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

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

环境搭建

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

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

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

npm install express apollo-server-express graphql mongoose

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

构建基本API结构

1. 创建项目文件结构

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

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

2. 定义数据模型

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

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中添加：

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并添加如下代码：

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的所有部分：

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架构。可以通过运行以下命令启动服务器：

node src/index.js

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

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

query {
  users {
    id
    name
    email
  }
}

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

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

小结

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

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

Jupyter AI

25 实战：构建一个GraphQL API之基本API结构