开发规范分享

最近要准备新同事的开发规范培训，所以大概理了理开发过程中总结的一些注意点和规范,有git管理、代码编写和API设计原则这3个方面

git分支开发管理

Git三大特色之Branch(分支)

主分支：

master： origin/master 分支上的最新代码永远是版本发布状态(这个分支只能从其他分支合并，不能在这个分支直接修改)。

develop：origin／develop 分支则是最新的开发进度(这个主要合并与其他分支，比如Feature分支)

协助分支：

feature：Feature 分支用来做分模块功能开发,一旦开发完成，可以合并到develop 分支，提交时对应的负责人可以code review

release：分支用来做版本发布的预发布分支 建议命名为 release/xxx 如：release/1.0.0

hotfix: 分支是用来做线上的紧急 bug 修复的分支,建议命名为 hotfix/xxx

原则：

1、分支不混用，一个分支就开发一个功能，开发完成合并就删除

2、分支名称简明，看到名字能知道这个分支要开发/修复的功能，分支名字长没关系只要能说明要做的事情就可以

3、commit一定要跟commit对应修改的代码对应的上，commit要能说明修改的内容，不要fix，fix这种，或者n个commit一模一样

注意点：

1、提merge request时，如果有冲突请把develop分支合并到本地解决完冲突后重新提交

2、打tag时一定要修改对应的version文件，确保version文件和实际的tag对应的上

2、打tag的时候需要全局替换@CommandLine.Command(version = "4.2.0")中的数字为对应的版本号，和version.ini中的信息对应上

设计原则

1.清晰(是什么，做了什么，一眼看得出来)
2.简单(职责少，代码少，逻辑少)
3.干净(没有多余的逻辑)
4.好拓展(依赖的比较少，修改不会影响很多)

命名原则

1.名副其实

阅读名称就知道它为什么存在、做什么事、应该怎么用，如果需要通过注释来回答，那就不算名副其实

2.不容易混淆

避免使用非常相似的名称，尤其是类型还相同，比如小写 l 和1、o 和 0、专有名词

3.读的出来

不要因为害怕名称过长而使用缩写，那样不便于和别人讨论

4.方便搜索

名称长度和其作用范围成正比，作用范围比较大的，长名称也可以，只要能表达清楚

方法设计原则

1.函数的第一要则：短小 (多短才算可以？不超过 40 行，缩进层级不该大于两层,尽量不出现2层for)

2. **只做一件事** 
要判断函数是否做了不止一件事，就看它里面的代码，是否能再拆出一个函数

函数变大的头号凶手：switch 语句 
switch 语句天生要做多件事，我们能做的，就是减少 switch 语句的次数，把它埋藏在较低的抽象层级，同时不重复使用 switch 
如果有类似的 switch 出现多次，就要考虑使用多态来减少 switch 语句出现的次数

3.参数尽量少
定义的函数的参数越多，你耗费函数使用者的青春就越多，使用者需要花时间搞清楚每个参数的具体含义和顺序 
最理想的参数数量是 1~2 
从测试的角度看，参数越多，可能出现的用例就越多，就越容易出错 
保持参数列表短小的方法: 参数升为全局变量、多个参数封装成一个类

注释

原则是尽量不写注释，除非一些特别的业务逻辑，代码看起来很奇怪但业务是这样子的

1.弥补代码表达意图的失败

代码本身无法说明意图，这时使用注释，说明这段代码需要被修改

2.提供信息

提供代码以外的信息，比如产品相关信息

3.复杂实现的简要概括

让阅读者快速了解某个复杂的系统

4.警示、提醒

比如某个不起眼的代码是为了解决某个 bug，防止别人误删

异常处理

1、尽量不使用异常捕获
原则是程序中尽量不使用try，代码层面可预期的全部使用代码层面处理掉，除非一些外部依赖，如连mysql失败，操作文件本身会报exception等
2、抽离错误处理
如果错误处理很重要的话，可以考虑把错误处理单独放到一个方法里。
3.不要返回 null
 返回空对象好于返回 null，尽可能的避免空指针的出现。

整体开发注意事项可以参考阿里巴巴的java开发手册

https://github.com/alibaba/p3c/blob/master/Java%E5%BC%80%E5%8F%91%E6%89%8B%E5%86%8C%EF%BC%88%E5%B5%A9%E5%B1%B1%E7%89%88%EF%BC%89.pdf   

API设计规范

路径(Endpoint)

路径又称"终点"(endpoint)，表示API的具体网址。
在RESTful架构中，每个网址代表一种资源(resource)，所以网址中不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应。
一般来说，数据库中的表都是同种记录的"集合"(collection)，所以API中的名词也应该使用复数。
举例来说，有一个API提供动物园(zoo)的信息，还包括各种动物和雇员的信息，则它的路径应该设计成下面这样。
 
https://api.example.com/zoos
https://api.example.com/animals
https://api.example.com/employees

HTTP动词

对于资源的具体操作类型，由HTTP动词表示。 常用的HTTP动词有下面五个(括号里是对应的SQL命令)。

GET(SELECT)：从服务器取出资源(一项或多项)。
POST(CREATE)：在服务器新建一个资源。
PUT(UPDATE)：在服务器更新资源(客户端提供改变后的完整资源)。
PATCH(UPDATE)：在服务器更新资源(客户端提供改变的属性)。
DELETE(DELETE)：从服务器删除资源。

下面是一些例子。

GET /zoos：列出所有动物园
POST /zoos：新建一个动物园
GET /zoos/ID：获取某个指定动物园的信息
PUT /zoos/ID：更新某个指定动物园的信息(提供该动物园的全部信息)
PATCH /zoos/ID：更新某个指定动物园的信息(提供该动物园的部分信息)
DELETE /zoos/ID：删除某个动物园
GET /zoos/ID/animals：列出某个指定动物园的所有动物
DELETE /zoos/ID/animals/ID：删除某个指定动物园的指定动物 (也可以把数据放到body里面)

过滤信息(Filtering)

如果记录数量很多，服务器不可能都将它们返回给用户。API应该提供参数，过滤返回结果。 下面是一些常见的参数。

?limit=10：指定返回记录的数量
?offset=10：指定返回记录的开始位置。
?page=2&per_page=100：指定第几页，以及每页的记录数。
?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。
?animal_type_id=1：指定筛选条件

参数的设计允许存在冗余，即允许API路径和URL参数偶尔有重复。比如，GET /zoo/ID/animals 与 GET /animals?zoo_id=ID 的含义是相同的。    

接口返回定义

数据标准返回code，data,message这3个字段，如果有额外的字段可以自行添加, 如es_search_ts代表es查询耗费时间，对排错有帮助
 
code: 接口响应状态码
data: 接口返回数据
message： 返回给用户的提示
{
    code: 20000
    data: {}
    message: "操作成功"
}

接口返回原则

返回message

1、不能出现页面一堆报错飘红的情况(即使某个组件出错，也需要catch住，但是需要能报出来,比如通过debug或者返回中增加额外错误信息展示字段) 2、报错类型尽量详细，每种返回简明致意，不要返回看到了也不知道什么原因的信息 3、有调试机制，开启后可以在返回中增加一个字段显示代码track信息

返回状态码

status	含义
200	成功的状态，成功又分两种code：20000表示后端校验通过，返回正确的数据； 40000表示后端验证不通过，把错误信息返回给前端展示
500	服务端异常，错误信息不展示
401	未登陆状态，给提示，用户点击确定按钮，跳转登陆页面
403	权限问题，api没有权限，重定向到登陆页面
404	路由没有权限或不存在，跳转默认的首页

返回翻页信息

{
    "totalDoc":0, # 文档总数
    "items": [] # 具体的数据信息
}