如何拆分AWS GraphQL API Schema文件以提升可维护性？

当你的GraphQL Schema超过数百行后，拆分文件是提升可维护性的关键。虽然AWS CDK官方没有直接提供拆分支持，但可以通过以下几种实用方案实现：

方案1：自定义文件拼接脚本 #

自己写一个简单的脚本（比如Node.js），将拆分后的多个Schema文件合并为单个文件，再在CDK中引用合并后的文件。

步骤： #

1. 按功能拆分Schema文件，比如：
   • schema/types/User.graphql
   • schema/queries/UserQueries.graphql
   • schema/mutations/UserMutations.graphql
   • schema/enums/RoleEnum.graphql
2. 编写合并脚本（比如merge-schemas.js）：

   const fs = require('fs');
   const path = require('path');
   
   const schemaDir = path.join(__dirname, 'schema');
   const outputPath = path.join(__dirname, 'schema.graphql');
   
   let mergedSchema = '';
   
   // 遍历目录读取所有.graphql文件
   function readFiles(dir) {
     const files = fs.readdirSync(dir);
     files.forEach(file => {
       const fullPath = path.join(dir, file);
       const stats = fs.statSync(fullPath);
       if (stats.isDirectory()) {
         readFiles(fullPath);
       } else if (file.endsWith('.graphql')) {
         const content = fs.readFileSync(fullPath, 'utf8');
         mergedSchema += content + '\n\n';
       }
     });
   }
   
   readFiles(schemaDir);
   fs.writeFileSync(outputPath, mergedSchema.trim());
   

3. 在部署前运行脚本，或者在CDK代码中通过child_process调用脚本生成合并文件：

   import * as childProcess from 'child_process';
   import * as cdk from 'aws-cdk-lib';
   import { GraphQLApi } from '@aws-cdk/aws-appsync-alpha';
   
   // 先运行合并脚本
   childProcess.execSync('node merge-schemas.js');
   
   export class MyGraphqlStack extends cdk.Stack {
     constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
       super(scope, id, props);
   
       const api = new GraphQLApi(this, 'MyApi', {
         name: 'my-api',
         schemaDefinitionFile: './schema.graphql',
         // 其他配置...
       });
     }
   }
   

方案2：使用GraphQL工具库合并 #

借助@graphql-tools/merge这类专门的工具库，直接在CDK代码中合并多个Schema文件，无需生成中间文件。

步骤： #

1. 安装依赖：

   npm install @graphql-tools/merge @graphql-tools/utils graphql
   

2. 在CDK代码中读取并合并Schema文件：

   import * as cdk from 'aws-cdk-lib';
   import { GraphQLApi, Schema } from '@aws-cdk/aws-appsync-alpha';
   import { loadFilesSync } from '@graphql-tools/load-files';
   import { mergeTypeDefs } from '@graphql-tools/merge';
   import * as path from 'path';
   
   export class MyGraphqlStack extends cdk.Stack {
     constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
       super(scope, id, props);
   
       // 加载所有拆分的Schema文件
       const typeDefs = loadFilesSync(path.join(__dirname, 'schema/**/*.graphql'));
       // 合并为单个Schema定义
       const mergedTypeDefs = mergeTypeDefs(typeDefs);
   
       const api = new GraphQLApi(this, 'MyApi', {
         name: 'my-api',
         schema: Schema.fromString(mergedTypeDefs),
         // 其他配置...
       });
     }
   }
   

这个方案更简洁，无需维护额外的脚本，还能自动处理Schema的语法校验。

方案3：通过自定义资源在部署时合并 #

如果希望完全在CDK部署流程中处理合并（不提前生成文件），可以使用**自定义资源（Custom Resource）**来在CloudFormation部署阶段合并Schema文件。

核心思路： #

1. 将拆分的Schema文件作为CDK Asset上传到S3。
2. 创建一个Lambda函数，负责从S3读取所有Schema文件并合并。
3. 自定义资源调用这个Lambda函数，将合并后的Schema传递给AppSync API。

这个方案相对复杂，适合需要动态生成Schema的场景，一般推荐前两种方案即可。

内容的提问来源于stack exchange，提问作者Elmar B.