背景

在团队两年多陆续负责了几个项目的开发上线已经代码的review，特别是对老项目的重构过程中，发现之前的API设计是没有任何规范和约定的，不同的开发同学有不同的习惯，因此需要一套规范去约定，现在分享一下我们目前试运行的一套规范，一起交流完善下。

WebAPI开发流程

第一步首先设计接口文档，公司内部有一套自研的多人协作文档系统，可以很好的做到这一步，并能很好的做好版本控制。如果公司内部没有可以基于showdoc搭建一套
第二步有技术负责人确认接口以及字段的命名规范
第三步找对应API对接人，确认接口是否符合要求
这三步其实是个闭环，只有等到全部通过后才会正式开始开发API

命名规范

所有接口中不能出现拼音，统一用英语
不能有特殊字符，例如/
接口命名遵循像个原则: 简单 易懂
出入参规范
命名规范参考之前的一篇文章
若需要使用分割符，只可以使用中划线 -
禁止把所有数据库字段全部返回，统一使用Dto,只返回调用方需要的字段
HTTP 请求方法使用规范

根据 HTTP 标准，HTTP 请求可以使用多种请求方法。
HTTP1.0 定义了三种请求方法： GET, POST 和 HEAD方法。
HTTP1.1 新增了六种请求方法：OPTIONS、PUT、PATCH、DELETE、TRACE 和 CONNECT 方法。
这里统一只是用 GET, POST,PUT,DELETE,PATCH

GET（SELECT）：从服务器获取单个资源或者资源列表
POST（CREATE）：发送请求创建一个新的资源
PUT（UPDATE）：通过接口更新服务器上的资源信息，资源内容全量更新，提供资源全部字段信息
DELETE（DELETE）：通过删除服务器上的资源
PATCH（UPDATE）：通过接口更新服务器上的资源信息，资源内容增量更新，仅提供更新的属性信息
具体使用规范，使用GET查询获取信息，POST创建新的资源，PUT修改已存在资源信息，DELETE删除服务器资源信息，不强制要求使用Patch。

HTTP码状态使用规范

200 OK ：成功
201 CREATED：成功创建数据不强制使用，可以使用200
400 Bad Request：提交的参数错误。错误信息中要能体现哪个parameter没有通过validation，为什么
401 Unauthorized：客户端传入了一个无效的auth token。客户端需要更新token进行重试，包括让用户重新登陆
403 Forbidden：访问被拒绝。最常见的case为水平越权。和401的区别是：如果改接口需要用户登陆，无有效的登陆token，则返回401，表示登陆验证未通过。登陆验证通过后，但是因为要操作的资源没有权限，则返回403.比如用户更新或者删除不属于自己的resource
404 Not Found：资源为找到
429 Too Many Requests：对于限频接口请求次数超频
500 Internal Server Error：应用服务器内部错误
502 Bad Gateway：网关或者代理处理请求错误
503 Service Unavailable：应用服务器暂时不可用
504 Gateway Timeout：网关超时。网关从上游服务没有在设定的时长内获取到数据。

自定义Header规范，

x-[应用英文缩写]-[语义化英文单词说明用途]

示例：
X-Test-Authorization: qwaszxerdfcvtyghbn

返回规范

全部统一使用 Content-Type = application/json 格式返回

请求失败的Response

Http码的状态为200或者201
code统一为 200，message 为success
isSuccess为true
有返回值时，统一通过data返回,无返回值时为{}，禁止使用null返回
返回的header中追加标记本次请求的唯一值的 X-[项目英文缩写]-ResponseId


{
'isSuccess': true,
'code': 200,
'message': 'success',
'data': {
'id': 0,
'value': 'Default'
},
'timestamp': '02/02/2020 13:19:22'
}

请求异常的Response

Http码的状态根据上一小节介绍的按需使用
code和http码对应，message 为对应异常说明
isSuccess为false
data统一返回为{}
返回的header中追加标记本次请求的唯一值的 X-[项目英文缩写]-ResponseId


{
'isSuccess': false,
'code': 400,
'message': 'Bad Request',
'value': {},
'timestamp': '02/02/2020 13:35:33'
}

接口注释说明

约定

项目统一使用swagger
接口相关的文档地址
相关jira.$ 分割 XXX-XXX $ XXX-XXX
可能的返回的状态码
对应参数说明

[c#] view plaincopyprint?

<code class='hljs cs'>/// <summary>
/// PUT api/values/5
/// </summary>
/// <param name='id'>id</param>
/// <param name='dto'>dto</param>
/// <remarks>
/// <url>doc: https://www.cnblogs.com/sagecheng/</url>
///
///
/// <jira>jira: XXX-XXX</jira>
/// </remarks>
/// <returns></returns>
/// <response code='200'> success </response>
/// <response code='400'>If the id is null</response>
/// <response code='404'>If the id is not found</response>
[HttpPut('{id}')]
[ProducesResponseType(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public ApiResult Put(int id, [FromBody] ValueDto dto)
{
var info = values.FirstOrDefault(o => o.Id == id);
if (info == null)
{
throw new ApiException(StatusCodes.Status404NotFound, 'Not Found');
}
info.Value = dto.Value;
return ApiResult.GetSuccessResult();
}</code>


/// <summary>
/// PUT api/values/5
/// </summary>
/// <param name='id'>id</param>
/// <param name='dto'>dto</param>
/// <remarks>
/// <url>doc: https://www.cnblogs.com/sagecheng/</url> <br/>
/// <br/>
/// <br/>
/// <jira>jira: XXX-XXX</jira>
/// </remarks>
/// <returns></returns>
/// <response code='200'> success </response>
/// <response code='400'>If the id is null</response>
/// <response code='404'>If the id is not found</response>
[HttpPut('{id}')]
[ProducesResponseType(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public ApiResult Put(int id, [FromBody] ValueDto dto)
{
var info = values.FirstOrDefault(o => o.Id == id);
if (info == null)
{
throw new ApiException(StatusCodes.Status404NotFound, 'Not Found');
}
info.Value = dto.Value;
return ApiResult.GetSuccessResult();
}

Swagger相关效果

整体效果

注释效果

本站仅提供存储服务，所有内容均由用户发布，如发现有害或侵权内容，请点击举报。

背景