Graphile Crystal 项目中如何隐藏特定表和字段

在 Graphile Crystal 项目中，开发者经常需要控制哪些数据库表和字段应该暴露在 GraphQL API 中。本文将详细介绍如何通过行为控制(behavior)来实现这一目标，特别是在从 V4 版本迁移到 V5 版本时的注意事项。

版本差异与迁移要点

在 Graphile Crystal V4 版本中，开发者可以使用 smartTagPlugin 和 omit 标签来隐藏特定的表和字段。然而在 V5 版本中，omit 已被弃用，取而代之的是更灵活的行为控制机制。

V4 版本中典型的隐藏配置如下：

{
  kind: "class",
  match(entity) {
    const klass = entity as PgClass;
    return METADATA_REGEX.test(klass.relname);
  },
  tags: {
    omit: true,
  }
}

V5 版本的行为控制

在 V5 版本中，我们可以使用 behavior 标签来实现相同的功能。以下是对 V4 功能的等效实现：

1. 隐藏整个表：

{
  kind: "class",
  match(entity) {
    const klass = entity as PgClass;
    return METADATA_REGEX.test(klass.relname);
  },
  tags: {
    behavior: "-*", // 使用"-*"表示禁用所有操作
  }
}

2. 隐藏特定字段：

{
  kind: "attribute",
  match(entity) {
    const attribute = entity as PgAttribute;
    return /^_block_range$/.test(attribute.attname);
  },
  tags: {
    behavior: "-*", // 同样使用"-*"来隐藏字段
  }
}

预设配置建议

在实际项目中，建议结合预设配置来统一管理行为控制：

export const preset: GraphileConfig.Preset = {
  extends: [PostGraphileAmberPreset, PgSimplifyInflectionPreset],
  schema: {
    defaultBehavior: "-connection +list -insert -update -delete",
    pgOmitListSuffix: true
  },
  // 其他配置...
};

最佳实践

1. 明确行为控制范围：使用 -* 可以完全隐藏一个表或字段，而更细粒度的控制如 -query -mutation 则可以实现部分隐藏。

2. 正则表达式匹配：对于需要批量处理的表或字段，使用正则表达式可以简化配置。

3. 迁移策略：从 V4 迁移到 V5 时，应逐步替换 omit 为 behavior，并测试每个变更的影响。

通过合理使用行为控制机制，开发者可以精确控制 GraphQL API 的暴露范围，既保证了安全性，又提供了必要的灵活性。