轻装研发规范(0.0.2).doc

轻装上阵研发规范修订记录版本号修订人修订日期修订描述V0.0.1周礼2016/06/03草稿V0.0.2周礼2016/06/08修改，新增一.流程规范2二.接口规范3三.异常管理5四.命名规范6五.数据库规范7六.SVN管理规范8七.工程规范9八. 环境，工具规范10一.流程规范从需求对接开始，项目开发应遵循包含如下7个步骤：1. 需求初审：目的：了解背景。包含三个方面：项目的由来、原因、展望过程：与会人员初步提出意见输出：（1） 原型草稿，思维导图等。（2） 产品经理需回答产品设计的原因，理念和期望。2. 需求评审目的：原型评审过程：相关人员主要了解交互设计与业务逻辑，结合用户和技术提出相关意见输出：（1） 修改意见（2） 业务流程图（3） 用户故事初稿3. 需求冻结目的：确认开发需求过程：需求较为稳定，暂无其它意见与更改后，冻结需求，并归档记录。输出：（1）原型图，思维导图，流程图等（2）user story（用户故事）与功能优先级4. 业务设计目的：实现产品设计到软件设计的转化，需求的整理与整合过程：主要研发人员参与，将原型需求转化到业务需求，进一步转化成领域模型。输出：模型与状态时序设计等5.接口设计目的：定义前后端接口和系统间接口过程：前后端配合，先完成模块接口的定义，包括接口字段与前后条件转换等内容输出：（1） 接口说明文档（2） 业务流程图6.开发实现在保证其它阶段完善的情况下，着手代码开发工作。7.需求变更目的：紧急且重要的需求变更过程：开发过程中的需求变更需正式申请通知，会议确认后归档记录输出：需求变更列表与优先级描述参考：用户故事与敏捷方法二.接口规范接口原则（1） 前后端分离：api接口需对前端负责（2） 接口先行：接口需在开发前制定（3） 接口中字段采用小驼峰风格，具体命名主要以后端定义为准，推荐前后端一起制定。1.URL说明：原则上采用RESTful API设计风格，采用显式语义化风格，格式如下域名+项目+功能块+请求 /api/photos/getDetail：获取照片列表 /api/photos/getList：获取照片列表 /api/photos/add：创建照片 /api/photos/delete：删除照片 /api/photos/edit：更新编辑照片2.请求接口（1）请求参数尽量一致，命名采用小驼峰（2）分页参数： page : 请求当前页 limit： 每页显示条数3. 返回数据返回格式如下： code:000000, data: name:zl , message:成功, success:true说明：（1） code: 状态码，000000表示成功，非0表示各种不同的状态。两位系统/项目，两位模块/功能，两位业务/状态（2） message: 描述信息（3）data: 成功时返回的数据，类型为对象或数据4.状态码规范六位数字（暂定）00 00 00系统/项目 模块/功能 业务/状态系统：00Promgr：01User：02Pay：03Marketing：04Wechat：05Message：06Cost：07Cm：085.Controller规范说明：采用Swagger接口配置，接口中需包含接口与参数的注释与说明。Demo： ApiOperation( value = 编辑用户信息, notes = 编辑用户信息, httpMethod = POST) RequestMapping(value = /editUser, method = RequestMethod.POST)public Result editUser(ApiParam(value = 用户姓名, required = true) RequestParam String name, ApiParam(value = 年龄, required = true) RequestParam Integer age) /1.参数校验：必传，范围等 if (name = null) return errorResponse(ACK.PARAM_ERROR, 参数异常name); if (age = null) return errorResponse(ACK.PARAM_ERROR, 参数异常age); /2.服务接口调用：实现功能 /3.数据整合：针对前段需求，组合数据结构 /4.返回结果 return successResponse(); ApiOperation：接口功能说明，请求方法ApiParam：请求参数说明参考：http:/swagger.io/http:/swagger.io/swagger-ui/6.HTTP请求返回常用状态（1）成功响应：【200】：请求成功，返回请求数据（2）客户端错误：【400】：因发送的请求语法错误,服务器无法正常读取【401】：需要身份验证后才能获取所请求的内容,类似于403错误.不同点是.401错误后,只要正确输入帐号密码,验证即可通过【403】：客户端没有权利访问所请求内容,服务器拒绝本次请求【404】：服务器找不到所请求的资源.由于经常发生此种情况,所以该状态码在上网时是非常常见的【405】：该请求使用的方法被服务器端禁止使用,RFC2616中规定,GET和HEAD方法不能被禁止【406】：在进行服务器驱动内容协商后,没有发现合适的内容传回给客户端（3）服务器错误：【500】：服务器遇到未知的无法解决的问题参考：http:/tool.lu/httpcode/三.异常管理1.异常基本要素要素要素名称说明code异常编码两位系统/项目，两位模块/功能，两位业务/状态message异常消息出现异常后，需要给用户展现的提示消息description异常说明说明异常产生的原因，解决办法等，配置文件中暂不体现2.异常基类mon.BusinessException- 继承自java.lang.RuntimeException构造方法方法名参数说明BusinessException(String code)对应于上述的异常编码中的异常编号BusinessException(String code, String msg)对应于上述的异常编码中的异常编号以及异常消息中的参数值实例方法方法名说明String getCode()返回本异常所对应的异常编码String getMessage()返回异常消息，这个消息是经过格式化的示例：与上述配置示例相对应的异常声明:BusinessException exception = new BusinessException(“000002”, “缺少参数”)四.命名规范1.命名需满足如下原则（1）名副其实：无论类名，方法还是临时变量，名字能表达含义，命名能表达的，就无需注释（2）避免缩写：除非已经广泛使用的缩写，不要自行创造缩写词汇（3）使用英语：除非万不得已，请多查英文词典（4）专业词汇：尽量采用领域词汇2. 类/接口/枚举（1）首字母必须大写（2）使用大驼峰方式（3）测试类的命名以它要测试的类的名称开始，以Test结束。3.方法命名小驼峰式：第一个单词首字母小写，后面其他单词首字母大写。 一般采用动词+名词的方式，动词体现方法要执行的操作，名词体现操作对象或操作方式getSomething() 表示查询editSomething() 表示修改addSomething() 表示新增deleteSomething() 表示删除4.变量命名小驼峰式：第一个单词首字母小写，后面其他单词首字母大写。 5.常量命名全大写，单词间下划线分隔单词6.方法/函数方法/函数需满足如下原则：（1）使用描述性名称：名字表达该方法要做的事（2）原则每个不超过50行，坚决不超过100行（3）一个方法只做一件事：例如：如果一个方法内需要查询和修改，请将其重构成两个方法然后调用调用（4）参数原则上不超过五个：过多参数请封装成对象（5）减少重复：相同的功能，封装成独立方法参考：代码整洁之道重构五.数据库规范1.库命名（1）以系统简称开头，如配置管理系统，就以CM(ConfigurationManagement)开头；多个单词用下划线分隔。（2）以后缀区分环境：开发：_dev测试：_test预演：_preview2.表命名（1）单词小写，单词之间用下划线区分（2）无需前缀3.字段命名（1）字段采用小驼峰（2）表命名使用英文描述，特殊情况允许使用拼音，禁止使用汉字4.设计原则（1） 每张表都必须有主键（2） 使用自增长主键时，字段名为id，类型为bigint(20)，对应JAVA数据类型为long。起始数值由业务决定，默认为1（3） 业务意义相同的字段，在不同表中的命名、数据类型和长度也需相同；（4） 每张表必须包含字段：创建时间(createTime)和修改时间(updateTime),有效标示（isValid）（5） 建议时间类型的字段，其数据类型设置为DateTime；（6） 建议使用没有业务意义的字段作为主键；（7） 建议不使用物理外键，数据的完整性约束，交由应用层控制；（8） 建议给非空字段设置默认值；（9） 建议数据非常稳定的表不使用主键id，使用其具有唯一性的字段作为主键；5.索引原则（1）主键PK列上必须建立唯一索引；（2）类型为Text、Image、Bit的列上不要建立索引；（3）建议不要在长度超过50的字符串字段上创建索引；（4）建议在查询频繁的列上建立索引，但当增删改效率优先于查询效率时则不建立索引；（5）建议在作为外键关联且关联查询频繁的列上建立索引；（6）建议在经常排序的列上建立索引；（7）建议在多个联合查询的字段上建立复合索引；（8）建议不要在数据重复概率很高的列上建立索引；（9）注：例如性别字段，一般只有男、女两种值，建立索引不会提高查询效率反而导致额外的开销，不过如果概率较高也可以考虑建立哈希索引(MySQL)或者位图索引(ORACLE)。6.mapper层设计原则（1） sql原子化设计，尽量不包含复杂业务逻辑和计算（2） 条件查询尽量采用判空表达（3） 保持字段与数据库的一致性，比如避免数据库使用mobile，查询结果使用phone7.数据库操作规范（1） 使用脚本新建，更新表（2） 每个字段必须有注释六.SVN管理规范1.版本划分 总体来说，分三个版本：dev（开发版）、deta（测试版）、release（发布版） 开发版本的版本号，由2位数字组成如0.1，0.2， Beta版本和Release版本的版本号由3位数字组成，即在开发版本的基础上增加了修订号，如 0.1.12.规范（以0.1版本为例）（1）当与产品确定好了一个0.1大版本的需求以后，会将任务划分到每个子系统，此时，每个子系统在trunk上创建一个新的开发分支（branches/dev/0.1）。（2）当branches/dev/0.1开发完毕并进行了充分的单元（JUint）测试，此时将branches/dev/0.1上的代码合并到trunk上。（3）当管理者确定此时trunk上的0.1版本已经可以发布，创建branches/deploy/0.1分支，开始对0.1版本进行严格测试和维护。与此同时，创建tags/beta/0.1.0，构建并发布到测试环境，供专业测试人员进行测试。（4）tags/beta/0.1.0测试过程中发现的bug，提交到branches/deploy/0.1分支进行修正。（5）到积累了一定多的bugs或者一段时间内已经没有发现新的bug，再从branches/deploy/0.1分支创建tags/beta/0.1.1，提交测试环境进行回归测试，同时将bug修正的代码合并到trunk。（6）tags/beta/0.1.1中发现的bug跟tags/beta/0.1.0的处理方法一致（7）如果tags/beta/0.1.1中没有再发现bug，则创建tags/release/0.1.0并发布到生产环境，开始正式运行。（8）tags/release/0.1.0上发现的bug与tags/beta/0.1.0的处理方法一致。（9）如果遇到两个版本同时开发的情况，在0.1版本发布前，开发人员要定时将主干上0.1版本的代码合并到0.2的开发分支上，当0.1版本发布以后，再讲0.2开发分支上的代码合并到主干3.注意提交时，请不要提交本地项目相关的文件，如.project，.settings等等。对于maven项目，只提交src/main/java；src/main/resources；src/test/java；src/test/resources；pom.xml七.工程规范1.工程结构系统主要包含三部分：API：前后端接口（Controller） ，主要功能如下（1） 请求参数接收，校验（2） 子系统服务调用（3） 部分系统间业务逻辑处理（4） 返回数据组装INFC：服务接口中心，主要功能包含：（1） 服务接口定义（2） 数据库模型（javabean）定义【注】该部分建议重构，实现多个infc，与子项目相关子系统：服务实现，数据持久化处理等，主要功能包含：（1） 服务接口实现（2） 处理业务逻辑（3） 数据封装（4） 数据持久化相关操作2.公共规范（1）日志采用logback（2）pom.xml采用“按需配置”3.api规范详见“接口规范”4.infc规范根据不同工程分包，推荐结构示例如下：cncomqingzinfccostentity：过程javabean，封装请求参数，返回数据，枚举类型等model：模型javabean，与数据库表对应service：接口定义，建议接口命名以Service结尾，不加“I”： ProjectService，对应的实现需以“Impl”结尾。5.子系统规范以cost工程为例：（1）代码结构主要包含 （2） 配置结构：env：环境相关，用于开发（local），测试（test），预演（preview），生产（release）环境的个性化配置mappings：mabatis配置文件spring：sping配置文件perties:常用业务配置内容logback.xml:日志配置8. 环境，工具规范1.环境测试环境服务器地址6服务器用户qzsz008服务器密#06#as8015033数据库链接jdbc:mysql:/9:3322/qzsz_dev数据库用户root数据库密码qzsz008008微信公众号另一个轻公众号账号公众号密码as8015033后台管理端地址后台管理端位置/home/qzsz008/front/admin微信APP地址微信APP位置/home/qzsz008/front/wechatZookeeper地址6Zookeeper端口8121老后台位置/home/qzsz008/tomcat7-wxzx8124老后台地址应用服务器(tomcat)位置端口dubbo端口API中心位置/home/qzsz008/sub-systems/api8121配置管理中心位置/home/qzsz008/sub-systems/cm973320889卡券系统位置/home/qzsz008/sub-systems/coupons972520888营销系统位置/home/qzsz008/sub-systems/marketing970920882消息中心位置/home/qzsz008/sub-systems/message971320884运营系统位置/home/qzsz008/sub-systems/operation972920886支付系统位置/home/qzsz008/sub-systems/pay970520881工程管理系统位置/home/qzsz008/sub-systems/promgr971720885用户中心位置/home/qzsz008/sub-systems/user972120887微信后台位置/home/qzsz008/sub-systems/wechat970120883报价系统位置/home/qzsz008/sub-systems/cost20890日志文件位置/usr/local/logs/xxx预演环境服务器地址0(9)服务器用户qzsz服务器密码qzsz008008数据库链接jdbc:mysql:/9:3322/qzsz_preview数据库用户root数据库密码qzsz008008微信公众号轻装_preview公众号账号公众号密码as8015033后台管理端地址后台管理端位置/home/qzsz008/preview/front/admin（6）微信APP地址/微信APP位置/home/qzsz008/preview/front/wechat（6）Zookeeper地址0Zookeeper端口8121老后台位置/home/qzsz008/tomcat7-yuyan82056老后台地址应用服务器(tomcat)位置端口dubbo端口API中心位置/home/qzsz/servers/ap