Apollo Server服务端如何将查询及类型拆分到多个文件

一、如何导入并引用拆分后的 .graphql 文件 #

要实现分散的 .graphql 文件合并为完整 Schema，可借助 @graphql-tools 工具包完成，具体步骤如下：

1. 安装必要依赖 #

先安装核心工具包：

npm install @graphql-tools/load-files @graphql-tools/merge graphql

如果使用 TypeScript，需补充类型声明（未自动安装时手动执行）：

npm install -D @types/graphql

2. 创建拆分的 .graphql 文件 #

按类型或功能拆分文件，示例结构：

• src/schema/books.graphql：存放 Book 类型及相关字段

type Book {
  id: ID!
  title: String!
  authorId: ID!
}

• src/schema/authors.graphql：存放 Author 类型

type Author {
  id: ID!
  name: String!
  books: [Book!]!
}

• src/schema/queries.graphql：存放根 Query 字段

type Query {
  getBook(id: ID!): Book
  getAuthor(id: ID!): Author
  getAllBooks: [Book!]!
}

3. 在 schema.ts 中加载并合并所有文件 #

编写代码加载指定目录下的 .graphql 文件，合并为完整 Schema：

import { loadFilesSync } from '@graphql-tools/load-files';
import { mergeTypeDefs } from '@graphql-tools/merge';
import { makeExecutableSchema } from '@graphql-tools/schema';
import resolvers from './resolvers'; // 你的解析器文件

// 加载所有 .graphql 文件，路径根据项目结构调整
const typeDefsArray = loadFilesSync('./src/schema/**/*.graphql');
// 合并所有类型定义
const mergedTypeDefs = mergeTypeDefs(typeDefsArray);
// 生成可执行 Schema
const schema = makeExecutableSchema({
  typeDefs: mergedTypeDefs,
  resolvers,
});

export default schema;

4. TypeScript 配置（可选） #

若 TypeScript 无法识别 .graphql 文件，在项目根目录创建 graphql.d.ts 声明文件：

declare module '*.graphql' {
  import { DocumentNode } from 'graphql';
  const content: DocumentNode;
  export default content;
}

同时确保 tsconfig.json 的 include 包含该声明文件：

{
  "include": ["src/**/*", "graphql.d.ts"]
}

二、.graphql 文件是否仅适用于客户端？ #

当然不是。.graphql 是 GraphQL 类型定义的原生格式，服务端和客户端均可使用：服务端用它定义 API 的 Schema 结构，客户端用它编写查询/突变语句，本质是同一语法规范的不同应用场景。

三、Schema 选择 .ts 还是 .graphql 文件？ #

根据项目规模与团队协作需求决策：

• 小规模项目/快速原型：用 .ts 中的 gql 字符串更便捷，无需额外配置工具链，直接嵌入代码即可运行。
• 中大规模项目/团队协作：优先选 .graphql 文件，优势包括：
  • 语法纯粹，无 JavaScript/TypeScript 字符串嵌套，可读性更强
  • 类型定义与业务代码分离，Schema 结构更清晰
  • 可使用 GraphQL 专用工具（如 eslint-plugin-graphql、prettier-plugin-graphql）做语法检查和格式化，统一团队规范
  • 便于扩展 Schema 可视化、自动生成文档等操作
• 混合场景：若存在动态生成的类型（如从数据库表结构自动生成），可用 .ts 处理动态部分，静态类型仍用 .graphql 文件维护。

内容的提问来源于stack exchange，提问作者user8758206