GraphQL循环模块错误求解：无需合并类型文件的方案

问题背景 #

开发星球大战GraphQL API时，filmType和characterType因互相引用形成循环依赖：电影包含多个角色，角色参演多部电影，导致启动时出现Circular modules: Expected {} to be a GraphQL type错误。现有方案是合并所有类型到单一文件，现寻求拆分文件的解决办法。

解决方案 #

方案1：将交叉引用移到fields工厂函数内部 #

利用GraphQL fields支持函数的特性，在需要引用交叉类型时延迟require，此时模块已完成加载，不会拿到空对象。

修改后的film.js关键部分

// 移除顶部的const charecterType = require("./charecter");

module.exports = new GraphQLObjectType({
  name: "Film",
  fields: () => ({
    // ...其他字段保持不变
    characters: {
      // 在字段定义内部require交叉类型
      type: new GraphQLList(require("./charecter")),
      resolve: (film, parent, args) => {
        return getFilteredData(film.characters);
      },
    },
    // ...其他字段保持不变
  }),
});

修改后的charecter.js关键部分

// 移除顶部的const filmType = require("./film");

module.exports = new GraphQLObjectType({
  name: "Character",
  fields: () => ({
    // ...其他字段保持不变
    films: {
      // 在字段定义内部require交叉类型
      type: new GraphQLList(require("./film")),
      resolve: (character, parent, args) => {
        console.log(character);
        return [];
      },
    },
    // ...其他字段保持不变
  }),
});

方案2：使用模块导出占位+延迟赋值 #

通过先导出空对象占位，再定义并赋值GraphQL类型，让循环引用时能获取到模块的导出对象，后续类型初始化完成后自动更新引用。

修改后的film.js

const axios = require("axios");
const {
  GraphQLObjectType,
  GraphQLString,
  GraphQLInt,
  GraphQLList,
} = require("graphql");

const specieType = require("./specie");
const starshipType = require("./starship");
const vehicleType = require("./vehicle");
const planetType = require("./planet");
const charecterType = require("./charecter");

const getFilteredData = require("../util/loader");

// 先导出空对象占位
module.exports = {};

// 定义Film类型
const FilmType = new GraphQLObjectType({
  name: "Film",
  fields: () => ({
    // ...所有字段保持不变
    title: { type: GraphQLString },
    episode_id: { type: GraphQLInt },
    // ...其他字段
    characters: {
      type: new GraphQLList(charecterType),
      resolve: (film, parent, args) => {
        return getFilteredData(film.characters);
      },
    },
  }),
});

// 将类型赋值给导出对象，覆盖占位
module.exports = FilmType;

修改后的charecter.js

const { GraphQLObjectType, GraphQLString, GraphQLList } = require("graphql");
const getFilteredData = require("../util/loader");

const filmType = require("./film");

// 先导出空对象占位
module.exports = {};

// 定义Character类型
const CharacterType = new GraphQLObjectType({
  name: "Character",
  fields: () => ({
    // ...所有字段保持不变
    name: { type: GraphQLString },
    height: { type: GraphQLString },
    // ...其他字段
    films: {
      type: new GraphQLList(filmType),
      resolve: (character, parent, args) => {
        console.log(character);
        return [];
      },
    },
  }),
});

// 将类型赋值给导出对象，覆盖占位
module.exports = CharacterType;

原理说明 #

CommonJS模块加载时，循环引用会导致其中一个模块在初始化阶段拿到另一个模块的未完成导出（空对象），GraphQL验证类型时发现不是合法的GraphQL类型，因此报错。两种方案都是通过延迟引用时机，确保在使用交叉类型时，目标模块已经完成类型的定义和导出。

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