[知識路書]技術規格說明書

這是一篇課程博客

項目	內容
課程：北航-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等中間件消峯。