KeystoneJS 中如何正确拆分 Schema 文件

在 KeystoneJS 项目中，随着应用规模的增长，将所有列表定义都放在单一的 schema.ts 文件中会变得难以维护。许多开发者希望将这些定义拆分到不同的文件中，但在实际操作中可能会遇到 TypeScript 类型错误。

问题背景

当开发者尝试将 User 列表从 schema.ts 文件迁移到单独的 User.ts 文件时，会遇到一个复杂的 TypeScript 类型错误。这个错误主要涉及类型不匹配问题，特别是关于字段类型和访问控制相关的类型定义。

错误信息表明，从单独文件导入的列表配置与 KeystoneJS 期望的类型结构不兼容。具体来说，问题出在字段类型、访问控制类型以及上下文数据库 API 类型的不匹配上。

解决方案

要解决这个问题，我们需要明确告诉 TypeScript 这个列表定义应该符合特定的类型结构。可以通过使用 satisfies 操作符来实现这一点：

1. 首先确保从 Keystone 类型中导入 Lists 类型
2. 在列表定义后使用 satisfies Lists.User 进行类型断言

import { list } from '@keystone-6/core';
import { Lists } from '.keystone/types';

export const User = list({
  // 列表配置
  fields: {
    // 字段定义
  }
}) satisfies Lists.User;

技术原理

这个解决方案之所以有效，是因为：

1. KeystoneJS 使用复杂的泛型类型系统来确保类型安全
2. 当列表定义在同一个文件中时，TypeScript 可以自动推断出正确的类型
3. 当拆分到不同文件时，类型推断链被中断，需要手动指定类型
4. satisfies 操作符既能进行类型检查，又不会改变值的实际类型

最佳实践

在 KeystoneJS 项目中拆分 schema 时，建议：

1. 为每个主要实体创建单独的文件
2. 始终使用 satisfies 进行类型断言
3. 保持一致的导入结构
4. 考虑创建一个索引文件来集中导出所有列表定义

这种方法不仅能解决类型错误，还能提高代码的可维护性和可读性，特别适合中大型 KeystoneJS 项目。