【做業】軟工項目技術規格說明書

軟工項目技術規格說明書

概述&技術棧

產品概述

咱們團隊的社團管理系統繼承自之前的版本，宏觀架構上沒有特別大的變化，可是會引入一些新的功能和特性，也會對新的平臺進行更加完善的支持。

技術棧

本節將詳細介紹本項目開發的技術棧結構。

前端框架

以前的項目中，並無明確的前端框架，也就是說，是原生的js+css+html完成的整個前端。除了使用了jquery作了基本的前端行爲控制，以及使用ueditor做爲編輯器以外，沒有明確的框架，也沒有很明確的架構，能夠說比較凌亂。

將來咱們將考慮使用vue.js框架對於前端進行一次完整的重構，使得架構更加清晰，可維護性更強，將來的開發效率和潛力進一步提升。

後端框架

後端框架使用的是Ruby語言，採用的是最爲主流的Ruby on Rails框架。

根據基本的觀察，代碼質量尚可，不過依然有不少缺少註釋的地方，以後能夠考慮進行一些補全和重構，以及一些功能的添加。

數據庫

數據庫使用的是Mysql，具體是5.6仍是5.7不太清楚，不過應該問題不是很大。

後端代碼裏面，並無較多的明文sql拼接，因此正常來講，只要是mysql係數據庫，都不會存在兼容性問題（mariadb應該也沒大問題）。

web引擎

web引擎的話，能夠有不少選擇，Apache或者Nginx。

咱們更傾向於使用Nginx，進行一次反向代理訪問後端，以及前端也能夠部署在同一個nginx下。

雲環境

雲環境的話，目前尚未徹底肯定，不知道華爲雲那邊是否願意提供足夠的資源。

若是不考慮這個的話，一個比較理想的配置以下（騰訊雲）：

• Ubuntu環境雲服務器，一個實例（理想配置2core4G，最低不得低於1core1G）
• MYSQL雲數據庫，一個實例（理想配置2G200Qps，最低不得低於1G100Qps）
• Redis緩存數據庫，一個實例（理想配置1G400+Qps，最低不得低於1G100Qps）
• 對象存儲服務，一個Bucket（常備模式便可，將來上了規模再考慮冷備Bucket，用於用戶資源的存儲）
• 內容分發網絡服務（也就是CDN），兩個域名
  • 一個用於存儲web前端的靜態內容（js、css、圖片等）
  • 一個用於用戶資源（好比文件等）存儲

固然，最緊縮的狀態下，那就只能：

• 一臺微型服務器
• 數據庫和緩存庫部署在本機
• 存儲內容也一律存儲於本機路徑下

產品設計

架構

宏觀架構

宏觀架構設計圖

宏觀技術架構淺析

• 從總體功能上看，咱們的項目分爲如下三個大的模塊：

  • 服務端（包括Server、Datebase及Nginx）
  • 後端
  • 用戶交互端（前端+小程序）

• 服務端與後端的數據交換

  考慮到軟件後期用戶量的上升及特殊時期（如百團大戰）的用戶訪問需求，咱們在後端與服務器之間加入了一層Nginx反向代理。當出現大量的用戶請求時，服務器能夠配置成集羣的形式，用戶在訪問前端或小程序時，請求會先發送到Nginx服務器，Nginx再在服務器集羣中選擇一個壓力較小的服務器，將該訪問引入被選擇的服務器，以達到負載均衡的效果。對於本項目而言，進行這樣的準備無疑頗有必要。

• 服務器與數據庫的部署

  本項目服務於廣大社團，有着大量的圖片及視頻存儲需求，把這些靜態資源放在主服務器上顯然不是一個明智的作法。咱們採起了服務器和數據庫分離的架構，靜態資源將會經過OSS對象存儲存放在一系列單獨的雲硬盤中，減輕服務器的空間壓力。

• RESTful API

  爲了使社團管理人員和社團用戶具備不一樣的操做界面，咱們在本項目中設置了用於管理社團信息的前端界面，和供普通用戶操做的小程序。因爲前端開發和小程序開發存在着很大的不一樣，所以傳統的後端+模板引擎生成前端界面的方法就不適用了。爲了解決這個問題，咱們的後端將提供一系列RESTful API接口，這些接口對前端和小程序而言都有着相同的調用形式，用戶交互端不須要考慮後端的內部細節，只須要按照約定調用這些API，就能夠得到本身須要的數據。這樣的框架設計將前端與後端徹底解耦，也讓先後端並行開發成爲了可能。

接口規格（暫定）

#	請求方法	請求路徑	路由指向	用途
1	get	/api/articles/:article_id/comments	comments#getcomments	得到當前文章評論
2	post	/api/users/phone_num/verify/code	users#verify_phone_sendcode	手機驗證發送驗證碼
3	post	/api/users/phone_num/verify	users#verify_phone	驗證驗證碼是否正確
4	post	/api/users/email/verify	users#verify_email_send	驗證郵箱，給郵箱寄信
5	get	/api/users/email/verify/:uid/:hash_code	users#verify_email	驗證郵箱，郵箱點擊連接返回
6	post	/api/users/forgetpassword/email	users#fp_email	忘記密碼，郵箱
7	get	/api/users/forgetpassword/email/verify/:uid/:hash_code	users#fp_email_verify	忘記密碼，郵箱轉跳
8	post	/api/users/forgetpassword/phone_num/send	users#fp_phone_send	忘記密碼，手機
9	post	/api/users/forgetpassword/phone_num/verify	users#fp_phone_verify	忘記密碼，手機
10	get	/api/clubs/members/all	clubs#memberslist	獲取社團名單
11	post	api/clubs/users/export	clubs#exportlist	導出名單
12	post	/api/clubs/members/forcequit	clubs#forcequit	強制退社
13	get	/api/clubs/members/apply	clubs#applicantlist	申請人列表
14	get	/api/clubs/members/apply/accept/:user_id	clubs#acceptapplication	贊成申請
15	get	/api/clubs/member/apply/refuse/:user_id	clubs#refuseapplication	拒絕申請

目前原代碼控制器內的返回結構有點凌亂，將來咱們將考慮抽象爲以下基本格式：

{
    "success": true,  // 請求是否成功
    "code": 0,  // 錯誤碼（success爲false纔有意義，不然均爲0）
    "message": "This is response message",  // 返回信息
    "data": {  // 返回數據信息（可能爲null或者Object類型）
        // this is data content
    }
}

分析

抽象&模塊化

抽象與模塊化的話，主要分爲幾層：

• 底層數據抽象化
  • 即，將底層的數據庫訪問，封裝成面向對象的形態（orm）
  • 具體來講，分爲三個點
    • 將SQL的各種操做語句，封裝成給予OOP的操做形態，甚至支持鏈式操做
    • 將數據庫內的數據信息，封裝成OOP對象形態，方便進行讀寫操做
    • 將數據庫結構的變更，維護成數據庫遷移對象（migration），方便往後的不斷後續開發維護
• 數據行爲模塊化
  • 將數據的調度行爲，基於需求域進行分類
  • 將不一樣類型的行爲劃分到不一樣的區域內（controller）
  • 將同一controller內的不一樣行爲，劃分爲不一樣的method
  • 對於不一樣的method，定義各種先後綴操做，極大方便有些共性操做的拼裝（這裏須要用到一些AOP程序設計模式）
• 行爲對外接口化
  • 經過一個映射（route，路由表），將controller內的各個method映射至對外訪問的api
  • 經過路由表，將api傳入的數據請求，進行基本的數據處理與封裝以後，交給對應controller對應method執行
  • method執行完畢後，返回請求response數據

海量數據適應性

對於海量數據適應性，其實有幾個比較常見的作法，咱們以後能夠進行考慮。

• 數據庫讀寫分離
  • 這一機制適用於數據io很大，且存在讀性能瓶頸的狀況（實際上，這種狀況對於webapp來講，至關常見）
  • 設置主庫和多個從庫，主庫主要負責寫操做，從庫負責讀操做，且分擔掉讀壓力
  • 不過值得注意的是，須要有可靠的手段保證數據一致性（這也是分佈式系統都必須面對的難題）
• 數據庫冷熱備份機制
  • 這一機制適用於數據庫存儲數據量巨大，且真正活躍的數據大部分集中在近期的狀況
  • 使用一個熱備份數據庫，和一個（也多是分佈式）冷備份數據庫
  • 大部分操做均在熱備份庫進行，極少數讀操做可能涉及到冷備份
  • 一樣的，對於table單位，也能夠作出相似的機制
  • 固然，在後端orm部分，能夠考慮經過進一步的封裝，以實現和普通單體數據庫無差別的編程體驗
• 服務端分佈式化
  • 將服務端作成分佈式的形態（無數據冒險的單體處理架構，或者有充分的冒險控制機制）
  • 由nginx或者其餘解決方案進行負載均衡管理
• 數據上雲，主要體如今如下幾個方面：
  • 對於前端，一些靜態資源能夠直接使用cdn進行分流，減輕原服務器壓力
  • 對於後端的靜態資源，能夠直接上傳至公有云，讀取時進行接口請求便可，減輕本地硬盤存儲以及IO壓力

信息封裝和隱藏

後端Ruby On Rails

Ruby On Rails是一個基於Ruby的Web開發框架，因爲Ruby自己就是一門極度面向對象的語言（甚至就連整數1都有可供調用的方法，例如1.times），所以Rails框架自然地實現了信息的封裝與隱藏。在咱們的設計中，後端的每個Controller、Model和Helper都是一個類，在開發後端時，外部只能訪問類中公開的方法，類持有本身的私密數據，外界沒法訪問。所以，後端採用的技術自己就很好地體現了信息的封裝和隱藏。

前端Vue.js

在傳統的網頁開發中，一張網頁一般由html, css和js這三個文件組成。以咱們繼承的版本爲例，以前的團隊使用了很純粹的傳統網頁開發模式，一個項目裏充斥了各類頁面文件、樣式文件和腳本文件，各類信息之間徹底沒有封裝和隱藏，所以也就沒法複用，爲前端的開發帶來了很大的困難。

在咱們的設計中，前端將會使用Vue.js進行開發。Vue.js推崇的是「單文件組件」的組織結構，即一個.vue文件中同時包含了頁面、樣式和腳本代碼，而且像其餘編程語言的import同樣，能夠被其它組件所包含。組件對外提供一些數據訪問接口，外界能夠經過這些接口向組件傳遞參數或從組件中獲取返回值，但沒法得到組件內部的運行信息。經過使用組件，Vue作到了前端開發的面向對象化，即信息的封裝與隱藏。咱們採用Vue.js做爲前端開發框架，也正是爲了體現這一點。

RESTful API

傳統的Web App是後端與前端寫在一塊兒，後端使用相似Java Servlet的技術操控http請求，而前端則使用JSP這樣的模板引擎生成。這樣作的缺點是，前端和後端互相透明，可以經過模板引擎中的參數隨意修改對方的值。顯然，這樣的開發方式是不利於信息的封裝的。

咱們的設計使用了RESTful API，前端只須要在特定的時候調用後端提供的API，就能夠得到其想要的數據，而無需也不能知道後端具體是如何工做的。同理，後端只須要爲前端提供API，沒法干涉前端的運做方式。如此這般，先後端都被各自封裝起來，內部信息不會對外界暴露，只經過API來交換信息，作到了信息的封裝和隱藏。

總結

總而言之，經過使用如下技術手段，咱們的項目體現了很好的信息封裝與隱藏：

• 面嚮對象語言與面向對象化的代碼設計方法
• 前端將功能模塊封裝爲單文件組件
• 前端與後端之間經過API交流，互相不暴露內部細節

先後端分離

上文中提到，咱們的項目的用戶展現層有面向社團管理人員和麪向普通用戶的兩個版本。因爲微信小程序的一些固有限制，社團管理的許多操做沒法在小程序中完成，所以咱們單獨設置了一個前端界面用於社團管理。這就帶來了一個問題，若是先後端不能分離的話，就必需要爲小程序和前端界面各作一個後端，這顯然會極大提升工做量。

咱們採用的先後端分離方案，就是由後端提供統一的RESTful API接口，前端和小程序分別去調用以得到數據。雖然前端Vue.js和小程序的運行機制和代碼結構都截然不同，但因爲接口是統一的，因此共用一套後端就能夠。咱們組的前端開發人員負責編寫小程序和前端頁面的代碼，後端開發人員負責編寫後端代碼，兩組人員之間沒有交疊，能夠並行開發，靠的就是這一套設計得當的API。RESTful API傳遞的是與語言環境無關的json格式數據，藉此咱們作到了徹底的先後端分離。

靈活性

基於上文所述，因爲先後端是分離開發的，所以在遇到新的需求或需求變動時，只須要新增或修改一下API接口，即可之前端後端同步進行開發，以實現新的需求。因爲後端和前端都有良好的模塊化特性，許多新需求變動只須要編寫一個簡單的模塊，再將其嵌入整個系統即可以解決。例如，若是用戶信息多加了一條「國籍」，只要在API約定的json格式數據中加一個字段，前端爲表單加一項輸入框，後端爲數據庫增長一個字段，就能夠解決問題。如此這般，咱們的項目體現出了高度的靈活性。

錯誤處理

前端

應對用戶的錯誤輸入是提升軟件產品體驗的重要一環。Vue.js和小程序對於表單驗證提供了很是好的支持，能夠實時檢測用戶的輸入是否知足特定的格式，甚至能夠經過調用後端提供的API鏈接數據庫進行驗證。錯誤的輸入將不會做爲一個請求發送。

當服務器出現意外，返回錯誤的信息時，前端和小程序會及時根據HTTP Status Code判斷髮生了什麼異常，並給予用戶彈窗提醒。對於最多見的沒有找到目標對象的錯誤，前端會根據後端提供的信息，給用戶以詳細的提示和操做指導。

後端

對於目前的後端，實際上大部分錯誤都是一件事：

• 沒有找到操做的目標對象

對於這樣的錯誤，通常來講返回一個錯誤信息，而且配備status_code 404便可。

將來咱們會考慮開發更加完備的接口體系。