GraphQL 服务端实现与工具库深度对比：apollo-server vs express-graphql vs graphql-tools

在构建现代前端应用时，GraphQL 已成为许多团队替代 REST 的首选数据查询语言。然而，如何在 Node.js 环境中搭建 GraphQL 服务，开发者面临多个选择：apollo-server、express-graphql 和 graphql-tools。它们看似相似，实则定位迥异 —— 有的是完整服务器，有的是中间件，有的则是底层工具库。本文将从工程实践角度，深入剖析三者的本质区别与适用场景。

🧱 核心定位：服务器 vs 中间件 vs 工具库

理解这三者的首要前提是认清它们的根本角色：

• apollo-server 是一个独立的 GraphQL 服务器框架，可直接处理 HTTP 请求并返回 GraphQL 响应，支持 Express、Koa、Fastify 等多种底层 HTTP 框架，也可独立运行。
• express-graphql 是一个Express 专用中间件，必须嵌入 Express 应用中使用，无法脱离 Express 环境。
• graphql-tools 不是服务器，而是一组用于构建和操作 GraphQL schema 的工具函数，需配合其他 GraphQL 执行引擎（如 graphql-js）和服务器使用。

⚠️ 注意：根据 npm 官方页面和 GitHub 仓库信息，express-graphql 已被标记为不再积极维护，官方建议新项目使用 apollo-server 或其他现代替代方案。

🛠️ 快速启动：如何创建一个 GraphQL 服务

使用 apollo-server

apollo-server 提供了最简洁的启动方式，无需手动配置 HTTP 服务器：

// apollo-server 示例
import { ApolloServer } from 'apollo-server';
import { gql } from 'apollo-server';

const typeDefs = gql`
  type Query {
    hello: String
  }
`;

const resolvers = {
  Query: {
    hello: () => 'Hello from Apollo Server!'
  }
};

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

server.listen().then(({ url }) => {
  console.log(`🚀 Server ready at ${url}`);
});

它也支持与 Express 集成：

// 与 Express 集成
import express from 'express';
import { ApolloServer } from 'apollo-server-express';

const app = express();
const server = new ApolloServer({ typeDefs, resolvers });
await server.start();
server.applyMiddleware({ app });

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

使用 express-graphql

express-graphql 必须作为 Express 中间件挂载：

// express-graphql 示例
import express from 'express';
import { graphqlHTTP } from 'express-graphql';
import { buildSchema } from 'graphql';

const schema = buildSchema(`
  type Query {
    hello: String
  }
`);

const root = {
  hello: () => 'Hello from express-graphql!'
};

const app = express();
app.use('/graphql', graphqlHTTP({
  schema,
  rootValue: root,
  graphiql: true // 启用 GraphiQL
}));

app.listen(4000);

使用 graphql-tools

graphql-tools 本身不能启动服务，需配合其他服务器。常见用法是与 apollo-server 结合：

// graphql-tools + apollo-server
import { makeExecutableSchema } from '@graphql-tools/schema';
import { ApolloServer } from 'apollo-server';

const typeDefs = `
  type Query {
    hello: String
  }
`;

const resolvers = {
  Query: {
    hello: () => 'Hello from graphql-tools!'
  }
};

const schema = makeExecutableSchema({ typeDefs, resolvers });

const server = new ApolloServer({ schema });
server.listen();

🧩 Schema 构建能力对比

apollo-server

apollo-server 内部使用 graphql-tools（旧版本）或自研 schema 构建逻辑（新版本），支持直接传入 typeDefs 和 resolvers 对象，也接受预构建的 GraphQLSchema 实例。

// apollo-server 接受多种 schema 输入
new ApolloServer({
  typeDefs: gql`...`,
  resolvers: { ... }
});

// 或
new ApolloServer({ schema: myPrebuiltSchema });

express-graphql

仅支持传入 GraphQLSchema 实例，通常需配合 graphql-js 的 buildSchema 或手动构造：

// express-graphql 要求 schema 是 GraphQLSchema 类型
const schema = buildSchema(`type Query { hello: String }`);

graphqlHTTP({ schema, rootValue: root });

graphql-tools

这是其核心优势所在。graphql-tools 提供了强大的 schema 构建能力，包括：

• SDL 字符串解析：makeExecutableSchema
• Schema 合并：mergeSchemas
• Schema 委托（Stitching）：stitchSchemas
• Mock 数据生成：addMocksToSchema

// 使用 graphql-tools 合并多个 schema
import { mergeSchemas } from '@graphql-tools/merge';

const userSchema = makeExecutableSchema({ ... });
const postSchema = makeExecutableSchema({ ... });

const combinedSchema = mergeSchemas({
  schemas: [userSchema, postSchema]
});

🔌 高级功能支持

开发者体验（DevEx）

• apollo-server：内置 Apollo Studio 集成、性能追踪、错误格式化、插件系统、订阅（Subscriptions）支持。
• express-graphql：仅提供基础的 GraphiQL 支持，无高级调试或监控功能。
• graphql-tools：不涉及运行时功能，但提供 mockServer 等开发辅助工具。

错误处理

apollo-server 允许自定义错误格式：

const server = new ApolloServer({
  formatError: (err) => ({
    message: err.message,
    code: err.extensions?.code || 'INTERNAL_ERROR'
  })
});

而 express-graphql 的错误处理较为原始，需自行封装中间件。

订阅（Subscriptions）

apollo-server 原生支持 WebSocket 订阅：

const server = new ApolloServer({
  typeDefs,
  resolvers,
  subscriptions: {
    path: '/subscriptions'
  }
});

express-graphql 不支持订阅，需额外集成 subscriptions-transport-ws 等库，且配置复杂。

📦 典型使用组合

在实际项目中，这三者常以组合方式出现：

• 主流方案：apollo-server + graphql-tools（利用后者构建复杂 schema，前者提供服务）
• 遗留系统：express-graphql（仅用于简单 Express 应用，新项目应避免）
• 微服务网关：graphql-tools 的 stitchSchemas + apollo-server（实现 GraphQL 网关）

🚫 为什么新项目应避免 express-graphql？

根据 npm 页面 和 GitHub 仓库 的明确说明：

“This package is no longer actively maintained. We recommend using Apollo Server instead.”

这意味着：

• 不再有功能更新
• 安全漏洞可能不会及时修复
• 与新版 graphql-js 的兼容性无法保证

因此，新项目绝不应选择 express-graphql，除非你正在维护一个无法升级的旧系统。

📊 总结：关键差异一览

💡 最终建议

• 如果你要从零开始搭建 GraphQL 服务：直接使用 apollo-server，它提供了最完整的开箱即用体验。
• 如果你需要构建复杂的 schema（如微服务聚合）：在 apollo-server 基础上引入 graphql-tools，利用其 mergeSchemas 或 stitchSchemas 能力。
• 如果你看到老代码里用了 express-graphql：计划迁移至 apollo-server，避免长期技术债务。

记住：graphql-tools 不是服务器，而是让你更轻松地“造 schema”；而 apollo-server 是那个“跑 schema”的引擎。两者配合，才是现代 GraphQL 服务的最佳实践。