Github GRAPHQL

GitHub GraphQL API Best Practices Guide

Rate Limiting（Points 系統）

GitHub GraphQL API 使用 points 系統，不是 REST 的 request count。

Primary Rate Limits

Secondary Rate Limits（每分鐘）

Secondary limit 的計算不同於 primary：

• Query（無 mutation）：1 point
• Query with mutation：5 points

查詢 Rate Limit 狀態

import { graphql } from "@octokit/graphql";

const graphqlWithAuth = graphql.defaults({
  headers: { authorization: `token ${process.env.GITHUB_TOKEN}` },
});

const { rateLimit } = await graphqlWithAuth<{
  rateLimit: { limit: number; cost: number; remaining: number; resetAt: string };
}>(`
  query {
    rateLimit {
      limit
      cost
      remaining
      resetAt
      nodeCount
    }
  }
`);

console.log(`Cost: ${rateLimit.cost}, Remaining: ${rateLimit.remaining}`);

Response headers 也有：

• x-ratelimit-limit：最大 points/hr
• x-ratelimit-remaining：剩餘 points
• x-ratelimit-used：已用 points
• x-ratelimit-reset：重置時間（UTC epoch）

Query Cost 計算

公式：加總每個 connection 需要的 requests，每個 request 假設達到 first/last 上限，除以 100 後取最近整數，最低 1 point。

範例

query {
  search(query: "location:Taiwan", type: USER, first: 100) {  # 100/100 = 1
    nodes {
      ... on User {
        repositories(first: 10) {  # 100 * 10 / 100 = 10
          nodes { name }
        }
      }
    }
  }
}
# 總 cost = 1 + 10 = 11 points

最佳化原則：減少巢狀 connection 的 first 值可大幅降低 cost。

Node Limits

• 單次查詢最多 500,000 nodes
• first/last 值必須在 1–100 之間
• Node 計算方式：各層 connection 的 first/last 相乘
  • 50 repos × 10 issues = 550 nodes（50 + 50×10）

Search API（type: USER）

基本查詢

import { graphql } from "@octokit/graphql";

const graphqlWithAuth = graphql.defaults({
  headers: { authorization: `token ${process.env.GITHUB_TOKEN}` },
});

interface SearchUsersResult {
  search: {
    userCount: number;
    pageInfo: { hasNextPage: boolean; endCursor: string | null };
    nodes: Array<{
      login: string;
      name: string | null;
      followers: { totalCount: number };
      repositories: { totalCount: number };
      contributionsCollection: {
        contributionCalendar: { totalContributions: number };
      };
    }>;
  };
}

const SEARCH_USERS_QUERY = `
  query SearchUsers($query: String!, $first: Int!, $after: String) {
    search(query: $query, type: USER, first: $first, after: $after) {
      userCount
      pageInfo {
        hasNextPage
        endCursor
      }
      nodes {
        ... on User {
          login
          name
          followers { totalCount }
          repositories(ownerAffiliations: OWNER) { totalCount }
          contributionsCollection {
            contributionCalendar { totalContributions }
          }
        }
      }
    }
    rateLimit { cost remaining resetAt }
  }
`;

const result = await graphqlWithAuth<SearchUsersResult>(SEARCH_USERS_QUERY, {
  query: "location:Taiwan followers:>50",
  first: 100,
  after: null,
});

Search Query 語法

• location:Taiwan — 位置
• followers:>100 / followers:50..200 — 追蹤者範圍
• repos:>10 — repo 數
• language:TypeScript — 主要語言
• type:user / type:org — 帳號類型
• created:>2020-01-01 — 建立日期
• 空格 = AND 組合

重要限制：1000 筆結果上限

Search API 硬性限制最多回傳 1000 筆結果，無論 pagination 如何設定。這是 GitHub 後端限制，REST 和 GraphQL 皆然。

突破 1000 限制的策略

// 策略：用 followers 範圍切分查詢
const followerRanges = [
  "followers:>1000",
  "followers:501..1000",
  "followers:201..500",
  "followers:101..200",
  "followers:51..100",
  "followers:21..50",
  "followers:11..20",
  "followers:1..10",
];

async function searchAllUsers(location: string): Promise<User[]> {
  const allUsers: User[] = [];

  for (const range of followerRanges) {
    const query = `location:${location} ${range}`;
    const users = await paginateSearch(query);
    allUsers.push(...users);

    // 如果某個範圍還是 >1000，需要再細分
    if (users.length >= 1000) {
      console.warn(`Range "${range}" hit 1000 cap, needs finer splitting`);
    }
  }

  return deduplicateByLogin(allUsers);
}

自動細分範圍

async function adaptiveSearch(
  location: string,
  minFollowers: number,
  maxFollowers: number,
): Promise<User[]> {
  const query = `location:${location} followers:${minFollowers}..${maxFollowers}`;

  // 先查 userCount
  const { search } = await graphqlWithAuth<SearchUsersResult>(SEARCH_USERS_QUERY, {
    query,
    first: 1,
    after: null,
  });

  if (search.userCount <= 1000) {
    return paginateSearch(query);
  }

  // 超過 1000，二分法細分
  const mid = Math.floor((minFollowers + maxFollowers) / 2);
  const lower = await adaptiveSearch(location, minFollowers, mid);
  const upper = await adaptiveSearch(location, mid + 1, maxFollowers);
  return [...lower, ...upper];
}

Cursor-Based Pagination

完整分頁實作

async function paginateSearch(searchQuery: string): Promise<User[]> {
  const allUsers: User[] = [];
  let cursor: string | null = null;
  let hasNextPage = true;

  while (hasNextPage) {
    const result = await graphqlWithAuth<SearchUsersResult>(SEARCH_USERS_QUERY, {
      query: searchQuery,
      first: 100, // 永遠用最大值 100
      after: cursor,
    });

    const { search, rateLimit } = result as any;

    // 過濾 null nodes（Organization 不符合 User fragment 時會是 null）
    const users = search.nodes.filter((node: any) => node !== null && node.login);
    allUsers.push(...users);

    hasNextPage = search.pageInfo.hasNextPage;
    cursor = search.pageInfo.endCursor;

    // 監控 rate limit
    if (rateLimit.remaining < 100) {
      const resetAt = new Date(rateLimit.resetAt);
      const waitMs = resetAt.getTime() - Date.now() + 1000;
      if (waitMs > 0) {
        console.log(`Rate limit low (${rateLimit.remaining}), waiting ${waitMs}ms`);
        await new Promise((resolve) => setTimeout(resolve, waitMs));
      }
    }
  }

  return allUsers;
}

Pagination 要點

• 永遠用 first: 100：減少 API 呼叫次數
• Forward pagination：first + after + endCursor + hasNextPage
• Backward pagination：last + before + startCursor + hasPreviousPage
• after: null 表示第一頁
• PageInfo 四欄位：endCursor、startCursor、hasNextPage、hasPreviousPage

Batch Queries（批次查詢）

用 Alias 合併多個使用者查詢

function buildBatchUserQuery(logins: string[]): string {
  const fragments = logins.map(
    (login, i) => `
    user${i}: user(login: "${login}") {
      login
      name
      followers { totalCount }
      repositories(ownerAffiliations: OWNER) { totalCount }
      contributionsCollection {
        contributionCalendar { totalContributions }
      }
    }
  `
  );

  return `query BatchUsers {
    ${fragments.join("\n")}
    rateLimit { cost remaining resetAt }
  }`;
}

// 每批最多 ~50 個使用者（避免超過 node limit 和 query 大小限制）
async function batchFetchUsers(logins: string[]): Promise<Map<string, User>> {
  const BATCH_SIZE = 50;
  const results = new Map<string, User>();

  for (let i = 0; i < logins.length; i += BATCH_SIZE) {
    const batch = logins.slice(i, i + BATCH_SIZE);
    const query = buildBatchUserQuery(batch);
    const data = await graphqlWithAuth(query);

    for (let j = 0; j < batch.length; j++) {
      const userData = (data as any)[`user${j}`];
      if (userData) {
        results.set(userData.login, userData);
      }
    }
  }

  return results;
}

Batch Query Cost

Alias 查詢中，每個 user(login:) 是獨立 node request，cost = alias 數量 / 100（最低 1）。比 N 次獨立查詢（N points）便宜很多。

Error Handling

GraphQL Error 結構

import { GraphqlResponseError } from "@octokit/graphql";

interface GraphQLError {
  type: string;          // "RATE_LIMITED" | "NOT_FOUND" | "FORBIDDEN" 等
  message: string;
  path?: string[];
  locations?: Array<{ line: number; column: number }>;
}

async function safeGraphqlQuery<T>(query: string, variables: Record<string, unknown>): Promise<T | null> {
  try {
    return await graphqlWithAuth<T>(query, variables);
  } catch (error) {
    if (error instanceof GraphqlResponseError) {
      // GraphQL 回傳了 data + errors
      const errors = error.errors ?? [];

      for (const err of errors) {
        switch (err.type) {
          case "RATE_LIMITED":
            console.error("Rate limited, waiting...");
            await waitForRateLimit();
            return safeGraphqlQuery<T>(query, variables);

          case "NOT_FOUND":
            console.warn(`Resource not found: ${err.path?.join(".")}`);
            return error.data as T; // partial data 仍可用

          case "FORBIDDEN":
            console.error(`Permission denied: ${err.message}`);
            return null;

          default:
            console.error(`GraphQL error: ${err.type} - ${err.message}`);
        }
      }
    }

    // Network error 或其他
    if ((error as any).status === 502) {
      console.warn("GitHub 502, retrying...");
      await new Promise((r) => setTimeout(r, 2000));
      return safeGraphqlQuery<T>(query, variables);
    }

    throw error;
  }
}

常見錯誤碼

Partial Data 處理

GraphQL 可能回傳 data + errors 同時存在。例如查詢 10 個 user，其中 1 個不存在：

// response.data 有 9 個 user 的資料
// response.errors 有 1 個 NOT_FOUND
// 不要因為 errors 就丟掉全部 data！

Authentication Scopes

本專案需要的最小 scope（Personal Access Token）

Fine-Grained Personal Access Token（推薦）

Fine-grained token 可以更精確控制權限：

• Account permissions > Followers: Read-only
• Repository permissions > Metadata: Read-only

認證設定

import { graphql } from "@octokit/graphql";

// 方式 1：直接設定
const graphqlWithAuth = graphql.defaults({
  headers: {
    authorization: `token ${process.env.GITHUB_TOKEN}`,
  },
});

// 方式 2：透過 Octokit
import { Octokit } from "@octokit/rest";
const octokit = new Octokit({ auth: process.env.GITHUB_TOKEN });
const data = await octokit.graphql(query, variables);

常見陷阱

1. Search 結果硬上限 1000 筆 — 必須用 followers 範圍切分突破
2. first/last 最大 100 — 設超過會 error
3. Node limit 500,000 — 巢狀 connection 相乘容易爆
4. GraphQL rate limit 是 points 不是 requests — 一個複雜 query 可能消耗幾十 points
5. Secondary rate limit 2000 pts/min — 快速連續查詢會觸發
6. Search 回傳 null nodes — type: USER 查詢仍可能包含 Organization，需過濾
7. Partial errors — GraphQL 可能同時回傳 data 和 errors，不要丟掉 partial data
8. userCount 是估計值 — Search API 的 userCount 不一定精確
9. Cursor 不可跨查詢使用 — 每個 search query 的 cursor 獨立
10. Contribution data 需要日期範圍 — contributionsCollection 的 from/to 跨度最多一年

與 Octokit REST 對照