proj-dash-backend/GITHUB_API_FEASIBILITY.md

GitHub Dashboard API 可行性分析报告

📊 功能模块 vs GitHub API 支持情况

---

1. 仓库概览卡片区

✅ 完全支持

功能	API 端点	返回数据
基本信息	GET /repos/{owner}/{repo}	仓库名、描述、创建时间
Star/Fork/Watch 数量	GET /repos/{owner}/{repo}	stargazers_count, forks_count, watchers_count
语言分布	GET /repos/{owner}/{repo}/languages	{ "JavaScript": 12345, "Python": 6789 }
License	GET /repos/{owner}/{repo}	license.name, license.key
Topics	GET /repos/{owner}/{repo}/topics	标签数组
最后更新时间	GET /repos/{owner}/{repo}	updated_at, pushed_at
仓库大小	GET /repos/{owner}/{repo}	size (KB)
开源评分	-	❌ 不支持，需自行计算

实现建议：

• 开源评分可通过组合多个指标计算（Star 数量、贡献者数量、更新频率、文档完整性等）

---

2. 活动时间线 (Activity Timeline)

⚠️ 部分支持（有限制）

功能	API 端点	数据可用性	限制
最近 commits	GET /repos/{owner}/{repo}/commits	✅ 支持	分页限制，最多 100/页
最近 PRs	GET /repos/{owner}/{repo}/pulls	✅ 支持	可过滤状态（open/closed/all）
最近 Issues	GET /repos/{owner}/{repo}/issues	✅ 支持	Issues 和 PRs 混合返回
每日/每周提交热力图	GET /repos/{owner}/{repo}/stats/commit_activity	✅ 支持	仅最近 52 周
贡献者活跃度趋势	GET /repos/{owner}/{repo}/stats/contributors	✅ 支持	<10k commits 仓库

API 示例：

# 提交活动（按周统计）
GET /repos/{owner}/{repo}/stats/commit_activity
# 返回：[{ "days": [0,3,5,2,1,0,0], "total": 11, "week": 1302508800 }]

# 贡献者统计
GET /repos/{owner}/{repo}/stats/contributors
# 返回：[{ "author": {...}, "total": 135, "weeks": [...] }]

⚠️ 重要限制：

• 统计数据需要缓存，首次请求返回 202 Accepted，需要等待后台计算
• 超过 10,000 commits 的仓库无法获取详细统计

---

3. 代码统计面板

⚠️ 有限支持

功能	API 端点	数据可用性	限制
语言分布饼图	GET /repos/{owner}/{repo}/languages	✅ 支持	返回字节数，非百分比
代码量趋势	GET /repos/{owner}/{repo}/stats/code_frequency	⚠️ 有限	仅周级别统计，<10k commits
文件结构	GET /repos/{owner}/{repo}/git/trees/{tree_sha}?recursive=1	✅ 支持	需遍历 tree SHA
热点文件（最常修改）	-	❌ 不支持	需自行分析 commits

代码频率 API：

GET /repos/{owner}/{repo}/stats/code_frequency
# 返回：[[1302508800, 1124, -435], ...]  # [周时间戳, 新增行, 删除行]

实现建议：

• 热点文件需要自己爬取所有 commits，分析每个文件的修改频次
• 文件结构可以通过 Git Trees API 递归获取

---

4. Issue/PR 管理看板

✅ 完全支持

功能	API 端点	返回数据
状态分布	GET /repos/{owner}/{repo}/issues?state=all	Open/Closed 数量
优先级标签云	GET /repos/{owner}/{repo}/labels	所有标签及颜色
响应时间	GET /repos/{owner}/{repo}/issues	created_at, closed_at
Issue 时间线	GET /repos/{owner}/{repo}/issues/{issue_number}/timeline	完整事件历史
PR 审查状态	GET /repos/{owner}/{repo}/pulls/{pull_number}/reviews	审查状态和评论

API 示例：

# 获取所有 Issues（包含 PRs）
GET /repos/{owner}/{repo}/issues?state=all&per_page=100

# 区分 Issue 和 PR
if (issue.pull_request) { /* 这是 PR */ }

# 获取 Issue 时间线
GET /repos/{owner}/{repo}/issues/1/timeline
# 返回：创建、关闭、标签变更、评论等事件

计算响应时间：

• 平均关闭时间 = closed_at - created_at 的平均值
• 首次响应时间 = 第一条评论时间 - 创建时间

---

5. 贡献者分析

⚠️ 部分支持（有性能限制）

功能	API 端点	数据可用性	限制
核心贡献者榜单	GET /repos/{owner}/{repo}/contributors	✅ 支持	按提交数排序
贡献者头像墙	GET /repos/{owner}/{repo}/contributors	✅ 支持	包含 avatar_url
提交量/增删行数	GET /repos/{owner}/{repo}/stats/contributors	⚠️ 有限	<10k commits
新老贡献者比例	GET /repos/{owner}/{repo}/stats/contributors	⚠️ 有限	需自行分析
协作网络图	-	❌ 不支持	需分析 commits 的 co-authors

Contributors API：

# 获取贡献者列表
GET /repos/{owner}/{repo}/contributors
# 返回：[{ "login": "user", "contributions": 123, "avatar_url": "..." }]

# 获取详细统计（需等待缓存）
GET /repos/{owner}/{repo}/stats/contributors
# 返回：[{ "author": {...}, "total": 135, "weeks": [{ "w": 1302508800, "a": 6898, "d": 77, "c": 10 }] }]

⚠️ 限制：

• GraphQL API 不支持获取贡献者，必须用 REST API
• 协作网络图需要自己分析 Git 的 Co-authored-by 标记

---

6. Release & 版本管理

✅ 完全支持

功能	API 端点	返回数据
版本时间轴	GET /repos/{owner}/{repo}/releases	所有 releases
最新 Release	GET /repos/{owner}/{repo}/releases/latest	最新版本信息
按标签获取	GET /repos/{owner}/{repo}/releases/tags/{tag}	指定版本
更新日志	POST /repos/{owner}/{repo}/releases/generate-notes	自动生成 Changelog
下载统计	GET /repos/{owner}/{repo}/releases/{id}	每个 asset 的 download_count

Release API 示例：

# 获取所有 releases
GET /repos/{owner}/{repo}/releases
# 返回：[{ "tag_name": "v1.0.0", "name": "Release 1.0", "assets": [...] }]

# 每个 asset 包含下载统计
{
  "name": "app.zip",
  "download_count": 12345,
  "size": 9876543,
  "created_at": "2023-01-01T12:00:00Z"
}

# 自动生成 Changelog
POST /repos/{owner}/{repo}/releases/generate-notes
{
  "tag_name": "v1.0.0",
  "previous_tag_name": "v0.9.0"
}

---

7. 依赖关系可视化

⚠️ 仅 GraphQL 支持

功能	API 端点	数据可用性	限制
依赖树	GraphQL dependencyGraphManifests	⚠️ 仅 GraphQL	REST API 不支持
安全漏洞	GraphQL vulnerabilityAlerts	⚠️ 仅 GraphQL	需启用 Dependabot
更新提醒	GraphQL dependabot	⚠️ 仅 GraphQL	-

GraphQL 查询示例：

query {
  repository(owner: "facebook", name: "react") {
    dependencyGraphManifests {
      edges {
        node {
          filename
          dependencies {
            edges {
              node {
                packageName
                requirements
                hasDependencies
              }
            }
          }
        }
      }
    }
    vulnerabilityAlerts(first: 10) {
      edges {
        node {
          securityVulnerability {
            package {
              name
            }
            severity
            advisory {
              summary
            }
          }
        }
      }
    }
  }
}

⚠️ 限制：

• 必须使用 GraphQL API，REST API 无此功能
• 需要仓库启用 Dependency Graph 和 Dependabot
• 私有仓库需要 repo 权限

---

8. CI/CD 状态监控

✅ 完全支持

功能	API 端点	返回数据
工作流列表	GET /repos/{owner}/{repo}/actions/workflows	所有 workflows
工作流运行状态	GET /repos/{owner}/{repo}/actions/runs	运行历史
特定工作流的运行	GET /repos/{owner}/{repo}/actions/workflows/{id}/runs	特定 workflow 的运行
运行详情	GET /repos/{owner}/{repo}/actions/runs/{run_id}	状态、结论、时长
任务详情	GET /repos/{owner}/{repo}/actions/runs/{run_id}/jobs	每个 job 的状态
使用统计	GET /repos/{owner}/{repo}/actions/workflows/{id}/timing	⚠️ 已废弃

GitHub Actions API：

# 获取工作流运行历史
GET /repos/{owner}/{repo}/actions/runs
# 返回：{
#   "workflow_runs": [{
#     "id": 123,
#     "status": "completed",
#     "conclusion": "success",
#     "run_started_at": "2023-01-01T10:00:00Z",
#     "updated_at": "2023-01-01T10:05:30Z"
#   }]
# }

# 计算运行时长
duration = updated_at - run_started_at

构建成功率计算：

const runs = await fetch('/repos/owner/repo/actions/runs')
const successRate = runs.filter((r) => r.conclusion === 'success').length / runs.length
const avgDuration =
  runs.reduce((sum, r) => sum + (r.updated_at - r.run_started_at), 0) / runs.length

---

9. 流量统计 (Traffic)

⚠️ 有严重限制

功能	API 端点	数据可用性	限制
页面访问量	GET /repos/{owner}/{repo}/traffic/views	⚠️ 有限	仅 14 天
Clone 统计	GET /repos/{owner}/{repo}/traffic/clones	⚠️ 有限	仅 14 天
Top Referrers	GET /repos/{owner}/{repo}/traffic/popular/referrers	⚠️ 有限	仅 14 天
Top Paths	GET /repos/{owner}/{repo}/traffic/popular/paths	⚠️ 有限	仅 14 天
历史流量	-	❌ 不支持	-

❗ 严重限制：

• GitHub 仅保留 14 天的流量数据
• 无法获取历史流量统计
• 必须定期轮询并自行存储才能构建历史趋势图

解决方案：

1. 使用 GitHub Actions 每天自动抓取数据存入数据库
2. 参考开源项目：github-repo-stats

---

10. Star 历史趋势

⚠️ 有分页限制

功能	API 端点	数据可用性	限制
Stargazers 列表	GET /repos/{owner}/{repo}/stargazers	✅ 支持	最多 40k stars
Star 时间戳	使用 header Accept: application/vnd.github.star+json	✅ 支持	最多 40k stars

获取 Star 时间戳：

curl -H "Accept: application/vnd.github.star+json" \
  https://api.github.com/repos/facebook/react/stargazers?per_page=100&page=1

# 返回：[{ "starred_at": "2023-01-01T12:00:00Z", "user": {...} }]

⚠️ 限制：

• 每页最多 100 个，最多 400 页 = 40,000 stars
• 超过 40k stars 的仓库无法获取完整历史

---

📋 API 限制总结

Rate Limits（速率限制）

认证方式	速率限制
未认证	60 次/小时
OAuth Token	5,000 次/小时
GitHub App	15,000 次/小时

数据限制

数据类型	限制
统计数据（stats）	仅 <10,000 commits 的仓库
流量数据（traffic）	仅 14 天
Star 历史	最多 40,000 个
分页	每页最多 100 条
Contributors	GraphQL 不支持，必须用 REST

---

✅ 推荐实现方案

核心功能（完全支持）

1. ✅ 仓库概览卡片
2. ✅ Issue/PR 管理看板
3. ✅ Release 版本管理
4. ✅ CI/CD 状态监控

需要定期采集数据

5. ⚠️ 流量统计（每天爬取一次，存入数据库）
6. ⚠️ Star 历史（定期更新）

需要混合使用 REST + GraphQL

7. ⚠️ 依赖关系可视化（GraphQL）
8. ⚠️ 安全漏洞（GraphQL）

需要自行计算/分析

9. 📊 开源评分（组合多个指标）
10. 📊 热点文件分析（分析 commits）
11. 📊 协作网络图（分析 co-authors）

---

🚀 技术栈建议

后端

• REST API: 使用 Octokit (@octokit/rest)
• GraphQL: 使用 @octokit/graphql
• 定时任务: GitHub Actions + Cron
• 缓存: Redis（缓存 stats 数据，避免 202 响应）

前端

• 图表库: Recharts / D3.js / Apache ECharts
• 热力图: react-calendar-heatmap
• 网络图: react-force-graph / cytoscape.js
• 时间线: react-vertical-timeline

---

📌 注意事项

1. 统计数据可能需要等待：首次请求返回 202，需要轮询直到返回 200
2. 流量数据必须自行存储：否则 14 天后数据丢失
3. 大型仓库限制多：>10k commits 的仓库很多统计不可用
4. GraphQL 和 REST 混用：依赖图必须用 GraphQL，其他用 REST 更方便
5. 速率限制：建议使用 GitHub App 获取更高的速率限制

---

🔗 参考文档

• GitHub REST API 文档
• GitHub GraphQL API 文档
• Octokit.js 官方文档
• GitHub Actions API