[知识路书]技术规格说明书

这是一篇课程博客

项目	内容
课程：北航-2020-春-软件工程	博客园班级博客
作业要求	技术规格说明书
我们在这个课程的目标是	提升团队管理及合作能力，实践软件工程开发
这个作业在哪个具体方面帮助我们实现目标	介绍团队项目【知识路书】，定义项目技术规格和相关特性

关于本组：【敏杰开发团队介绍】

关于选题：【知识路书项目介绍】

整体规划

前后端分离。

对前后端分离的介绍可以参考：这篇博客

考虑到项目体量和开发难度，我们选用的实际是上文中介绍的半分离模式

之所以不引入nodejs中间层将控制器前移，是因为可预见地，应用的业务逻辑并不复杂，后端提供一套restful api，加上少量定制的功能接口足以满足大部分的开发需求。同时队里的同学前端经验并不丰富，因此没有必要额外引入nodejs的学习成本。因此综合考虑，我们作出了这个选择。

在具体的技术方案上，前端我们选用vue.js为基础框架搭建spa，后端选用django并基于其插件扩展快速开发api。选用vue主要看中其易上手的特点，方便我们快速进入开发状态；选用django主要看中其大而全的设计，其自带的ORM、路由管理、用户系统等组件免去了我们学习多种第三方库的烦恼，并且django-rest-framework、django-jwt等插件也方便我们快速开发需要的接口。

如何体现抽象

• 论文被抽象为一个包含作者、标题、摘要、发表时间等属性的数据聚合，而不使用具体的pdf文件表示一篇论文，这样可以方便地管理论文与pdf文件间的映射关系、论文与论文间的引用关系
• 路书被抽象为素材结点集合及其上的连接关系，这样便于序列化；不同的素材都可以继承自素材父类（原型），不同的连接也继承自连接父类（原型），这样便于代码复用
• 后端的django ORM组件提供数据模型及持久化的抽象

如何体现高内聚

• 前端请求restful接口，只给出查询必需的参数而不需要/不允许传控制参数影响后端的查询逻辑，这样后端的接口实现细节对前端隐藏

如何体现低耦合

• 前后端分离的设计本身就是低耦合的：数据、逻辑与呈现解耦
• “抽象”一节中提到的论文数据模型实际上是将论文的元信息与具体pdf文件解耦，这样可以方便替换不同版本的pdf文件
• 文献管理与路书绘制组件解耦，各种文献相关的素材允许复用，提升编辑效率

如何处理错误

由于我们使用View UI，其已经提供了一套模态框，因此我们可以在此基础上封装错误处理，根据错误种类在模块框中显示不同的错误信息

/**
 * 让VUE组件根据异常推出错误模态框
 * @param vc vue component
 * @param err
 */
export const pushErrModal = (vc, err) => {
  const options = getErrModalOptions(err) // 根据异常种类给出错误提示信息
  const errData = err.response ? err.response.data || err : err
  if (...) { // do anything you want
    ...
  } else {
    ...
  }
  vc.$Modal.error(options) // push modal
}

使用时只需要用try-catch捕获不同的异常并使用这个方法处理即可

我们考虑到不同的可能错误制定了内部错误码。目前暂时有如下类型：

Name | Code | Description

•          | -    | -
  

Uncaught | - | 未能正确处理的错误
Debug | 0001 | 调试用错误
NotImplemented | 0010 | 未实现的方法或接口
RuntimeErr | 1000 | js运行时错误
Undefined | 1010 | 访问未定义对象
NetworkErr | 4000 | 无法分类的网络错误
NotFound | 4040 | 访问或查询不存在的资源
Unauthorized | 4010 | 未登陆或没有访问权限

后续我们会根据开发时遇到的需求补充

对开发环境与部署环境的假设

• 前端开发环境统一使用yarn管理依赖包，需要预留本地3000端口用于运行测试；需要已配置好git及其他协作工具
• 后端开发环境要求python版本为3.6或更高，需要使用venv或conda创建虚拟环境并安装requirements.txt中的依赖
• 生产环境正确部署并配置nginx（用于静态资源分发）和uwsgi（用于代理django）。假设生产环境服务器核数、内存等配置合理

应对变化的灵活性

整体是符合开闭原则的。

• 后端部分：对数据模型的修改直接创建并应用新的migration即可，在部署时只需要增量应用migrations即可保持向前更新；由于restful api根据模型和序列化器动态创建，因此这部分几乎不需要改动
• 前端部分：基于vue component组织开发，面向组件的开发可以将每次修改的范围最小化
• 前后端协调：数据请求过程是无状态的，结合前文介绍的高内聚、低耦合特点，前后端可以最大程度实现各自迭代互不干扰。对于新的接口需求，前端同学只需要将功能告知后端同学，后端同学根据需求增设接口并给出调用方法，再由前端接入即可

对大量数据的处理能力

考虑到我们预期的用户规模并不大（千级），后端逻辑简单且支持自行定制部署，因此项目的高并发需求并不强烈。对于正常的访问场景，mysql + nginx + uwsgi的部署策略对于一般的生产服务器已经够用。

假如出现更强烈的高并发需求，可以借助CDN分发静态资源（前端SPA），后端增加响应实例数量，并添加redis等中间件消峰。