graphql

Crowdin GraphQL 查询编写

使用此技能编写有效的 Crowdin GraphQL 查询，使其符合实时架构、避免使用不受支持的参数，并包含实用的分页和筛选模式。

交付内容

返回：

1. 可运行的 GraphQL 查询。
2. 对其工作方式的简短说明。
3. 如有需要，提供用户错误查询的修正版，并简要说明“问题所在”。
4. 可选：在有助于提高可读性时提供变量对象。

核心工作流程

1) 确认意图和范围

识别：

• 目标资源（项目、字符串、翻译等）。
• 必要的约束条件（语言、日期、状态、用户、审核状态）。
• 用户需要的输出字段。

如果请求含糊不清，请选择保守的默认值并简要说明。

2) 使用符合架构的基本构件

按以下顺序操作：

1. 选择实际提供目标连接的根字段。
2. 为每个连接添加必需的分页参数（first 或 last）。
3. 添加嵌套选择（edges -> node），且仅选择所需字段。
4. 仅在架构支持的情况下添加筛选和排序。

不要类比 REST 参数来臆造参数。

3) 检查常见的 Crowdin GraphQL 约束

完成前请确认：

• 每个查询的连接都包含 first 或 last（1..10000）。
• 估算的请求节点总数不超过 10,000。
• 可能需要分页时，查询包含 pageInfo。
• 查询未对字段使用不受支持的参数。

4) 添加安全的分页模式

优先使用游标分页：

• 向前：first + after
• 向后：last + before

如果用户要求“从日期 X 到日期 Y”，请对提供相应筛选字段的资源使用受支持的 filter 输入，而不要使用临时添加的参数。

需要避免的高风险错误

未知参数错误

如果用户查询包含架构中不存在的字段参数，请使用受支持的替代方案重写查询。

来自实际故障的反面示例：

• translations(..., createdAfter: "...", createdBefore: "...")

修复策略：

1. 移除不受支持的参数。
2. 保留 languageId、first、after 等受支持的参数。
3. 如果需要日期约束，请将其移至提供相应 filter 输入的字段（或说明该字段不直接支持日期筛选）。

缺少必需的分页参数

Crowdin GraphQL 连接需要 first 或 last。切勿省略。

过度获取数据

没有必要时，不要请求庞大的嵌套扇出数据。请合理控制节点数量。

查询模式

模式 A：最简安全连接查询

query GetProjects($first: Int!, $after: String) {
  viewer {
    projects(first: $first, after: $after) {
      edges {
        node {
          id
          name
        }
        cursor
      }
      pageInfo {
        hasNextPage
        endCursor
      }
      totalCount
    }
  }
}

模式 B：筛选 + 排序（支持时）

query FilteredProjects {
  viewer {
    projects(
      first: 10
      filter: { createdAt: { gt: "2023-01-01T00:00:00Z" } }
      order: [{ lastActivityAt: asc }]
    ) {
      edges {
        node {
          id
          name
          lastActivityAt
        }
      }
    }
  }
}

模式 C：注意速率限制

query MeAndCost {
  viewer {
    username
  }
  rateLimit {
    limit
    cost
    remaining
    resetAt
  }
}

调试模板

用户提供错误时，请按以下格式输出：

1. 原因：用一句话指出架构不匹配之处。
2. 修正后的查询：提供完整的修正后查询。
3. 为何可行：提供 2-4 条与架构规则相关的要点。
4. 如果用户要求按日期筛选：说明该字段是否支持日期筛选；如果不支持，请提出最接近的有效替代方案。

语气与安全性

• 正确性优先，不要刻意“耍聪明”。
• 如果不确定架构是否支持，请明确说明“请在 Playground Explorer 中核实此字段”。
• 切勿假装某个参数存在。

参考资料

约束和示例请参照 Crowdin 文档：

• GraphQL API 概览、分页、筛选/排序和限制。
• https://support.crowdin.com/developer/graphql-api/