本文只是介绍如何基于 github issues 实现第三方评论系统,对于 Hexo 介绍,本文并不打算详述,如果有童鞋之前还没有了解 Hexo 的,可以先看一下之前文章《静态博客框架 Hexo 入门 》,或者直接访问 Hexo 官网 https://hexo.io/

一、事情起因

个人博客是基于静态博客系统(Hexo)搭建的,本身是没有具备任何后台功能的,例如搜索、评论系统等。但是,如果你想在静态博客上加上评论功能,也不是无法实现的,这时候就要借助第三方评论系统了。

什么是第三方评论系统?博客或 cms 系统,一般都是有内容和评论两部分组成。评论可以增加博主与用户之间的交流互动,也是博主一对多的传达自己想法和观点的交流平台。所以除了社区平台外,评论也成为一般博客和cms系统必备功能。大型网站本身自己开发了评论系统和分享系统,而一般中小型网站开发的自己的评论系统,成本高。而且垃圾评论和过滤非法关键字难度较大,所以在国内外都有第三评论系统。以下是曾经流行或者正在流行的一些第三方评论系统。

  • 多说。多说是一款追求极致体验的社会化评论框,可以用微博、QQ、人人、豆瓣等帐号登录并评论。多说已经成为国内份额最大的所谓“社交评论框”服务,但是这个行业第一并没有给它带来更多的收益和发展空间。不过可惜,现在已经停止服务了。

  • 搜狐畅言。搜狐畅言是由搜狐推出的一个简单而强大的社会化评论及聚合平台。用户可以直接用自己的社会化网络账户在第三方网站发表评论,并且一键评论同步至社交网络将网站内容和自己的评论分享给好友。增加第三方网站用户活跃度,调动好友参与评论,帮助网站实现社会化网络优化,有效提升网站社会化流量。现在还健在。

  • 友言。友言是国内专业的第三方实时社会化评论系统,“完全社交化”可将评论一键同步到各大微博与社区(目前支持10个社交媒体),同时将评论的回复与跟帖同步至使用的网站上,让网站变得更具有活力和社交性,从而为网站带来更多的回访和流量,是一个简单而强大的社会化评论及聚合平台。现在还健在。

  • 网易云跟帖。网易云跟贴是网易公司推出的强大而又简单的评论聚合与分享平台。坑爹的,在多说发布停止服务声明之后不久,网易云跟帖也分出了停止服务声明。

  • Disqus。说到第三放评论系统,当然不得不提国外第三方评论系统界的老大 Disqus,只可惜由于天朝网络原因,Disqus 加载很慢,甚至有时候加载不出来,建议用户自备梯子。

那么回归主题,市面上那么多第三方评论系统,就算有那么一两个挂掉了,还是有很多选择呢,为什么还要自己去做一个呢,这不是造轮子吗?其实,一开始我一直用多说的,用的不亦乐乎,突然有一天说挂就挂了,没办法,那我就选择其他的呗,然后就改成网易云,坑爹的,刚改造好没多久,网易云也挂了。

后面我就在网上找啊找啊,发现居然有人用 GitHub Issue 做了一个评论系统,这无疑是一个很好的想法,很有创意啊。当然,我也拿来用了,但是始终觉得有点丑,跟我自己的博客主题不搭,才用了两天,撤了,打算自己做一个。说干就干,程序员总喜欢造轮子。

二、什么是 GitHub Issues

经常逛 GitHub 的童鞋,都应该知道这个功能,有人理解 GitHub 的 issue 功能,就如同 TODO list。你可以把所有想要在下一步完成的工作,如 feature 添加、bug 修复等,都写成一个个的 issue ,放在上面。既可以作为提醒,也可以统一管理。另外,每一次 commit 都可以选择性的与某个 issue 关联。比如在 message 中添加 #n,就可以与第 n 个 issue 进行关联。具体可以看一下知乎里面别人对 《github issue是做什么的? 》的解答。而本博客的评论数据存储 issues 仓库地址为 https://github.com/jangdelong/blog_comments/issues,仓库里面并没有放置托管代码。总之,像我现在要用 github Issues 来制作评论系统的,其实就是把数据存储到 github issues,简单的说可以把 github issues 理解为一个免费的数据库。

三、评论系统实现

预备工作

  • 创建 OAuth applications。评论需要涉及 GitHub 授权登录,所以在这里你先要有一个 GitHub application。GitHub 授权登录遵循 OAuth 2.0 标准。OAuth applications 创建如下图所示,填写上面相应的内容。

OAuth

Application name:你的站点名称;
Homepage URL:你的站点主页链接;
Application description:站点描述;
Authorization callback URL:GitHub 授权成功后返回地址

创建成功之后会生成一个 Client ID 和一个 Client Secret。

  • GitHub REST API v3

GitHub 提供了很多方便第三方开发的 API,当然,github issues 的增删改查 API 也在其中,有了这些 API,你才能各种施展奇技淫巧,比如我们现在要写的评论系统。另外,有人怀疑我们应不应该“滥用”这些 API,但是,个人觉得,既然,GitHub 提供了这些 API,就是说明要开放给大家这些权限,应该就不怕你“滥用”。那么,要满足我们现在的需求需要哪些 API 呢,下面我列举一下,以我的账号为例,jangdelong 为 Github 名,blog_comments 为仓库名。

GET: https://api.github.com/repos/jangdelong/blog_comments/issues 获取所有issues信息

GET: https://api.github.com/repos/jangdelong/blog_comments/issues/11 获取某个issue下的信息 (11 为 issue 编号 )

GET: https://api.github.com/repos/jangdelong/blog_comments/issues/11/comments 获取某个issue下的评论

GET: https://api.github.com/repos/jangdelong/blog_comments/issues/comments/111/reactions 获取评论 ID 为 111 下的所有 reactions(reactions 包含顶[+1]、踩[-1]、喜欢[heart]等字段)

POST: https://api.github.com/repos/jangdelong/blog_comments/issues 创建一个 issue

POST: https://api.github.com/repos/jangdelong/blog_comments/issues/11/comments 在编号为 11 的 issue 下创建一条评论

POST: https://api.github.com/repos/jangdelong/blog_comments/issues/comments/111/reactions 在 ID 为 111 的评论下创建一条 reactions(如 heart)

POST:https://developer.github.com/v3/markdown/ markdown 语法解析接口

整体设计

流程图:

1
2
3
4
5
6
7
8
9
|--> 显示已登录
|--> 已登录 --> |--> 加载评论列表 --> 分页加载
| |--> 其他
| |--> 评论操作 --> 成功/失败 |
开始 --> GitHub 授权登录 ? --> | |--> 结束
| |--> 显示未登录 |
|--> 未登录 --> |--> 加载评论列表 --> 分页加载
|--> 其他
|--> 评论操作 --> 提示未登录状态

效果图:

OAuth

因此,我们可以将评论系统分为列表(list)、评论框(box)、顶部登录状态栏(signbar)等部分。View 部分的代码组织为:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// 为了减少全局变量,整个网站就暴露一个全局变量 JELON
var JELON = JELON || {};
;(function (JL) {
...
JL.Renders = {
// 列表模块
list: {
tpl: ...,
...
},
// 评论框模块
box: {
tpl: ...,
...
},
// 顶部登录状态栏
signBar: {
tpl: ...,
...
},
... // 其他模块视图
};
...
})(JELON);

视图部分的代码组织好之后,根据 GitHub 提供的各种 API,我们将其封装到 Requests 里面去,组织如下:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
// 为了减少全局变量,整个网站就暴露一个全局变量 JELON
var JELON = JELON || {};
;(function (JL) {
...
JL.Requests = {
// 根据 label 获取 issue 编号
getIssueNumberByLabel: function () { ... },
// 创建 issue
createIssue: function () { ... },
// 根据 issue 编号获取评论列表
getCommentListByIssueNumber: function () { ... },
// 根据评论 ID 获取 reactions (即点赞数据)
getReactionsByCommentId: function () { ... },
// markdown 解析
markdown: function () { ... },
// 通过 code 获取 access_token
getAccessToken: function () { ... },
// 利用 access_token 去获取 GitHub 用户信息
getUserInfo: function () { ... },
// 创建评论
createComment: function () { ... },
// 创建 reactions (点赞)
createReaction: function () { ... }
};
...
})(JELON);

接下来是封装事件操作,我们将其封装到 Actions 里面去,代码组织如下:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
// 为了减少全局变量,整个网站就暴露一个全局变量 JELON
var JELON = JELON || {};
;(function (JL) {
...
JL.Actions = {
// 初始加载,如列表、登录状态等
init: function () { ... },
// 登出操作
signOut: function () { ... },
// 列表翻页跳转
pageJump: function () { ... },
// 编辑预览
editPreviewSwitch: function () { ... },
// 提交评论操作
postComment: function () { ... },
// 点赞操作
like: function () { ... }
};
...
})(JELON);

程序入口:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// 为了减少全局变量,整个网站就暴露一个全局变量 JELON
var JELON = JELON || {};
;(function (JL) {
...
JL.Comment = function (options) {
JL.options = options || {};
$('comments').innerHTML = [
this.Renders.signBar.tpl,
this.Renders.box.tpl,
this.Renders.tips,
this.Renders.list.tpl
].join('');
JL.Actions.init();
};
...
})(JELON);

登录流程

GitHub 授权登录是不可或缺的功能,用只有登录之后才能进行评论。前面有提到,GitHub 授权登录是遵循一个 OAuth 2.0 标准。以下是 OAuth 2.0 的一个运作流程,可以让我们更好的理解它。

OAuth 2.0 运行流程

那么,GitHub 授权登录是怎么样按照这个标准来运作的呢,接下来简单介绍一下,如果要更加详细深入了解的话,你也可以访问 GitHub 官方文档

  1. 用户发起重定向请求授权服务器换取 code
    GET http://github.com/login/oauth/authorize
  2. 拿到 code 之后,利用 client_id、client_secret 和 code 去换取 token_access。(client_id 和 client_secret 前面的预备工作里有提到)
    POST https://github.com/login/oauth/access_token
  3. 获取到 token_access 之后,我们就可以用 token_access 去获取已登录的用户的信息了
    GET https://api.github.com/user

通过以上3个步骤,GitHub 授权登录就算是完成了。

四、评论系统如何使用

  1. 引入评论系统相关的 css、js 。引入相关样式和脚本之后,在你的页面加入以下代码:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    <link rel="stylesheet" href="样式路径">
    <script src="脚本路径"></script>
    <div id="comment" class="comment">
    </div>
    <script>
    JELON.Comment({
    container: 'comments', // 评论框容器id或对象,留空是默认为 comments
    label: '<%- post.slug %>' || '<%- post.path %>', // 文章标签
    owner: '<%- theme.comment.owner %>', // GitHub application 创建者
    repo: '<%- theme.comment.repo %>', // issue 所在仓库名
    clientId: '<%- theme.comment.client_id %>', // GitHub application client_id
    clientSecret: '<%- theme.comment.client_secret %>' // GitHub application client_secret
    });
    </script>
  2. 由于这个评论系统是要集成到个人的主题上去的,所以要跟 hexo-theme-xups 搭配使用,hexo-theme-xups 主题链接为 https://github.com/jangdelong/hexo-theme-xups,目前最新的主题(带有GitHub 登录评论功能),后面会更新上去,往后当然也会陆续进行更新和优化,欢迎多多 star。

五、遇到的问题

遇到的问题主要有三个,一个是创建 label 权限问题,一个是跨域问题,另外一个 GitHub 授权登录兼容性问题。

  1. 创建 label 权限问题(目前未解决)。label 是一个连接文章和 issue 关系的纽带,因为我们要用 label 去查询 issue number,后面的流程才能走下去。如今遇到的问题是,对于新文章来说,只能是我自己本人账号(GitHub Application)创建者才能创建带有 label 的 issue。参考了 GitHub 的接口(POST /repos/:owner/:repo/issues)文档,上面说

    Labels to associate with this issue. NOTE: Only users with push access can set labels for new issues. Labels are silently dropped otherwise.

  2. 跨域问题(暂时解决了)。主要是通过 code 去换取 token_access 的 POST https://github.com/login/oauth/access_token 这个接口跨域,暂时解决方案是用 Node 去转发,但是,我没有服务器资源,这里不得不感谢 @imsun 提供的服务https://gh-oauth.imsun.net了,敬礼😁!!

    以下是更新于 2017.10.11
    POST https://github.com/login/oauth/access_token 接口转发路径已由 https://gh-oauth.imsun.net/ 迁移至 https://cors-anywhere.herokuapp.com/https://github.com/login/oauth/access_token

  3. GitHub 授权登录兼容性问题(暂时不解决)。经过简单的测试,发现 PC 端兼容性问题主要是一些老版本的浏览器,其中包括一些老版本的谷歌浏览器(版本号55.x.xxxx.xx);而移动端的主要是 UC 浏览器无法实现 GitHub 授权登录。