如何让Contentful GraphQL架构将必填字段识别为必填而非可选？

我在使用Contentful内容模型时遇到了一个问题：内容模型里标记为必填的字段，在自动生成的GraphQL Schema中没有被标记为非空（缺少!），导致最终生成的TypeScript类型里所有字段都被标记为可选（带?或包裹在Maybe中），完全无法区分必填和可选字段。

举个实际例子：
内容模型中的必填title和可选description字段：

{
  "id": "title",
  "name": "Title",
  "type": "Symbol",
  "localized": false,
  "required": true,
  "validations": [
    {
      "size": {
        "max": 150
      }
    }
  ],
  "disabled": false,
  "omitted": false
},
{
  "id": "description",
  "name": "Description",
  "type": "RichText",
  "localized": false,
  "required": false,
  "validations": [],
  "disabled": false,
  "omitted": false
}

生成的GraphQL Schema里两者都是可选：

description(locale: String): ReferenceToRichTextModelDescription
title(locale: String): String

对应的TypeScript类型也全是可选：

description?: Maybe<ReferenceToRichTextModelDescription>;
title?: Maybe<Scalars['String']['output']>;

解决办法 #

Contentful的GraphQL API默认将所有字段设为可选，这是出于本地化、字段省略等场景的兼容性考虑，但我们可以通过以下方式手动区分必填字段：

1. 自定义GraphQL Codegen插件（推荐）

通过Contentful Management API拉取内容模型的元数据（包含required标记），然后编写GraphQL Codegen插件，在生成TypeScript类型时自动修正必填字段的可选性。

示例插件逻辑（伪代码）：

import { CodegenPlugin } from '@graphql-codegen/plugin-helpers';
import { createClient } from 'contentful-management';

// 拉取Contentful内容模型元数据
async function getContentfulRequiredFields() {
  const client = createClient({ accessToken: 'YOUR_MANAGEMENT_TOKEN' });
  const space = await client.getSpace('YOUR_SPACE_ID');
  const environment = await space.getEnvironment('YOUR_ENV');
  const contentTypes = await environment.getContentTypes();
  
  const requiredFields = new Map();
  contentTypes.items.forEach(type => {
    type.fields.forEach(field => {
      if (field.required) {
        // 存储类型名+字段名的映射
        requiredFields.set(`${type.sys.id}.${field.id}`, true);
      }
    });
  });
  return requiredFields;
}

// 自定义Codegen插件
export const contentfulRequiredFieldsPlugin: CodegenPlugin = {
  async afterOneFileWrite(content) {
    const requiredFields = await getContentfulRequiredFields();
    let updatedContent = content;
    
    requiredFields.forEach((_, key) => {
      const [typeName, fieldName] = key.split('.');
      // 替换TS类型中的可选标记和Maybe包裹
      const regex = new RegExp(`(${fieldName})\\?: Maybe<(.*)>;`, 'g');
      updatedContent = updatedContent.replace(regex, `$1: $2;`);
    });
    
    return updatedContent;
  },
};

在GraphQL Codegen配置中引入这个插件，就能自动生成带正确必填标记的TypeScript类型。

2. 手动维护类型覆盖文件

如果字段数量不多，可以在自动生成的类型基础上，手动创建覆盖文件，用交叉类型修正必填字段：

import type { Post } from './generated/contentful';

// 修正title为必填，保留其他字段
type PostWithRequiredFields = Omit<Post, 'title'> & {
  title: NonNullable<Post['title']>;
};

这种方式简单直接，但需要在内容模型变更时手动同步覆盖文件。

3. 调整GraphQL Codegen配置（简易版）

在codegen.ts中设置maybeValue: 'undefined'，然后手动给必填字段添加非空断言，但这种方式需要提前明确所有必填字段，灵活性较差：

// codegen.ts
export default {
  // ...其他配置
  generates: {
    './generated/contentful.ts': {
      plugins: ['typescript'],
      config: {
        maybeValue: 'undefined',
      },
    },
  },
};

注意事项 #

• 本地化字段：如果字段开启了本地化，即使标记为必填，不同locale下仍可能存在为空的情况，需要根据业务场景决定是否强制设为必填。
• 内容模型变更：无论使用哪种方案，当内容模型的必填字段修改时，都需要同步更新对应的处理逻辑，避免类型与实际数据不一致。

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