NingG +

开发实践:RESTFul 接口规范

1. 从需求入手

2. 资源分类

3. 设计 URI

3.1. URI 命名

3.2. URI 结构

几点:

3.2.1. 路径变量

id为8的deal的评论列表:

  • /deal/8/comments

id为8的商家下第88条评论:

  • /merchant/8/comment/88

上述通过实体关联关系进行路径导航,一般是 id 导航;如果实体之间关联层级过深,则,使用查询参数,替代路径层级导航。

组合实体的访问:必须通过父实体的 id导航访问。组合实体不是first-class的实体,它的生命周期完全依赖父实体,无法独立存在,在实现上通常是对数据库表中某些列的抽象,不直接对应表,也无id。

3.2.2. 路径标点

”.”表达不同的representation,约定 Response 返回的数据格式

3.3. URI 对外暴露的方法

GET,获取服务器的资源:

POST,创建资源:

备注:幂等,多次操作与只进行一次的效果相同。

PUT,创建资源和更新资源:

DELETE,删除资源:

HTTP 请求返回码:

HTTP 常见状态码:

小结

REST,Representational States Transfer,表现层状态转化 & 有状态传输,本质上:REST 关注于资源,将所有的内容看做一个资源:图片、文本、计算,为每一个资源分配唯一的地址,并对这些资源进行规范的操作。

几个方面:

4. URL 补充

避免层级过深的 URL,/ 在 URL 中表示层级,按实体关联关系进行对象导航,通常是 id 导航。

过深的 URL 层级导航,容易造成 URL 迅速膨胀,例如:GET /zoo/1/area/2/animal/3,推荐使用查询参数,替代路径中的实体导航,例如:GET /zoo/1?area=2&animal=3

5. 请求及返回内容的规范

几点:

//  单个对象
{
   "data" : {
        "bdId" : 8,
        "bdName": "Rongjun",
        "commission" : 1200.00,
        ...
    }
}
 
// 多个对象
{
     "data" : [
           {
              "code" : "1234567890",
              "status": 0,
           },
           {
              "code" : "234578901",
              "status": 128,
           }
           ...
      ]
     "paging" : {
           "offset" : 0,
           "limit" : 20,
       "total" : 100
      }
}
 
// 错误信息
{
    "error" : {
        "code" : 401,  /* code 仅用于表示有错误,相同的 code 可能有不同的 type 和 message */
        "type" : "PermissionDenied",   /* type表示真正的错误类型,错误类型的唯一标示 */
        "message" : "抱歉,你没有足够的权限" /* 错误对应的详细说明,和type成对。可以理解type是title,message是body */
    }
}
 

POST/PUT 提交的请求数据:

疑问:Request 通过 POST 方式传递数据时,如何定义数据的编码格式?

6. 猫眼演出接口约定

整体上遵循技术文档-前后端约定,补充一些:

7. 异常处理

出现异常时,要满足两种场景:

  1. 开发调试时,方便看到完整的异常信息,方便调试
  2. 线上服务时,屏蔽异常细节信息,只需向用户显示提示信息

技术上,两种情况:

  1. 请求 Web 页面,出现异常,或者 model 中属性异常
  2. 调用 API 端口,出现异常,通常是 Ajax 请求对应的 JSON 数据

从业务与非业务角度,异常分为两类:

  1. 业务异常:自己的业务代码抛出,表示一个用例的前置条件不满足、业务规则冲突等,比如参数校验不通过、权限校验失败。抛出异常,好处:终止业务逻辑的继续执行。
  2. 非业务异常:表示不在预期内的问题,通常由类库、框架抛出,或由于自己的代码逻辑错误导致,比如数据库连接失败、空指针异常、除0错误等等。

技术细节实现上,所有异常,返回给用户时,都需要两类信息:

  1. 异常对应的HTTP响应码
  2. 异常的文本描述信息

Spring MVC 下,具体技术解决方案:在Controller 层使用统一的异常拦截器:

8. 其他

常用命名方法:

出错信息:

// 错误信息
{
    "success": false,
    "data" : {
        "reason" : "没有权限",
        "message": "详细信息..."
    }
}

PUT vs. POST:

原文地址:https://ningg.top/develop-series-restful-api-intro/
微信公众号 ningg, 联系我

同类文章:

微信搜索: 公众号 ningg, 联系我, 交个朋友.

Top