RESTful实战笔记二——REST API设计

比眉伴天荒 2021-11-05 03:12 334阅读 0赞

# 统一接口REST VS RPC #

REST使用HTTP协议的通用方法作为统一接口的词汇，方法信息都在HTTP方法里；

RPC服务提供的方法信息在SOAP/HTTP信封里。

# REST方法设计 #

HTTP请求方法可以从安全性和幂等性进行考虑：

安全性：外系统对该接口的访问不会使服务器资源的状态发生改变；

幂等性：外系统对统一REST接口访问得到的资源状态是相同的。

<table style="width:500px;"> 
 <thead> 
  <tr> 
   <th style="width:74px;">方法名</th> 
   <th style="width:70px;">幂等性</th> 
   <th style="width:72px;">安全性</th> 
   <th style="width:282px;">补充</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td style="width:74px;">GET</td> 
   <td style="width:70px;">幂等</td> 
   <td style="width:72px;">安全</td> 
   <td style="width:282px;">只读的， 但是设计不良的API可能造成假GET</td> 
  </tr> 
  <tr> 
   <td style="width:74px;">PUT</td> 
   <td style="width:70px;">幂等</td> 
   <td style="width:72px;">不安全</td> 
   <td style="width:282px;">更新/添加资源，添加资源只有当客户端创建连接请求的时候使用PUT</td> 
  </tr> 
  <tr> 
   <td style="width:74px;">DELETE</td> 
   <td style="width:70px;">幂等</td> 
   <td style="width:72px;">不安全</td> 
   <td style="width:282px;">删除资源，可以返回void</td> 
  </tr> 
  <tr> 
   <td style="width:74px;">POST</td> 
   <td style="width:70px;">不幂等</td> 
   <td style="width:72px;">不安全</td> 
   <td style="width:282px;"> <p>添加资源；RESTful中为POST(a),RPC中为POST(p)，需要先解析信封才能获取真正方法</p> </td> 
  </tr> 
 </tbody> 
</table>

**WebDAV** 对HTTP1.1的扩展协议，增加了些协作方法，但是违背了REST统一接口受歧义。

## Demo ##

[REST方法测试Demo][REST_Demo]

# REST资源设计 #

资源地址的设计是面向资源的，资源名称应是准确描述该资源的名词，资源地址应具有直观的描述性。一个URI资源地址唯一对应一个资源，但是一个资源可以拥有多个RUI资源地址。

资源地址的设计良否涉及系统的可用性、可维护性和可扩展性等诸多方面的表现。

## 资源地址 ##

资源地址具体可以分为五个部分： scheme://host:port/path?queryString

<table>  资源地址路径分解  
 <thead> 
  <tr> 
   <th>元素</th> 
   <th>描述</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>scheme</td> 
   <td>协议名称，通常是HTTP和HTTPS</td> 
  </tr> 
  <tr> 
   <td>host</td> 
   <td>（DNS）主机名或IP地址</td> 
  </tr> 
  <tr> 
   <td>port</td> 
   <td>服务端口</td> 
  </tr> 
  <tr> 
   <td>path</td> 
   <td>资源地址，用“/“符号分隔逻辑上的层级结构</td> 
  </tr> 
  <tr> 
   <td>？</td> 
   <td>用来分隔资源地址和查询字符串的符号</td> 
  </tr> 
  <tr> 
   <td>queryString</td> 
   <td> <p>查询字符串，方法作用域信息</p> <p>使用”&amp;“符号分隔查询条件</p> <p>使用逗号分隔有次序的作用域信息</p> <p>使用分号分隔五次序的作用域信息</p> </td> 
  </tr> 
 </tbody> 
</table>

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl8zODkzMDcwNg_size_16_color_FFFFFF_t_70][]

<table>  资源地址设计  
 <thead> 
  <tr> 
   <th>功能</th> 
   <th>资源地址</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>添加/创建</td> 
   <td> <p>POST /books</p> <p>PUT /books/{id}</p> </td> 
   <td>&nbsp;</td> 
  </tr> 
  <tr> 
   <td>删除</td> 
   <td>DELETE /books/{id}</td> 
   <td>&nbsp;</td> 
  </tr> 
  <tr> 
   <td>修改/更新</td> 
   <td>PUT /books/{id}</td> 
   <td>&nbsp;</td> 
  </tr> 
  <tr> 
   <td>查询全部</td> 
   <td>GET /books HTTP1.1</td> 
   <td>&nbsp;</td> 
  </tr> 
  <tr> 
   <td>主键查询</td> 
   <td> <p>GET /books/{id} HTTP1.1</p> <p>GET /books?id=132456789</p> </td> 
   <td>&nbsp;</td> 
  </tr> 
  <tr> 
   <td>分页作用域查询</td> 
   <td> <p>GET /books?start=0&amp;size=10</p> <p>GET /books/01,2002-12,2014</p> <p>GET /books/restful;program=java;type=web</p> <p>GET /books?limit=100&amp;sort=bookname</p> </td> 
   <td> <p>起始页0，页条10；</p> <p>逗号分隔次序：2002年1月到2014年12月</p> <p>分号做并列查询，查询条件同级</p> <p>每页100条，按书名排序</p> </td> 
  </tr> 
 </tbody> 
</table>

[REST_Demo]: https://github.com/feuyeux/jax-rs2-guide-II/tree/master/2.simple-service-3
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl8zODkzMDcwNg_size_16_color_FFFFFF_t_70]: /images/20211104/bb3844a0d417413d99cab8d7ac81979f.png