我们即将与 2019 挥手作别,踏入崭新的 2020。一到年末,各个平台都在整理数据,出具一份属于自己平台的「年度报告」。而对于技术人而言,如果你是一位开源爱好者,GitHub 的年度报告就是你 2019 年的技术总结。
阮一峰老师曾在科技爱好者周刊[1]中提到「数据的力量」:
GitHub 个人页有一个日历栏目,只要当天有代码提交,那一天的小方格就会变成绿色。如果这一年,你每天编码,日历就全是绿的,否则就会有白色的小方块。所有人都可以看到这个「编码日历」。很多人为了让绿色小方格子不要中断,就会尽量每天提交代码。时间一长,真的多做了不少项目。
因此,这次年度报告我想主要针对这份「编码日历」,把你的「编码日历」组装到一张图片上展示给别人。
因为前一段时间正好在学习 GraphQL[2],所以这次将通过 GitHub 的接口 GitHub GraphQL API v4[3] 来获取相关的用户数据。
这份年度报告涉及到的主要技术有:
在开始 Coding 之前需要先梳理一下需求。生成报告的整个流程大致如下:
项目流程图
因此,需要做的事包括:
因为要通过 GitHub GraphQL API v4 获取数据,所以先来聊聊 GraphQL。
官方对于 GraphQL 的定义是:
一种用于 API 的查询语言,是一个使用基于类型系统来执行查询的服务端运行时(类型系统由你的数据定义)。
这样说很抽象,大家可能对 RESTful[6] 比较熟悉些,那么我们就拿 GitHub REST API v3[7] 与 GitHub GraphQL API v4 获取数据的方式做一个简单的对比,GraphQL 的特点自然就一目了然。
以获取用户数据为例,相关接口文档:
对于 RESTful 风格而言,自然是要发起一个 GET
请求。由于我们要获取某个指定用户的数据,所以需要在 PATH 中指定 :username
:
GET /users/:username
请求成功后 GitHub 将会返回以下数据:
{
"login": "octocat",
"id": 1,
"node_id": "MDQ6VXNlcjE=",
"avatar_url": "https://github.com/images/error/octocat_happy.gif",
"gravatar_id": "",
"url": "https://api.github.com/users/octocat",
"html_url": "https://github.com/octocat",
"followers_url": "https://api.github.com/users/octocat/followers",
"following_url": "https://api.github.com/users/octocat/following{/other_user}",
"gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
"starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
"subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
"organizations_url": "https://api.github.com/users/octocat/orgs",
"repos_url": "https://api.github.com/users/octocat/repos",
"events_url": "https://api.github.com/users/octocat/events{/privacy}",
"received_events_url": "https://api.github.com/users/octocat/received_events",
"type": "User",
"site_admin": false,
"name": "monalisa octocat",
"company": "GitHub",
"blog": "https://github.com/blog",
"location": "San Francisco",
"email": "octocat@github.com",
"hireable": false,
"bio": "There once was...",
"public_repos": 2,
"public_gists": 1,
"followers": 20,
"following": 0,
"created_at": "2008-01-14T04:33:35Z",
"updated_at": "2008-01-14T04:33:35Z"
}
但有时我们不需要这么多的数据,我们可能只想获取用户的头像地址。在 RESTful 风格的接口下,我们无法只获取某一条数据,但对于 GraphQL 接口,我们可以发起这样一条请求:
{
user(login: "username") {
avatarUrl
}
}
这样一来,服务端将根据我们请求数据的格式,返回给我们对应的字段,即仅返回 user
下的 avatarUrl
数据:
{
"data":{
"user":{
"avatarUrl":"url"
}
}
}
在 RESTful 中,我们被迫接受服务端已组装好的数据,但 GraphQL 给了我们更多的自由,让我们可以只取所需。
除此之外,RESTful 以资源划分接口,数据之间相对离散,如果想请求不同的资源则需要发起多次请求。而 GraphQL 的数据更具整体性,资源之间以图(即 Graph 名称的由来)的形式彼此关联,一次请求即可获取多种资源。
我想要获取的数据主要有:
根据接口文档 User[8] 与 ContributionsCollection[9] 可知,这些数据都在 user
中,对应的字段如下:
name
followers.totalCount
contributionsCollection.contributionCalendar
contributionDays
color
contributionCount
date
totalContributions
weeks
因此,可以构造出如下 query
:
query = """
{
user(login: "%s") {
followers {
totalCount
}
name
contributionsCollection(
from: "%s",
to: "%s"
) {
contributionCalendar {
totalContributions
weeks {
contributionDays {
color
contributionCount
date
}
}
}
}
}
}
"""% (github_id, begin, end)
构造好 query
后,我们使用 requests
发起请求:
import requests
access_token = "xxx"
# 请求 headers 带上 access_token
headers = {"Authorization": "bearer %s" % access_token}
# 发起请求
response = requests.post(
"https://api.github.com/graphql",
headers=headers,
json={'query': query}
)
若请求成功,GitHub 会返回如下格式的 JSON 数据:
{
"data":{
"user":{
"name":"江不知",
"followers":{
"totalCount":71
},
"contributionsCollection":{
"contributionCalendar":{
"totalContributions":2234,
"weeks":[
{
"contributionDays":[
{
"color":"#c6e48b",
"contributionCount":30,
"date":"2019-01-01"
}
]
}
]
}
}
}
}
}
我主要针对 weeks
做了一些简单的数据统计。主要包括:
contributionCount > 0
)这些数据对 weeks
进行一次遍历即可得出,在此不多做赘述。
作为一个后端开发,真的没有多少设计天赋,说多了都是泪……
整份报告大致分成三个区域:
反反复复改了多版,询问了很多朋友的意见,最后的结果依旧不是很好看……
年度报告设计最终版
报告设计完成以后就可以把最终要展示的数据拼接到报告上了。
在遍历 weeks
统计数据的过程中,可以顺便完成「编码日历」的绘制。
「编码日历」中的每一天就是一个小方块,方块的颜色我们已经从接口返回数据的 color
字段中获取到了。我选择使用 line()
绘制一条颜色为 color
的直线代表方块,把直线的 width
加粗,以获得方块的效果。
from PIL import Image, ImageDraw
# 打开图片
f = open(self.IMAGE_FILE_PATH, 'rb')
image = Image.open(f)
# 创建一个 draw 实例
drawImage = ImageDraw.Draw(image)
# 遍历每周数据
for week in weeks:
# 遍历每日数据
for day in week['contributionDays']:
# 取出当天的颜色
color = day['color']
# 绘制直线
drawImage.line([(x_point, y_point), (x_point + square_width, y_point)], fill=color, width=square_width)
# 改变下一个方格的 y 坐标
y_point += move_width
# 改变下一个方格的 x 坐标
x_point += move_width
# 下一周开始,y 坐标恢复原处
y_point = y_begin
报告的其他部分就主要是文字内容了,设置好字体、颜色等,使用 text()
在指定位置贴上文字。
from PIL import ImageFont
font_size = 60
# 设置字体与字号
font = ImageFont.truetype("./font/fzlt.ttf", font_size)
font_color = "#F7FFF7"
# 设置坐标
x, y = 0
# 在图片写上文字
draImage.text((x, y), "要显示的文字", fill=font_color, font=font)
公众号方面直接使用了开发框架 WeRoBot[10]。
设定:当用户发送信息为「2019 $github_id」时触发生成年度报告。
import werobot
robot = werobot.WeRoBot(token='token')
# 回复包含指定文本的信息
@robot.filter(re.compile("2019(\s)+(.*)?"))
def annual_report(message, session, match):
if match:
# do something...
生成年度报告后,我们使用微信的新增临时素材[11]接口上传报告图片,并获取到临时素材的编号 media_id
:
from werobot.client import Client
config = {
"APP_ID": "app_id",
"APP_SECRET": "app_secret"
}
client = Client(config)
# 上传临时素材
response = client.upload_media('image', image) # image 为生成的报告图片
# 获取临时素材 ID
media_id = response['media_id']
然后,我们再将这一图片信息返回给用户:
from werobot.replies import ImageReply
# 要返回的图片数据
reply = ImageReply(message=message, media_id=media_id)
return reply
当用户在公众号发送 2019+空格+github_id
时,将返回 github_id
所对应的报告。最终生成的报告如下:
我的 2019 GitHub 年度报告
源码见 GitHub 仓库:https://github.com/JalanJiang/2019-github-annual-report
接入的服务器为辣鸡配置,还请各位大佬手下留情。
整个过程涉及到微信公众号和 GitHub 接口的调用,用户从输入到数据返回需要等待几秒的时间。为了避免超时的尴尬情况,这里只对用户提交记录做了简单的分析。
在完成这个项目的过程中几度因为设计出的报告太丑而想要放弃,感谢几位朋友一直鼓励我、给我提出修改意见才让我坚持了下来。
2019 年再见啦,希望 2020 年能尝试更多有趣的事。:)
[1]
科技爱好者周刊: https://www.ruanyifeng.com/blog/2019/09/weekly-issue-73.html
[2]
GraphQL: https://graphql.cn/
[3]
GitHub GraphQL API v4: https://developer.github.com/v4/
[4]
requests: https://2.python-requests.org//zh_CN/latest/user/quickstart.html
[5]
PIL: https://github.com/python-pillow/Pillow
[6]
RESTful: https://www.ruanyifeng.com/blog/2011/09/restful.html
[7]
GitHub REST API v3: https://developer.github.com/v3/
[8]
User: https://developer.github.com/v4/object/user/
[9]
ContributionsCollection: https://developer.github.com/v4/object/contributionscollection/
[10]
WeRoBot: https://github.com/offu/WeRoBot
[11]