freader
使用
环境准备
安装 MongoDB
配置 mongodb 连接字符串,程序监听接口等,见配置项
编译并运行:
npm start
程序编译结果在 bin 目录,运行时可只保留 bin 目录,但需要手动编译:
编译程序
npm run build
运行程序
cd bin
>node .
路由
路由配置改由配置文件式的方式配置,避免写大量重复代码的枯燥。但路由配置仍是程序的一部分,而非真正的配置文件(如测试配置),因此它们被定义在.js 文件中而不是.json 文件。
路由配置的结构如下:
controller // controller
route1 // 路由
request1 // 相同路由下的不同请求方法
param1 // 请求参数
param2 // 请求参数
每一层次的详细结构定义见src/domain/types/route.d.ts
每一个 Controller应该对应一个路由配置文件,它们调用同一个 service 的不同方法。
但例外是被允许的,可以通过 RequestMethod#invoke 属性为每个请求方法单独设置要调用的 service 层方法,这将允许使用除 Controller#service 属性指定的 service 之外的方法,但你必须指定方法调用时的this指向谁,通过 RequestMethod#thisObject 指定,否则将使用 controller.service。
验证
来自用户的数据总是不被信任的。验证必不可少。
身份验证
通过在请求头中包含一个 token 来认证身份。但登录和注册请求除外。
token 的值是随机生成的,每次登录后它的值将会改变。同时用户的 token 也可以作为注册时的邀请码,新用户成功注册后邀请码对应的用户的 token 将会重新生成,即原邀请码失效。
如果在请求过程中 token 变化或验证失败,会在响应体中要求变更 token 或重新登录,方式见统一响应。
请求参数验证
请求参数的合法性也需要验证。
过滤不合法的参数有利于减少服务器的不必要开销,如连接数据库等。另外,mongodb 的使用也要求我们对参数进行验证。
试想,注册请求要求前端传递一个 json 对象,它包含用户信息。当我们对用户信息相关的字段验证通过后,它似乎没问题。但如果它包含一大堆无效字段呢,我们就可能向数据库插入大量垃圾数据。
这样的验证可以有很多方法,但我认为零碎的把验证代码分布在各个地方显得冗余,因此将其集成在了路由参数配置里:这样我就可以通过类似配置文件的方法来对数据进行验证,而无需在业务逻辑中包含额外的验证代码。关于验证的代码在这里。
数据源
数据由远程数据源提供。为了方便不同源之间的无缝衔接,书籍和章节的 ID 都被(尽量)设计为与数据源无关。但注意,客户端不应该依赖这一点,服务器并不保证不同数据源章节 ID 一定一致,切换数据源时应注意检查,如果章节 ID 不一致应通过当前阅读进度中的章节索引来预测新的阅读进度。
数据提供者(数据源)继承一个统一的接口,以此来整合不同数据源。请求数据时给定source
参数指定数据源。
添加数据源
添加数据源是简单的。因为每个数据源被独立为一个模块。数据源模块只需要做好自己该做的事就行了——获取数据。其它的就交给数据处理模块去完成吧。要添加一个数据源,只需要在数据源组目录中添加一个 service 并将它的名字添加到数据源列表。这需要修改BookService让它能够识别出新的数据源。相信我,这足够简单。
数据更新
由于数据来源于远程数据源,不得不考虑数据的更新。为了更加优雅的更新数据,cron(定时任务模块)被创建了出来。目前,它会按照配置的那样在特定的时间去更新需要更新的数据。尽管这还不够完善。
统一响应
为了一致性和方便,任何请求的响应体都具有统一的结构,并且 HTTP 状态码总是 200。
{
code //错误代码,一般为对应的HTTP状态码。但并不保证设置值。为0的时候等同于200
error //错误内容
data //请求的响应内容
needLogin //是否要求重新登录(当前会话已过期)
token //如果非空,即要求变更会话ID(token)
}
全局配置
有一个全局配置文件来配置一些参数,以更好的工作。但这些配置都不是必须的,即它们总是有一个默认值。你可以让配置文件留空,但请不要配置不合适的值,因为那样可能会造成一些奇异的错误。并没有对每一个配置项的值做验证——管理者是值得信任的。
如果无法理解某个配置项,可以看看这里,它对每一项配置进行了简短的说明。
全局配置文件仅允许在运行目录,即 bin 目录下。
测试
接口测试
参考路由配置,测试和配置路由一样,可能需要写很多重复代码,因此同样的,我将测试工作交给了配置文件。我只需要在配置文件中配置对应路由的请求参数,便可以自动化的执行测试。
考虑到配置文件不在代码范畴内,而是根据情况随时改动,测试的配置文件格式并不像路由配置一样严格,它更加自由。测试配置文件参考配置文件。可修改test/test-config.json
文件设置参数和要测试的接口。
然后执行:
npm test api
如果是要测试本地服务器,则应在测试前保证服务运行,或者加参数--run
自动运行服务:
npm test api -- --run
数据源测试
数据源测试使用 Mocha 作为测试框架,chai 作为断言库。
注意,测试并不会重新编译代码,所以应在测试前先进行编译:
npm run build
然后执行:
npm test sources
也可以单独测试某个数据源,如仅测试起点和顶点数据源:
npm test qidian x23uscom