WebAPI接口开发实践

2019/04/10 10:10
阅读数 11

背景

在团队两年多陆续负责了几个项目的开发上线已经代码的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
  • 接口相关的文档地址 <url></url>
  • 相关jira.$ 分割 <jira>XXX-XXX $ XXX-XXX</jira>
  • 可能的返回的状态码
  • 对应参数说明
/// <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相关效果

整体效果 avatar

注释效果 avatar

参考文章

Swashbuckle 和 ASP.NET Core 入门

原文出处:https://www.cnblogs.com/sagecheng/p/12250774.html

展开阅读全文
打赏
0
0 收藏
分享
加载中
更多评论
打赏
0 评论
0 收藏
0
分享
返回顶部
顶部