top-github-users-ref

# top-github-users 架構參考 + 社群回饋 ## 資料抓取管線（從原始碼分析） ### 搜尋策略 - **GraphQL Search API**（非 REST）— 使用 `search(type: USER)` 查詢 - **所有 locations 合併成一個 query** — `location:Taiwan location:Taipei sort:followers-desc` - **Cursor-based 分頁** — 用 `hasNextPage` + `endCursor` 遍歷所有結果，不限固定頁數 - **每頁 10 筆**（`first: 10`），透過 cursor 持續取得直到沒有下一頁 ### 單次 GraphQL 取得所有欄位 一次查詢即取得：`login`、`avatarUrl`、`name`、`location`、`company`、`twitterUsername`、`followers.totalCount`、`contributionsCollection.contributionCalendar.totalContributions`、`contributionsCollection.restrictedContributionsCount` **重點**：不需要逐人打 REST API 取 profile，效率遠高於 REST Search + 逐人 REST profile + 逐人 GraphQL contributions 的三步驟做法。 ### Rate Limit 策略 - **隨機延遲 1-5 秒** — 每頁請求之間加入 `randomIntFromInterval(1000, 5000)` 延遲 - **錯誤重試** — 失敗時等待 60 秒，最多容許 4 次錯誤（`MAXIMUM_ERROR_ITERATIONS`）後停止 - **Checkpoint 機制** — 每次 cron 只處理一個國家（checkpoint），避免一次跑完所有國家撞 rate limit ### 資料保護 - **最低 750 筆保護** — 如果新抓的結果比快取少，且低於 750 筆，視為 API 錯誤，不覆蓋快取 - **快取機制** — 每個國家有獨立 cache 檔案，只在確認資料品質後才覆蓋 ### 排序與排名 - 搜尋時依 `followers-desc` 排序 - 產出三種排名：Public Contributions、Total Contributions、Followers ## 與我們的差異比較 | 面向 | gayanvoice | CodeAtlas（目前） | |------|-----------|------------------| | 搜尋 API | GraphQL `search(type: USER)` | REST `search/users` | | 每人 API calls | 1（GraphQL 包含全部欄位） | 3（REST search + REST profile + GraphQL contributions） | | 分頁 | Cursor-based，無上限 | Page-based，上限 10 頁 × 100 = 1000 | | Rate limit | 隨機延遲 1-5s + 錯誤等待 60s | Octokit throttle plugin | | 處理單位 | 一次 cron 跑一個國家（checkpoint） | 一次 cron 跑所有國家（逐國 commit） | | 快取保護 | 有（750 筆最低門檻） | 無 | ## 已知問題（從 Issues 學到的） ### Location 歧義問題（最嚴重） - **Georgia（美國州）vs Georgia（國家）** — #291 - **Granada（西班牙城市）vs Granada（尼加拉瓜）** — #287 - **解決方案**：搜尋時加排除條件，如 `location:Georgia NOT location:"Georgia, US"` 或事後用 country code 過濾 ### Emoji Flag Location — #279 - 有些使用者的 location 設為 flag emoji 如 🇹🇼 - **解決方案**：regex 偵測 flag emoji 並 mapping 到國家 ### Contribution 計算不準 — #281 #295 - GraphQL `totalContributions` 和使用者看到的數字可能不同 - 原因：private repo contributions 計算差異 - **接受此限制**，清楚說明我們的計算方法 ### Username 變更 — #123 - 使用者改名後舊資料不更新 - **解決方案**：每次 cron 重新抓取，不依賴快取的 username ### 使用者遺漏 — #222 #198 - 不理解為何沒被列入 - **解決方案**：建立 FAQ 頁面說明：需要設定 location、需要有足夠 followers/contributions ## 社群最想要的功能 1. **更頻繁更新**（weekly 以上）— 他們的 pipeline 壞了導致資料非常舊 2. **Profile info + top repos** — 目前只有 table，沒有個人資訊 3. **Star-based ranking** — 依總 star 數排名 4. **GitHub Pages 呈現** — 不只是 markdown 檔案 5. **容易新增國家/城市** — 目前需要 PR 改 config.json ## 我們的優勢 | 面向 | top-github-users | CodeAtlas | |------|-------------------|---------| | 呈現 | Markdown 表格 | GitHub Pages 網站 | | 個人資料 | 無 | 語言、repos、bio、social | | 搜尋/過濾 | 無 | 語言/城市/搜尋 | | 更新頻率 | 壞了（~195 天一輪） | 每週 cron | | 新增國家 | 需 PR 改 config.json | 加一個 JSON 檔 | | Theme | 無 | Dark/Light toggle | | 分享 | 有社群按鈕 | 有社群按鈕 + OG image | | 3D | 無 | Globe 地球 |