【做业】软工项目技术规格说明书

软工项目技术规格说明书

概述&技术栈

产品概述

咱们团队的社团管理系统继承自之前的版本，宏观架构上没有特别大的变化，可是会引入一些新的功能和特性，也会对新的平台进行更加完善的支持。

技术栈

本节将详细介绍本项目开发的技术栈结构。

前端框架

以前的项目中，并无明确的前端框架，也就是说，是原生的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便可。

将来咱们会考虑开发更加完备的接口体系。