edx笔记系统是很有意思的一个话题

架构

  • 前端
  • 后端
  • 通信方式：RESTful接口

由此可知笔记可以作为一项服务

前端

笔记库：annotator

edx中的依赖

edx中业务逻辑

后端

已废弃

edx-notes-api

lms

其他

RESTful接口

通信相关

在LMS中记条笔记的来龙去脉

在lms里做笔记，观察ajax请求，可以看到笔记以POST方式发往：http://NOTESERVER/api/v1/annotations/

header中带有x-annotator-auth-token和X-CSRFToken

x-annotator-auth-token实际上是一个JWT编码的串，放到jwt.io解码完，可看到结果形如

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{
  "sub": "35774bce800db0e8a76980d9c332df73",
  "administrator": true,
  "name": "ww",
  "exp": 1464079917,
  "iss": "http://LMS/oauth2",
  "iat": 1464079887,
  "preferred_username": "ww",
  "email": "ww@qq.com",
  "aud": "edx-notes-id"
}

代码见get_token

上边链接所在的模块就是lms与NOTESERVER通信的模块，通信的url入口为get_internal_endpoint

新技能

这里边有个值得注意的地方是：get_id_token,这个工具是通用的，如果想用jwt来发送受信信息的话

通过JWT，我们可以保证数据是被签名过可信任的。

值得注意的还有当前这部分并不完善，许多地方还是硬编码的,诸如：CLIENT_NAME

观察网络面板，可以看到，发送的数据形如

1

{"ranges":[{"start":"/div[1]/p[2]","startOffset":8,"end":"/div[1]/p[2]","endOffset":18}],"quote":"你可以观看介绍视频","text":"课程介绍","tags":["fun"],"user":"35774bce800db0e8a76980d9c332df73","usage_id":"block-v1:edX+test+2014_T2+type@html+block@af9f16e4a4704f4ab52bc90e5280ba18","course_id":"course-v1:edX+test+2014_T2"}

相关的前端模型定义在edxnotes/models/note.js

前端note工厂为edxnotes/views/notes_factory.js

user是不是采用了什么编码/加密（和edx的匿名用户id一样吗？）

对此有兴趣的同学可以参考common/templates/edxnotes_wrapper.html,其中关键部分为：

1
2

from student.models import anonymous_id_for_user
params.update({'user': anonymous_id_for_user(user, None)})

猜测和edx成绩单中匿名用户的机制一样

出于好奇，追踪到底:anonymous_id_for_user,至此我们揭开了匿名ip的全部谜团

  • Return a unique id for a (user, course) pair
  • If user is an AnonymousUser, returns None

核心源码为

1
2
3
4
5
6

hasher = hashlib.md5()
hasher.update(settings.SECRET_KEY)
hasher.update(unicode(user.id))
if course_id:
    hasher.update(course_id.to_deprecated_string().encode('utf-8'))
digest = hasher.hexdigest()

由此可知，登录用户的anonymous_id是唯一的，使其具有唯一性的影响因素包括：

  • settings.SECRET_KEY（站点级别）
  • course_id
  • user.id

心满意足收场

搜索笔记

我们在lms的笔记汇总页面http://LMS/courses/course-v1:edX+DemoX+Demo_Course/edxnotes/

搜索笔记时，发出的http（ajax）请求为http://LMS/courses/course-v1:edX+DemoX+Demo_Course/edxnotes/search/?text=hello

实际上，这个请求实际上是代理了edx-notes-api。

edx-notes-api

我们使用httpie来向edx-notes-api请求笔记数据

http://NOTESERVER/api/v1/search/?user=106ecd878f4148a5cabb6bbb0979b730&usage_id=block-v1%3AedX%2BDemoX%2BDemo_Course%2Btype%40html%2Bblock%4082d599b014b246c7a9b5dfc750dc08a9&course_id=course-v1%3AedX%2BDemoX%2BDemo_Course

url解码完为http://NOTESERVER/api/v1/search/?user=106ecd878f4148a5cabb6bbb0979b730&usage_id=block-v1:edX+DemoX+Demo_Course+type@html+block@82d599b014b246c7a9b5dfc750dc08a9&course_id=course-v1:edX+DemoX+Demo_Course

我们使用httpie测试

http “http://NOTESERVER/api/v1/search/?user=106ecd878f4148a5cabb6bbb0979b730&usage_id=block-v1%3AedX%2BDemoX%2BDemo_Course%2Btype%40html%2Bblock%4082d599b014b246c7a9b5dfc750dc08a9&course_id=course-v1%3AedX%2BDemoX%2BDemo_Course” (注意要url编码！)

得到

 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
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

{
    "rows": [
        {
            "course_id": "course-v1:edX+DemoX+Demo_Course",
            "created": "2016-05-12T03:38:24.565900+00:00",
            "id": "2",
            "quote": "nks above. At edX",
            "ranges": [
                {
                    "end": "/div[1]/p[2]",
                    "endOffset": 206,
                    "start": "/div[1]/p[2]",
                    "startOffset": 188
                }
            ],
            "tags": [
                "tag"
            ],
            "text": "df",
            "updated": "2016-05-12T03:38:24.566048+00:00",
            "usage_id": "block-v1:edX+DemoX+Demo_Course+type@html+block@82d599b014b246c7a9b5dfc750dc08a9",
            "user": "106ecd878f4148a5cabb6bbb0979b730"
        },
        {
            "course_id": "course-v1:edX+DemoX+Demo_Course",
            "created": "2016-05-12T03:09:01.496272+00:00",
            "id": "1",
            "quote": "to",
            "ranges": [
                {
                    "end": "/div[1]/p[1]",
                    "endOffset": 10,
                    "start": "/div[1]/p[1]",
                    "startOffset": 8
                }
            ],
            "tags": [],
            "text": "a",
            "updated": "2016-05-12T03:09:01.496376+00:00",
            "usage_id": "block-v1:edX+DemoX+Demo_Course+type@html+block@82d599b014b246c7a9b5dfc750dc08a9",
            "user": "106ecd878f4148a5cabb6bbb0979b730"
        }
    ],
    "total": 2
}

注意其中的ranges属性,这是定位的关键，end和start是xpath，tags属性用于存放标签，usage_id是课程内容的定位符，user是用户匿名化后的结果

架构设计

edx的架构总体而言是采用RESTful api来解耦，笔记模块也不例外

edx的笔记前端模块采用的是openannotation开放出来的annotator，openannotation同时也开放了后端，edX没有采用他们的后端，而是使用django-rest-framework重写了笔记部分的后端，我想应该是出于一致性的考虑，这样一来，整个团队的技术栈是统一的，个人而言我觉得这是个明智的决定，尽管这可能浪费一些时间（这确实浪费了不少时间，要知道笔记系统在birch版本中就准备投入使用的！）。

我之所以会赞同这种做法，可能是因为对论坛模块的恐惧吧，论坛采用ruby写的，想对此做定制优化，就显得艰难（事实证明论坛也的确不够稳定）

保持技术栈的一致，有利于让团队成员更热衷维护它们

如果你有兴趣进一步看笔记的模型，请阅读notesapi/v1/models.py

总结

edx的笔记系统可以单独部署，只要做好oauth2的配置即可

由于笔记系统是基于oauth2的，所以可以为手机端所用，同时如果我们将笔记系统视为一个服务，我们可以将它用在edx之外的网站或app里

后话

我对阅读和笔记偏好有加，想基于以下东西做个工具

  • annotator
  • firebase
  • chrome插件
    • 参考划词翻译或者pocket

一个随手摘工具，同时能高亮做过笔记的网页