04 - GitHub API 文档研究笔记

创建日期：2026-04-28
用途：Github 动态模块开发参考，记录 GitHub REST API 与 GraphQL API 的关键接口和使用方式
REST API 版本：2022-11-28
文档地址：https://docs.github.com/zh/rest
GraphQL 文档：https://docs.github.com/zh/graphql

认证方式

Authorization: Bearer <GITHUB_TOKEN>
Accept: application/vnd.github+json
X-GitHub-Api-Version: 2022-11-28
User-Agent: kaiwen.work/1.0

• Token 类型：Fine-grained PAT（github_pat_ 前缀）
• Token 存放：config.inc.php → define('GITHUB_PUBLIC_TOKEN', '...')（已在 .gitignore，不提交 git）
• 无认证速率：60 次/小时；有认证速率：5000 次/小时

Fine-grained PAT 注意事项

• 创建时 Repository access 选 All repositories（选具体仓库会导致跨仓库公开 API 调用 403）
• Permissions 最小权限：Metadata: Read-only 即可满足本项目所有只读需求
• 访问私有仓库列表额外需要：Contents: Read-only

Base URL

REST:     https://api.github.com
GraphQL:  https://api.github.com/graphql

活动（Activity）相关接口

获取用户公开事件流

GET /users/{username}/events?per_page=15

• 返回用户最近操作的公开事件，不包含私有仓库事件
• 即使携带认证 token，私有仓库 Push 等事件也不出现
• 事件最多保留 90 天，最多返回 300 条

事件对象结构：

{
  "id": "22249084964",
  "type": "PushEvent",
  "actor": { "login": "kxue4", "avatar_url": "..." },
  "repo": { "name": "kxue4/kaiwen.work", "url": "..." },
  "payload": { ... },
  "public": true,
  "created_at": "2026-04-27T08:30:00Z"
}

支持的事件类型及 payload 关键字段：

仓库（Repos）相关接口

获取认证用户的仓库列表（含私有）

GET /user/repos?sort=updated&per_page=6&affiliation=owner

• 必须携带认证 token，否则只返回公开仓库
• affiliation=owner 只返回自己创建的仓库（排除协作仓库）
• sort=updated 按最近更新时间排序

响应关键字段：

{
  "name": "kaiwen.work",
  "full_name": "kxue4/kaiwen.work",
  "description": "My personal website",
  "private": true,
  "language": "PHP",
  "stargazers_count": 0,
  "html_url": "https://github.com/kxue4/kaiwen.work",
  "updated_at": "2026-04-27T08:30:00Z"
}

获取用户公开仓库（无需认证）

GET /users/{username}/repos?sort=updated&per_page=6

• 只返回公开仓库，不含私有

GraphQL API

获取贡献热力图

POST https://api.github.com/graphql

{
  user(login: "kxue4") {
    contributionsCollection(from: "2026-03-29T00:00:00Z", to: "2026-04-28T23:59:59Z") {
      contributionCalendar {
        totalContributions
        weeks {
          contributionDays {
            contributionCount
            date
          }
        }
      }
    }
  }
}

• from / to：ISO8601 格式，支持任意时间范围
• contributionDays 数据按周组织，需展开为扁平数组使用
• 贡献统计包括：commit、PR、issue、code review

PHP 调用方式：

$payload = json_encode(['query' => $query]);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json', ...]);

速率限制

本项目每次刷新调用 3 次 API（GraphQL×1 + REST×2），配合 5 分钟缓存，每小时最多触发 12 次，远低于限制。

常用 curl 调用示例

TOKEN="your_token_here"

# 获取用户事件流
curl -s -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/vnd.github+json" \
  "https://api.github.com/users/kxue4/events?per_page=15"

# 获取认证用户仓库
curl -s -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/vnd.github+json" \
  "https://api.github.com/user/repos?sort=updated&per_page=6&affiliation=owner"

# GraphQL 贡献热力图
curl -s -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  https://api.github.com/graphql \
  -d '{"query":"{ user(login: \"kxue4\") { contributionsCollection(from: \"2026-03-29T00:00:00Z\", to: \"2026-04-28T23:59:59Z\") { contributionCalendar { totalContributions weeks { contributionDays { contributionCount date } } } } } }"}'

# 验证 token 有效性
curl -s -H "Authorization: Bearer $TOKEN" https://api.github.com/user | python3 -m json.tool | grep login

已知限制与注意事项

1. 私有仓库事件不可见：/users/{username}/events 即使有 token 也不返回私有仓库活动，这是 GitHub 的设计行为
2. Fine-grained PAT 作用域：Token 绑定具体仓库时，调用其他仓库的公开接口可能返回 403，建议设置为 All repositories
3. GraphQL 无匿名访问：GraphQL 端点必须携带认证 token
4. 贡献计数口径：GitHub 贡献图只统计默认分支的 commit、PR merge、issue open/close、code review，fork/star 不计入