标签:效果 表示 现在 一个 com 属性 produces rev pre
在团队两年多陆续负责了几个项目的开发上线已经代码的review,特别是对老项目的重构过程中,发现之前的API设计是没有任何规范和约定的,不同的开发同学有不同的习惯,因此需要一套规范去约定,现在分享一下我们目前试运行的一套规范,一起交流完善下。
第三步找对应API对接人,确认接口是否符合要求
这三步其实是个闭环,只有等到全部通过后才会正式开始开发API
/
接口命名遵循像个原则: 简单
易懂
-
禁止把所有数据库字段全部返回,统一使用Dto,只返回调用方需要的字段
根据 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。
x-[应用英文缩写]-[语义化英文单词说明用途]
示例:
X-Test-Authorization: qwaszxerdfcvtyghbn
全部统一使用
Content-Type = application/json
格式返回
success
true
data
返回,无返回值时为{}
,禁止使用null
返回X-[项目英文缩写]-ResponseId
{
"isSuccess": true,
"code": 200,
"message": "success",
"data": {
"id": 0,
"value": "Default"
},
"timestamp": "02/02/2020 13:19:22"
}
false
data
统一返回为{}
X-[项目英文缩写]-ResponseId
{
"isSuccess": false,
"code": 400,
"message": "Bad Request",
"value": {},
"timestamp": "02/02/2020 13:35:33"
}
/// <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();
}
整体效果
注释效果
标签:效果 表示 现在 一个 com 属性 produces rev pre
原文地址:https://www.cnblogs.com/sagecheng/p/12250774.html