Egg.js GraphQL 完整指南

简介

GraphQL 是一种用于 API 的查询语言，它提供了一种更高效、强大和灵活的方式来处理数据。Egg.js 通过 egg-graphql 插件提供了完整的 GraphQL 支持，使得在 Egg.js 中开发 GraphQL API 变得简单和高效。

主要特点

完整的 GraphQL 规范支持
自动加载 Schema 和 Resolver
内置 GraphQL 调试工具
支持自定义中间件
类型安全

项目设置

1. 创建新项目

bash 复制代码

$ mkdir egg-graphql-example
$ cd egg-graphql-example
$ npm init egg --type=simple
$ npm i

2. 安装必要依赖

bash 复制代码

$ npm install --save egg-graphql

3. 启用插件

在 config/plugin.js 中启用 GraphQL 插件：

javascript 复制代码

module.exports = {
  graphql: {
    enable: true,
    package: 'egg-graphql',
  },
};

GraphQL 基础配置

1. 配置 GraphQL 路由

在 config/config.default.js 中添加配置：

javascript 复制代码

module.exports = appInfo => {
  const config = {};

  config.graphql = {
    router: '/graphql',
    // 是否加载到 app 上，默认开启
    app: true,
    // 是否加载到 agent 上，默认关闭
    agent: false,
    // 是否加载开发者工具 graphiql, 默认开启
    graphiql: true,
  };

  return config;
};

实战示例

让我们创建一个简单的用户查询系统。

1. 定义 Schema

在 app/graphql/user/schema.graphql 中：

graphql 复制代码

type User {
  id: ID!
  name: String!
  email: String!
  age: Int
}

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

type Mutation {
  createUser(name: String!, email: String!, age: Int): User
}

2. 实现 Resolver

在 app/graphql/user/resolver.js 中：

javascript 复制代码

module.exports = {
  Query: {
    user(root, { id }, ctx) {
      // 这里实现获取单个用户的逻辑
      return ctx.service.user.findById(id);
    },
    users(root, params, ctx) {
      // 这里实现获取用户列表的逻辑
      return ctx.service.user.findAll();
    },
  },
  Mutation: {
    createUser(root, { name, email, age }, ctx) {
      // 这里实现创建用户的逻辑
      return ctx.service.user.create({ name, email, age });
    },
  },
};

3. 实现 Service 层

在 app/service/user.js 中：

javascript 复制代码

const Service = require('egg').Service;

class UserService extends Service {
  async findById(id) {
    // 实现查询单个用户的逻辑
    return {
      id,
      name: 'John Doe',
      email: '[email protected]',
      age: 30,
    };
  }

  async findAll() {
    // 实现查询所有用户的逻辑
    return [
      {
        id: '1',
        name: 'John Doe',
        email: '[email protected]',
        age: 30,
      },
      {
        id: '2',
        name: 'Jane Doe',
        email: '[email protected]',
        age: 25,
      },
    ];
  }

  async create({ name, email, age }) {
    // 实现创建用户的逻辑
    return {
      id: '3',
      name,
      email,
      age,
    };
  }
}

module.exports = UserService;

使用示例

查询单个用户

graphql 复制代码

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

查询所有用户

graphql 复制代码

query {
  users {
    id
    name
    email
    age
  }
}

创建新用户

graphql 复制代码

mutation {
  createUser(
    name: "Alice"
    email: "[email protected]"
    age: 28
  ) {
    id
    name
    email
    age
  }
}

最佳实践

类型定义
- 使用明确的类型定义
- 合理使用非空类型（!）
- 为每个字段添加描述
目录结构

app/
├── graphql/
│ └── user/
│ ├── schema.graphql
│ └── resolver.js
├── service/
│ └── user.js
└── model/
└── user.js
错误处理

javascript 复制代码

// 在 resolver 中
module.exports = {
  Query: {
    async user(root, { id }, ctx) {
      try {
        const user = await ctx.service.user.findById(id);
        if (!user) {
          throw new Error('User not found');
        }
        return user;
      } catch (error) {
        ctx.logger.error(error);
        throw error;
      }
    },
  },
};

性能优化
- 使用数据加载器（DataLoader）处理 N+1 问题
- 实现字段级缓存
- 限制查询深度和复杂度
安全性
- 实现身份验证和授权
- 限制查询复杂度
- 设置适当的超时时间

调试技巧

使用 GraphiQL 工具（访问 /graphql）
开启 Debug 日志
使用 ctx.logger 记录关键信息

结论

Egg.js 的 GraphQL 插件提供了一个强大而灵活的方式来构建 GraphQL API。通过合理的项目结构和最佳实践，我们可以构建出高效、可维护的 GraphQL 服务。

Egg.js GraphQL 完整指南