最近要准备新同事的开发规范培训,所以大概理了理开发过程中总结的一些注意点和规范,有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中的信息对应上 ``` ![image.png](https://s2.51cto.com/images/20210609/1623244379735624.png?x-oss-process=image/watermark,size_14,text_QDUxQ1RP5Y2a5a6i,color_FFFFFF,t_100,g_se,x_10,y_10,shadow_20,type_ZmFuZ3poZW5naGVpdGk=) # 设计原则   ``` 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": [] # 具体的数据信息 } ```