REST服务的URI设计

阳光穿透心脏的1/2处 2022-06-06 10:56 161阅读 0赞

REST服务的URI设计

*  第一前言
 *  第二什么是资源怎么抽离
 *  第三URI命名规范
 *  第四重点

# 第一：前言 #

我们一般写API常用的逻辑思维是以“动作”为中心，比如购买商品，要查询商品列表添加购物车，提交订单，写接口不外乎“listGoods, addCarts，submitOrders”等， 这些接口常常是表达某种动作。  
而REST服务抽象出了“资源”的概念，API设计将不再以执行了什么动作为中心，而是以资源为中心。一些对资源的通用操作有添加，取得，修改，删除，以及对符合特定条件的资源进行列表操作。  
与之对应的是系统设计步骤的不同，首先想的不是“为了完成系统业务需要哪些动作，而是为了完成系统业务需要哪些资源。  
在设计URI之前，我们需要了解一些概念，比如何为资源？

> **当然对于我们实用主义的人来说，这些概念了解了解即可，这些资源概念即使在以动作为中心的API设计里依然存在，只是我们没用明确的红线标识出来而已，不要被“资源”的概念进入坑里了。**
> 
>  RESTful的定义是HTTP 1.1标准的一部分。具体实现和语言无关。而解析RESTful URL是由实现HTTP服务的组件来进行的，具体是哪种并不重要。  
> RESTful是一种（推荐的）命名规范和设计思路。所以你并不需要强迫自己按照它的方式走。只是这是一种推荐而已。不要为了RESTful而RESTful

# 第二：什么是资源，怎么抽离 #

REST里一切都是资源，它是概念上的一种抽象，比如电商平台，资源肯定包括订单，购物车，商品，商品分类，帐户等。  
判断资源的抽象是否合理，一般使用如下方法：  
对应资源的CRUD是否产生意义。比如删除商品，那该商品必需没有了，说明对资源的操作产生了意义。比如如果把商品的分布功能也抽成的资源，那对删除某页的商品后，该页数据并没消除而是被后面一页替换了，即做删除并没有产生意义（当然对整体而言数据变少了，但对应的资源是“商品”而不是“商品分布”资源）  
资源抽象出来有主资源和子资源之分。主资源实际上就是能够独立存在的一系列资源。而子资源则需要依附于主资源之上才能表达实际的意义。同时各个子资源也可能拥有自身的子资源。比如把主资源删了，但子资源依然可以被其它资源重用，那这个子资源可视为主资源。  
区分主资源和子资源实际上是为了URI命名做准备的。

# 第三：URI命名规范 #

抽象出资源概念后，我们就可以为资源设计URI了。  
这里使用的“根路径”是“/api”，即统一的API相对根路径入口，相信使用过SpringMVC的同学都明白。以下以订单“orders”资源为例。  
“orders”是个主资源，由于主资源是一类独立的资源，因此它应该直接置于/api下。如下

/api/orders

1.获取订单类型的特定实例，在主资源的URI里加上资源ID，通俗说法是根据cd值查询订单

/api/orders/1234

2.按帐户主键分布查询

/api/orders/1(acctPk)/page

3.不可避免的一个问题是参数是放在URI里还是请求参数里。我的原则是如下2点：  
1.任何参数都可以放在请求参数里，因为请求参数它不会影响URI路径，但放在URI里就不一样的，对于确定不了的就用请求参数携带数据。

2.对于多个（至少2个）可选的参数放在请求参数里。对于单个可放在URI里。比如  
2个以上的参数：以egoods中的手机为例。在选择手机时，用户可以选择品牌以及颜色。如果将品牌和颜色都定义在相对URL中，那么具有特定品牌和颜色的手机将可以通过两个不同的URL访问：/api/mobiles/brand/\{brand\}/color/\{color\}以及/api/mobiles/color/\{color\}/brand/\{brand\}。就用户而言，其并无法了解这两个URL所表示的是同一类资源还是不同类型的资源。当然，您可以说，我们只用/api/mobiles/brand/\{brand\}/color/\{color\}。但是该URL将无法处理用户仅仅选择了颜色，却没有选择品牌的情况。  
单个参数：比如订单下某个cd的实例  
orders/1  
查询cd值是1的订单，因为cd值是条件固定的，可放在URI里。但如果按订单号和订单名称云查询就不一样的，如果放在URI里有前后顺序，有可能没先订单名称或cd。就像上面的2个以上参数一样。  
有种特殊的情况，“条件固定且条件顺序固定”，也可以放在URI里。  
总的来说，放在哪里并没有明确的要求。不要为了规范而规范。

# 第四：重点 #

使用HTTP动词表示请求的目的。  
比如：  
GET /tickets \# 获取ticket列表  
GET /tickets/12 \# 查看某个具体的ticket  
POST /tickets \# 新建一个ticket  
PUT /tickets/12 \# 更新ticket 12.  
DELETE /tickets/12 \#删除ticekt 12  
可以看出使用REST的好处在于可以充分利用http的强大实现对资源的CURD功能。**接口名称一样，但使用不同的HTTP动态会进入不同的接口。**