【CodingNoBorder - 04】无际软工队 - 求职岛：技术规格说明书
無際軟工隊 - 求職島：技術規格說明書
| 這個作業屬于哪個課程 | 2022年北航敏捷軟件工程 |
| 這個作業的要求在哪里 | 團隊項目-計劃階段要求 |
| 我們在這個課程的目標是 | 熟悉敏捷開發的方法論，并通過實際開發產品進行實踐。 |
| 這個作業在哪個具體方面幫助我實現目標 | 熟悉敏捷開發的方法論：學習敏捷開發的技術定義規范和方法。 通過實際開發產品進行實踐：實際定義所開發產品的技術規格。 |
Author: 無際軟工隊
Date: 2022.04.18
摘要
本文檔設計并定義了平臺的系統架構。
項目硬件架構及技術棧
本項目基于微信小程序與網頁 web 端實現，目標適配 PC 和手機端。項目將部署到騰訊云服務器云端，部署環境為 Debian 11。服務器基本配置如下：
- 4 核 8G，100G SSD 云盤存儲，10Mbps 公網帶寬
項目前后端開發所涉及的具體技術棧如下：
- 微信小程序端：使用微信官方開發工具開發；
- Web前端：前端所用的程序設計語言為 HTML + CSS + JS ，采用 Nuxt.js 全家桶開發；
- 后端：
- 后端所用的程序設計語言為 Python，采用 django-rest-framework框架
- 測試采用 Django 框架自帶的單元測試
- 數據存儲使用關系型數據庫 PostgreSQL
- 其中 Python 版本為 3.8，Django 版本為4.0，PostgreSQL 版本為 14.2，后續可能會視具體兼容情況決定是否做相應調整。
軟件架構
軟件的整體架構如下圖所示：
下面對其中的主要模塊所承擔的功能任務進行簡要介紹。
后端 Django 框架
依照 RESTful 樣式（Model - Serializer - API）設計后端，利用 Django 提供的對象關系映射機制 (ORM)、路由管理、用戶認證與權限組件可顯著降低開發成本，提升整體開發效率。同時，利用 Django-rest-framework（DRF）插件快速開發RESTful樣式的接口，利用 django-rest-framework-simplejwt 插件實現JWT樣式的用戶鑒權，從而快速迭代實現前端所需的各類接口。
前端
前端使用 MVVM 架構，視圖層 (View) 負責向用戶展示界面，視圖模型層 (View Model) 負責實現頁面視圖與數據的雙向綁定，數據模型層 (Model) 負責和后端交互以及相關邏輯的處理。
CDN & COS
用于解決高并發時流量瓶頸問題，前端的靜態文件如 .css/.js 會由內容分發網絡 CDN 進行緩存和分發。用戶的頭像、圖片、簡歷等等大文件將依托于騰訊云提供的對象存儲服務 COS 進行存儲與分發，此舉既可以減輕服務器帶寬壓力，也可以加快用戶下載速度提升用戶體驗。
后端開發目標
代碼編寫 & 系統設計
數據建模
數據的建模依托于 Django 提供的 ORM 框架，通過編寫 Python 類來自動生成數據庫中的數據表和表之間的依賴關系。將實驗室、實驗室招聘者、求職者、求職信息、實驗室與導師評價等實體抽象成對象，利用 ORM 進行面向對象編程
API 設計及抽象
參照 RESTful 范式將對象的字段、完整性驗證以及與對象狀態轉變相關的過程封裝在 Model 類中；將模型對象表示為 json 的方法實現為 Serializer 類，將面向前端調用的對象視圖以及對象操作方法封裝為 APIView 類，從而實現高內聚、松耦合和模塊化。以上做法可以充分利用 django-rest-framework 的框架實現， 大幅提升開發效率。
錯誤機制及處理辦法
后端的錯誤包括兩大類：通用錯誤和特定錯誤，通用錯誤是在任何 API 調用時都有可能出現的錯誤；而特定錯誤是僅針對某個或某些API可能會發生的錯誤。
除了的上述兩類意料中錯誤以外，還可能出現意料外錯誤，如網絡不可達、nginx 反代連接失敗、后端崩潰等等，其標志為返回的報文不是 json 格式，前端可能仍需要處理此類錯誤。
| 發生位置 | 任何API都有可能出現 | 文檔中特別規定某API中會出現 |
| HTTP Status Code | 4xx ~ 5xx | 4xx ~ 5xx |
| 報文信息格式 | {“code”: 400, “detail”: “…”} 其中code 與 HTTP Status Code 一致 | {“code”: 600+, “detail”: “…”, “data”: {…}} |
| 前端處理優先級 | 最后處理 | 優先處理（先判定code字段是否大于600） |
| 格式定義方式 | 定義于此，類型數量固定 | 定義于API文檔，隨時增加 |
| 處理方式 | 跳轉登錄，或彈窗報錯，或刷新頁面，或根據前端對于不同場景的定制化設置 | 前端具體分析data內容決定 |
通用錯誤類型一覽
- 400 BadRequest：json不能解析或數據不滿足約束
- 401 Unauthorized：當前用戶未登錄，或token失效
- 403 Forbidden：用戶已登錄，但是無權訪問資源
- 404 NotFound：為了滿足用戶的請求所需要的某一部分資源不存在
- 405 MethodNotFound：比如API只定義了GET方法，那么用POST就會出這個錯
- 500 InternalServerError：后端運行過程中報了其他錯誤
后端具體寫法
對于通用錯誤類型，請拋出rest-framework內置的特定錯誤如：
raise rest_framework.exceptions.ValidationError對于特定錯誤類型，請在core.exceptions內新建一個異常類，繼承自rest_framework.exceptions.APIException，并在異常類中定義好轉換成json的方法，在需要拋出異常的地方將其拋出并由 rest_framework 框架自動轉化為指定的格式
class MyException(APIException):code = 600default_detail = "foo"...大部分錯誤如果前端可以進行處理的將由前端處理，若有惡意用戶直接向后端發送非前端生成的數據包后端不會額外返回錯誤詳細信息而是直接返回一個 400 BadRequest，前端無需對此處理。
需要后端查詢數據才能發現的錯誤將與前端協商一個錯誤碼，返回的數據包格式如下所示，所有的內容根據具體的錯誤以及前端所需要的信息單獨設定
{"code": 600, "detail": "...", "data": {...}}若后端處理正確將會返回一個 200 Success 數據包，內容各自約定，不采用上面的格式。
系統性能分析 & 高并發應對
因為與職協有合作，可能會存在高并發的情況，因此我們購置了 4核8G 的服務器，使用 nginx + uwsgi 的方式部署基本上可以符合要求，如果真的出現了處理能力不足的情況還可以額外購置服務器并利用 nginx 的分流機制提升并發能力。
同時我們會使用對象存儲分發大文件，減小帶寬的壓力。
需求迭代的靈活性
由于我們的軟件整體設計上呈現扁平化趨勢，且團隊規模與軟件大小均相對輕量，因此當出現新增需求時，我們可以實現“一站式”流水線應對方案。
具體操作流程為：
網絡安全設計
- 任何生產環境密碼不得進入 git 倉庫，需要在 CI 中使用的密碼填入 Action Secret 。
- 用戶的密碼通過安全的 pbkdf2_sha256 的方式存儲，即將用戶密碼加隨機鹽之后使用散列函數循環計算 320000 次后將結果存入數據庫中，有效防止暴力破解與意外的數據庫泄露導致的密碼泄露。在注冊和修改密碼時會要求用戶的密碼長度、使用大小寫字母與特殊符號并拒絕使用常見密碼。
- 數據傳輸會采用全程 https 安全加密并禁用 http 不安全傳輸方式。
- 用戶登錄后將會得到一個符合 JWT 標準的 token，之后的所有用戶操作后端都會根據此 token 進行鑒權，向后端的請求格式必須為 json 而不能是 urlencoded_form，這樣的機制可以有效防止 CSRF 攻擊。
- 后端的權限驗證將會采用 Django 提供的權限管理機制，并且我們會將默認的API調用權限設置為僅管理員可訪問，僅當顯式聲明某些用戶可訪問時才可訪問（也就是白名單模式），防止編程時意外的權限泄露。
- 后端訪問數據庫均會通過 Django-ORM 的機制進行，其會對產生的 SQL 語句進行轉義，防止 SQL 注入攻擊。
- 前端如果需要顯示用戶發送的富文本內容，將會在前端使用 JavaScript 編寫的 xss 插件進行腳本標簽白名單過濾，防御 XSS 攻擊。
- 用戶上傳的文件將會直接上傳至騰訊云對象存儲服務，不會在本機留存，防止用戶上傳惡意程序。
測試
單元測試
測試會采用 Django 框架的測試模塊進行編寫，測試各個 API 的安全性與可用性還有代碼覆蓋率，并且測試工作將會配置于 CI 實現自動化測試。
系統壓力測試
為了模擬真實請求場景，計劃使用 Python-requests 腳本發送請求進行壓力測試。
前端開發目標
代碼編寫 & 系統設計分析
視圖層
微信小程序端使用其特有的視圖層描述語言 WXML 和 WXSS，以及小程序的腳本語言 WXS。
Web 前端使用 HTML + CSS + Javascript 完成視圖層的描述。
視圖模型層
Web 前端 (Nuxt.js 基于 Vue.js)：
微信小程序端：
數據模型層
微信小程序端基于 Uni-app 所提供的類 VueX 狀態管理框架進行集中狀態管理。
Web 端依托 Nuxt.js 集成的 VueX 進行集中的狀態管理。
前后端交互
微信小程序端和 Web 端均使用 Axios 與后端進行交互。
錯誤處理
將 Axios 再封裝一層，按照和后端約定的錯誤碼進行相應的邏輯操作。
需求迭代的靈活性
采用 MVVM 架構，通過組件化降低模塊間的耦合度，同時提高代碼復用率，方便在需求迭代時進行更改。
測試
微信小程序端使用測試工具集 miniprogram-simulate 進行測試。
Web 端使用 Jest + Vue-test-utils 進行單元測試，使用 Nightwatch.js 實現端對端的真實測試。
部署
Git倉庫與CI/CD
使用GitHub Action運行自動化測試、打包Docker鏡像和自動部署。
Docker容器化部署
為了保證部署環境和開發測試環境的一致性，CI 部署的方便性，我們采取 Docker 部署方式。
文檔編寫
為了避免花費太多時間在文檔編寫上，我們決定是只編寫必要的文檔，例如前后端 API 交互文檔。同時，我們考慮利用 swagger 等工具自動從后端代碼中導出 API 文檔，以保證文檔和代碼的一致性。
除此之外，我們制定了嚴格的 commit 和提交規范，以保證能夠通過 commit 歷史以及 issue 歷史等對代碼提交進行追溯。
總結
以上是生活随笔為你收集整理的【CodingNoBorder - 04】无际软工队 - 求职岛：技术规格说明书的全部內容，希望文章能夠幫你解決所遇到的問題。
- 上一篇： 佳能数码相机照片删除了怎么恢复，如何恢复
- 下一篇： [转]拍照怎么搜题？（上）