KeystoneJS GraphQL Schema扩展指南：自定义你的API结构-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00707/article/details/148418313

KeystoneJS GraphQL Schema扩展指南：自定义你的API结构

keystone The most powerful headless CMS for Node.js — built with GraphQL and React 项目地址: https://gitcode.com/gh_mirrors/key/keystone

理解KeystoneJS的GraphQL Schema自动生成机制

KeystoneJS作为一个强大的Headless CMS框架，其核心功能之一就是能够根据开发者定义的配置自动生成完整的GraphQL Schema。这个自动生成的Schema包含了基于你定义的所有列表（Lists）的GraphQL类型、查询（Queries）和变更（Mutations）。

当你运行Keystone项目时，框架会在项目根目录生成一个schema.graphql文件，这个文件就是Keystone根据你的配置自动生成的GraphQL Schema定义。虽然Keystone提供的Hooks机制可以满足大部分行为定制需求，但在某些场景下，你可能需要：

添加自定义的GraphQL类型
创建特殊的查询或变更操作
修改现有的解析逻辑

这时，extendGraphqlSchema配置选项就派上用场了。

使用Keystone内置的graphql.extend方法

Keystone从@keystone/core模块导出了一个graphql对象，它基于@graphql-ts/schema库实现，可以与.keystone/types中的Context类型配合使用，提供类型安全的Schema扩展能力。

基本使用模式

首先，你需要在Keystone配置文件中导入必要的工具：

import { graphql, config } from '@keystone/core';
import { Context } from '.keystone/types';

然后，你可以使用graphql.extend方法来扩展基础Schema。这个方法接收一个函数，该函数接收自动生成的base Schema，并返回一个包含你自定义内容的Schema扩展对象。

实战示例：发布文章的自定义Mutation

假设我们有一个博客系统，需要添加一个"发布文章"的自定义Mutation：

export default config({
  // ...其他配置...
  extendGraphqlSchema: graphql.extend(base => {
    return {
      mutation: {
        publishPost: graphql.field({
          type: base.object('Post'),  // 使用基础Schema中的Post类型
          args: { 
            id: graphql.arg({ type: graphql.nonNull(graphql.ID) }) 
          },
          resolve(source, { id }, context: Context) {
            return context.db.Post.updateOne({
              where: { id },
              data: { 
                status: 'published', 
                publishDate: new Date().toISOString() 
              },
            });
          },
        }),
      },
    };
  }),
});

这个例子中，我们创建了一个名为publishPost的Mutation，它：

接收一个非空的ID参数
使用Keystone的数据库上下文(context.db)更新对应文章
返回更新后的Post对象

关键点说明：

context.db提供了类型安全的数据库访问方式
base.object('Post')引用了基础Schema中定义的Post类型
所有GraphQL类型定义都通过graphql命名空间下的方法创建

使用第三方工具扩展Schema

虽然Keystone提供了内置的扩展方式，但你也可以选择使用流行的GraphQL工具库如@graphql-tools/schema来进行Schema扩展。

安装与配置

首先安装必要的依赖：

npm install @graphql-tools/schema

然后在配置文件中导入：

import { mergeSchemas } from '@graphql-tools/schema';

使用mergeSchemas扩展

下面是用mergeSchemas实现相同功能的例子：

export default config({
  // ...其他配置...
  extendGraphqlSchema: schema =>
    mergeSchemas({
      schemas: [schema],  // 包含原始Schema
      typeDefs: `
        type Mutation {
          publishPost(id: ID!): Post
        }
      `,
      resolvers: {
        Mutation: {
          publishPost: (root, { id }, context) => {
            return context.db.Post.updateOne({
              where: { id },
              data: { 
                status: 'published', 
                publishDate: new Date().toUTCString() 
              },
            });
          },
        },
      },
    }),
});

注意事项：