在SST AppSyncApi中拆分GraphQL Schema至多文件时遇mergeTypeDefs错误

问题说明 #

根据SST AppSyncApi文档，schema参数支持string|string[]类型，但传入GraphQL Schema文件路径数组时，触发TypeError: mergeTypeDefs is not a function错误。

错误栈信息 #

TypeError: mergeTypeDefs is not a function
    at AppSyncApi.createGraphApi (file:///E:/aws_projects/backend/node_modules/@serverless-stack/resources/dist/AppSyncApi.js:240:42)
    at new AppSyncApi (file:///E:/aws_projects/backend/node_modules/@serverless-stack/resources/dist/AppSyncApi.js:48:14)
    at EmptyStack.MyStack (file:///E:/aws_projects/backend/.build/lib/index.js:3386:15)
    at stack (file:///E:/aws_projects/backend/node_modules/@serverless-stack/resources/dist/FunctionalStack.js:15:35)
    at App.stack (file:///E:/aws_projects/backend/node_modules/@serverless-stack/resources/dist/App.js:336:16)
    at Module.main (file:///E:/aws_projects/backend/.build/lib/index.js:3437:7)
    at file:///E:/aws_projects/backend/.build/run.mjs:99:22 

项目目录结构 #

.
├── lib
│   ├── MyStack
│   ├── Resolvers
│   ├── Schemas
│   └── DataSources
├── src
│   ├── feature1
│   |  ├── feature1.graphql
│   |  ├── feature1.handler
│   |  ├── feature1.resolver
│   ├── feature2
│   |  ├── feature2.graphql
│   |  ├── ...
│   ├── ...
│   └── ...
└── ...

当前栈配置代码 #

import { StackContext, AppSyncApi, Cognito } from '@serverless-stack/resources';
import dataSources from './dataSources';
import resolvers from './resolvers';
import { AuthorizationType, UserPoolDefaultAction } from '@aws-cdk/aws-appsync-alpha';
import { Duration, Expiration } from 'aws-cdk-lib';

export function MyStack({ stack }: StackContext) {
  // Create the AppSync GraphQL API
  const auth = new Cognito(stack, 'Auth');

  const api = new AppSyncApi(stack, 'AppSyncApi', {
    schema: ['src/feature1/feature1.graphql','src/feature1/feature1.graphql'],
    defaults: {
      function: {
        timeout: 20,
        environment: {
          DATABASE:
            process.env.DATABASE ||
            `mongodb+srv://${process.env.MONGO_USERNAME}:${process.env.MONGO_PASSWORD}@atlascluster.sr2q4hg.mongodb.net/${process.env.DATABASE_NAME}?retryWrites=true&w=majority`,
          GRAPHQL_API_URL: process.env.GRAPHQL_API_URL || '',
          GRAPHQL_API_KEY: process.env.GRAPHQL_API_KEY || '',
        },
      },
    },
    cdk: {
      graphqlApi: {
        authorizationConfig: {
          defaultAuthorization: {
            authorizationType: AuthorizationType.USER_POOL,
            userPoolConfig: {
              userPool: auth.cdk.userPool,
              defaultAction: UserPoolDefaultAction.ALLOW,
            },
          },
          additionalAuthorizationModes: [
            {
              authorizationType: AuthorizationType.API_KEY,
              apiKeyConfig: {
                expires: Expiration.after(Duration.days(365)),
              },
            },
          ],
        },
      },
    },
    dataSources: dataSources,
    resolvers: { ...resolvers },
  });
  api.attachPermissions(['s3']);

  // Show the AppSync API Id in the output
  stack.addOutputs({
    ApiId: api.apiId,
    APiUrl: api.url,
    UserPoolId: auth.userPoolId,
    UserPoolClientId: auth.userPoolClientId,
  });
}

解决方案 #

原因分析 #

该错误源于SST内部依赖@graphql-tools/merge包的mergeTypeDefs函数合并多Schema文件，但项目中可能缺失该依赖，或存在版本不兼容问题。

具体解决步骤 #

1. 安装必要依赖
   在项目根目录执行以下命令，安装Schema合并所需的工具包：

npm install @graphql-tools/merge @graphql-tools/utils
# 或使用yarn
yarn add @graphql-tools/merge @graphql-tools/utils

2. 手动合并Schema（可选，安装依赖后仍报错时使用）
   若依赖安装后问题未解决，可手动读取并合并Schema文件，再传递给schema参数：

import { readFileSync } from 'fs';
import { join } from 'path';
import { mergeTypeDefs } from '@graphql-tools/merge';

// 读取各模块Schema文件
const feature1Schema = readFileSync(join(__dirname, '../src/feature1/feature1.graphql'), 'utf8');
const feature2Schema = readFileSync(join(__dirname, '../src/feature2/feature2.graphql'), 'utf8');

// 合并所有Schema
const mergedSchema = mergeTypeDefs([feature1Schema, feature2Schema]);

// 在AppSyncApi配置中使用合并后的Schema
const api = new AppSyncApi(stack, 'AppSyncApi', {
  schema: mergedSchema,
  // 其余配置保持不变
});

3. 验证版本兼容性
   检查SST版本与@graphql-tools包版本是否匹配，可查看SST依赖的@graphql-tools/merge版本（在node_modules/@serverless-stack/resources/package.json中），确保安装的包版本一致，避免版本冲突。

模块化Schema管理实现 #

通过上述方法，可将不同业务模块的Schema拆分到独立.graphql文件中，再通过合并整合为完整Schema，实现大型项目的Schema模块化管理，提升维护效率。

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