前言

开发规范类似API，是各个公司和团队内部约定俗成的东西，目的是为了业内人员在彼此交流时提升沟通效率，避免各自为营，从而产生鸡同鸭讲、牛头不对马嘴的场景。

举个例子，A和B一起开发一个人员管理系统，A用Java语言进行开发一部分功能，B用PHP语言进行开发一部分功能，最后合并上线时发现语言不兼容架构不一致导致系统用不了。所以在开发之前需先与A和B规定使用特定的开发语言（比如Java），而这就是一种规范。

规范 & 原则文档

• 《阿里巴巴开发手册》：alibaba.github.io/p3c/
• 《API Design Patterns》中文翻译：github.com/evan-ysj/AP…
• 《github OpenAPI-Specification》：github.com/OAI/OpenAPI…
• 《MySQL设计规范》：github.com/guanguans/n…
• 《应用程序日志规范》：github.com/bingoohuang…
• 《单元测试规范和mock进阶使用实例》：github.com/cyneck/unit…
• 《你必须知道的Git分支开发规范》：ricardolsw.github.io/%E5%B7%A5%E…
• 《Apache架构师的30条设计原则》：github.com/baicaihenxi…

API设计

API管理

Swagger 2.0

RestFul 风格

API用途

常规API：一般面向内部前端页面，灵活性比OpenAPI好，变动影响范围较小

OpenAPI：面向所有用户，刚性，变动可能导致用户系统不可用

方法

GET（Select）：从服务器取资源（一项或多项）

POST（Create）：在服务器新建资源

PUT（Update）：在服务器更新资源（客户端提供改变后的完整资源）

PATCH（Update）：在服务器更新资源（客户端提供改变的属性）

Delete（delete）：从服务器删除资源

HEAD：获取资源的元数据

OPTIONS：获取信息，关于资源的哪些属性是客户端可以改变的

命名

url

使用"-"进行拼接

# 正例

# 反例

字段

使用"_"进行拼接

请求

鉴权相关参数放在Header

响应

响应码，数据，错误码，具体信息 数据格式使用json

安全性与幂等性

版本控制

接口预留版本升级（/v1/xxx,/v2/xxx）

接口限流

权限校验

数据库设计

错误码

日志

日志文件分离 什么时候记录日志 日志级别 日志格式规范 日志内容

异常处理

全局异常处理兜底

异常发生后要分析是中断业务还是内部消化，打印相关日志

异常响应需要规定错误码及对应的错误描述

UT

覆盖率：类覆盖，接口覆盖，行覆盖，分支覆盖，正常/异常场景覆盖

哪些内容需要覆盖

命名：类、方法

断言

测试数据

打桩

Git分支开发规范

分支命名

分支类型

版本发布/特性开发/bug修复