最近要准备新同事的开发规范培训，所以大概理了理开发过程中总结的一些注意点和规范,有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": [] # 具体的数据信息 } ```