跳到主要内容

指标使用指南

基本使用

OpenDigger 实现的所有指标对所有人开放使用,OpenDigger 的静态数据根链接为:

https://oss.open-digger.cn/{platform}/{org/login}/{repo}/

其中 platform 目前支持 githubgitee,只需要替换 org/repo 或用户 login 即可获取数据。

以下是一份完整的指标数据清单,您可以前往 Playground 页面试用数据,或对于具体数据,前往相应文档页面查看详情。

OpenRank
统计指标
开发者
问题
变更请求

数据结构

对于所导出的指标文件,其基本数据结构为一个 JSON 对象,其键值为月度、季度、年度值,对应的数值为指标数据。

  • 月度键值形式为 YYYY-MM
  • 季度键值形式为 YYYYQXX 取值范围为 1 至 4,Q1 为当年 1 至 3 月,Q2 为当年 4 至 6 月,以此类推。
  • 年度键值形式为 YYYY

所有键值均在顶层结构中,按照年度、月度、季度的顺序排列,每类中按时间先后顺序排列。

例如,对于 OpenDigger 仓库,其全域 OpenRank 影响力数据为:

{
"2020":34.81,"2021":55.59,"2022":92.97,... // 年度数据
"2020-08":4.91,"2020-09":5.17,"2020-10":5.1,... // 月度数据
"2020Q3":10.08,"2020Q4":24.73,"2021Q1":22.18,... // 季度数据
}

由于 OpenDigger 的 GitHub 数据源存在时段数据缺失的情况,因此若键值中存在 2021-10-raw,则该值为指标数据的原始值。为了使得指标数据具有时序上的连续性,对应的 2021-10 指标值为前后各两个月的插值结果,具体代码参见这里

导出范围

OpenDigger 并未为全域所有仓库和用户均导出指标数据,具体导出的仓库和开发者列表可分别在 repo_list.csvuser_list.csv 文件中查询,其中:

  • repo_list.csv 的行结构为 id,platform,repo_name,即使用,分隔的仓库数据库 ID、平台名称和仓库全称。
  • user_list.csv 的行结构为 id,platform,login,即使用,分隔的用户数据库 ID、平台名称和用户登录名。

其中数据库 ID 为对应平台中的唯一 ID,与各平台的数据一致,平台名与数据库 ID 共同唯一标识一个仓库或开发者

关于 OpenDigger 的导出策略,请参考开发者文档中导出表的部分。

OpenDigger 官网页面中各类仓库和开发者搜索组件使用这两个文件实现浏览器本地搜索。

元数据

对于导出的仓库和开发者,OpenDigger 会同时导出一份元数据,其地址为:

仓库:https://oss.open-digger.cn/{platform}/{org/login}/meta.json示例

开发者:https://oss.open-digger.cn/{platform}/{org/login}/{repo}/meta.json示例

元数据中包含如下字段:

  • updatedAt:数据更新时间。
  • type:仓库或开发者类型,值是 repouser
  • id:仓库或开发者在平台数据库中的 ID。
  • labels:仓库或开发者在 OpenDigger 中所属标签。关于该字段,请参考标签数据相关文档。

例如,对于 OpenDigger 仓库,其元数据为:

{
"updatedAt": 1725221391661, // 更新时间时间戳
"type": "repo", // 元数据类型
"id": 288431943, // 仓库在 GitHub 中的唯一 ID
"labels": [ // 仓库所属标签
{
"id": ":communities/mulan", // 木兰社区
"name": "Mulan",
"type": "Community"
},
{
"id": ":communities/xlab", // X-lab 社区
"name": "X-lab",
"type": "Community"
},
{
"id": ":communities/xlab/open_digger", // OpenDigger 项目
"name": "OpenDigger",
"type": "Project"
},
{
"id": ":regions/CN", // 中国项目
"name": "China",
"type": "Region"
}
]
}

FAQ

问:OpenDigger 指标数据是否支持在其他应用中集成?

答:是的,OpenDigger 指标数据非常欢迎下游应用集成。OpenDigger 对于导出的静态数据,在响应头中加入了 Access-Control-Allow-Origin: *,从而保证数据可以被跨域使用。如果您的网站对于响应头中的域名有强要求,可能需要自己实现服务以进行数据转发。事实上 OpenDigger 数据已有大量下游应用,例如 HyperCRX、OpenLeaderboard、OSGraph 等。

问:应用使用指标数据是否需要自己做缓存策略?

答:浏览器应用可以直接使用数据而不做缓存。OpenDigger 对于指标数据,在响应头中加入了 Expires 字段,每月更新后直到次月 2 日之前,浏览器可以通过该字段判断直接从浏览器磁盘缓存中获取数据,而无需重复获取远程数据。

问:在访问某指标文件时不存在可能是什么问题导致的?

答:如果在访问某个数据指标文件不存在,可能是如下原因导致的:

  • 该仓库或开发者不在导出范围内,可以通过访问元数据确定仓库或开发者是否在导出范围内,若元数据存在则数据已导出。
  • 该仓库没有对应的事件类型。例如 Apache 某些项目不使用 GitHub Issues 功能(如 Flink),因此将不存在问题类相关的指标文件。

问:指标文件中的键值为什么可能缺失某些特定的月份或季度?

答:若某仓库或开发者在某时段内不存在某类事件,则对应指标数据中的时段键值将不存在,而指标数据中不会出现 0 值,因此在指标数据中键值可能出现不连续的情况。