Graphile/Crystal项目中枚举值内部表示与外部表示的转换问题解析

在Graphile/Crystal项目中，开发者遇到了一个关于GraphQL枚举值表示的有趣问题。这个问题涉及到GraphQL规范中枚举值的内部表示与外部表示之间的差异，以及在插件开发中如何处理这种差异。

问题背景

在PostgreSQL数据库中定义了一个枚举类型calendar_unit，包含days和months两个值。通过PostGraphile自动生成的GraphQL schema中，这个枚举类型被转换为：

enum CalendarUnit {
  DAYS
  MONTHS
}

在客户端查询时，可以正常使用大写的枚举值（如DAYS）作为输入。然而，当开发者在插件中通过loadOne方法访问fieldArgs参数时，发现接收到的枚举值变成了小写形式（如days），这与GraphQL JSON序列化规则不一致。

技术原理

这个问题实际上涉及到GraphQL规范中枚举值的"内部表示"和"外部表示"概念：

1. 内部表示：枚举值的真实存储形式，在PostgreSQL中就是days和months这样的字符串
2. 外部表示：通过GraphQL暴露给客户端的名称，遵循GraphQL命名规范（通常为大写）

这种设计有几个重要原因：

1. 数据库中的枚举值可能不符合GraphQL的命名规范
2. 保持与底层数据源的一致性
3. 允许在不同层之间进行值转换

解决方案

对于需要在插件中获取枚举值外部表示的场景，可以通过类型系统进行转换。以下是核心解决方案：

function uncoerce(type: GraphQLInputType, coercedValue: any): any {
  if (type instanceof GraphQLNonNull) {
    return uncoerce(type.ofType, coercedValue);
  } else if (coercedValue === undefined) {
    return undefined;
  } else if (coercedValue === null) {
    return null;
  } else if (type instanceof GraphQLList) {
    return [...coercedValue].map((item) => uncoerce(type.ofType, item));
  } else if (type instanceof GraphQLInputObjectType) {
    return Object.fromEntries(
      Object.entries(coercedValue).map(([fieldName, value]) => [
        fieldName,
        uncoerce(type.getFields()[fieldName].type, value),
      ]),
    );
  } else if (type instanceof GraphQLEnumType) {
    const v: any = type
      .getValues()
      .find((enumValue) => enumValue.value === coercedValue);
    return v?.name ?? null;
  } else if (type instanceof GraphQLScalarType) {
    return coercedValue;
  } else {
    const never: never = type;
    throw new Error(`Unexpected type ${never}`);
  }
}

这个函数递归地处理各种GraphQL输入类型，特别针对枚举类型，通过查找匹配的内部值来返回对应的外部名称。

实际应用场景

这种转换在以下场景特别有用：

1. GraphQL网关模式：当需要将请求转发到其他GraphQL服务时
2. 请求日志记录：记录客户端实际发送的请求而非内部表示
3. 插件开发：需要与客户端保持一致的枚举值表示

设计考量

Graphile/Crystal项目选择保持与GraphQL.js一致的行为，主要基于以下考虑：

1. 规范一致性：遵循GraphQL规范对输入值的强制转换规则
2. 数据源真实性：保持与PostgreSQL数据库中的真实值一致
3. 灵活性：允许在不同层之间进行值转换和适配

总结

理解GraphQL中枚举值的内部表示与外部表示差异对于开发复杂GraphQL应用和插件至关重要。通过类型系统提供的元信息，开发者可以在需要时进行两种表示形式之间的转换，满足不同场景的需求。Graphile/Crystal项目在这方面的设计与GraphQL规范保持一致，同时提供了必要的工具让开发者能够处理这种转换需求。

在实际开发中，当需要处理GraphQL输入值的原始形式时，建议使用类似上述的uncoerce函数来获取期望的外部表示形式。这种模式不仅适用于枚举值，也可以处理其他GraphQL类型的输入值转换。