类Restful接口设计规范

 

  
  -- 引言 -- 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  Restful是一种很是优美的http接口设计风格及设计规范。使用restful原理来设计接口，能够很是显著地下降多个系统之间的耦合性，也可使得接口变得很是一致，不只美观，并且容易理解和上手。 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  然而在实际工做中，彷佛很难真正用上彻底的Restful，理想和现实老是有差距的- - 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  经过不断地实践概括，结合restful的核心原理，我小结出了一套类Restful接口规范。它基本上解决了我在项目中遇到的90%的问题，自我感受良好，哈哈。 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
    

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  -- 正文 -- 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  == 请求/响应规范 == 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
    

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  请求 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  GET: 使用url传参，如：?a=1&b=2 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  POST: 使用Json传参，从request.body中获取此Json，如：'{"a": 1, "b": 2}' 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
    

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  响应 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  返回值格式为json，分为成功返回（ok_json）和失败返回（fail_json） 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
    

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  ok_json示例： 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  {"ok": True, data: {"user_id": 1}, "echo": "", "error": "", "reason": ""} 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
    

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  fail_json示例： 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  {"ok": False, data: {}, "echo": "COMM_INVALID_ARGS", "error": "1001", "reason": "请求参数错误"} 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
    

 


 
 
 
 

 

 

  
  
  
  
  

 

  
    

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  == 接口规范 == 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  假设咱们的数据模型叫作“User” 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  注意： 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  一、如下接口中的“返回值”均为请求成功时的返回值，存在ok_json中的data里 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  二、在参数前面加上:的（如:user_id），说明此参数非必须；在参数前面加*的（如*user_id），说明此参数必须 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  三、列表返回值的结果，默认使用id逆序排序，即新建的数据在前。若是你在数据模型中本身定义了display_order，你就使用你的order进行排序 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
    

 


 
 
 
 

 

 

  
  
  
  
  

 

  
    

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【新增】/user/add/ 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【请求方式】POST 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【描述】提供新建一个User对象所须要的全部属性，新建成功后，将新建数据的id返回 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【参数】新建user所须要的全部参数，依据业务不一样有所不一样 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【返回值】：{"id": 3} 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
    

 


 
 
 
 

 

 

  
  
  
  
  

 

  
    

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【更新】/user/update/ 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【请求方式】POST 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【描述】根据提供的id更新对应记录的属性 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【参数】*user_id，*其余待更新的属性值（不包括删除标记） 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【返回值】{} 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
    

 


 
 
 
 

 

 

  
  
  
  
  

 

  
    

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【查看】/user/view/ 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【请求方式】GET 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【描述】提供记录id，返回对象的json化数据 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【参数】*user_id 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【返回值】{"id": "1", "username": "swpu-lee", "real_name": "lee", "gender": 0, ...} 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
    

 


 
 
 
 

 

 

  
  
  
  
  

 

  
    

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【删除】/user/delete/ 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【请求方式】GET 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【描述】删除一条数据。在个人实际项目中，每每只是对记录标记如下is_deleted为True。对于全部查询接口来讲，被标记为is_deleted的数据都应该查不到（也就是说这些接口在作数据查询时都要加上“is_deleted为False”这个条件） 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【参数】*user_id 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【返回值】{} 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
    

 


 
 
 
 

 

 

  
  
  
  
  

 

  
    

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【查询】/user/query/ 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【请求方式】GET 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【描述】得到知足指定过滤条件的数据，这个接口返回知足条件记录的id列表。此接口与实际使用相关，须要本身定义一个查询协议。 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【参数】依据实际需求有所不一样，如：{"age": "11-20", "eye_color": "red", ...} 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【返回值】[1, 2, 3, 5, 78, 121, ...] 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
    

 


 
 
 
 

 

 

  
  
  
  
  

 

  
    

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【批量查看】/user/view/bulk/ 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【请求方式】GET 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【描述】根据提供的ids批量查看数据。此接口能够配合Query接口进行批量查看 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【参数】*user_ids（格式为："1,2,3,4,5"，用逗号隔开） 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【返回值】{"1": {用户1的数据}, "2": {用户2的数据}, "3": {用户3的数据}, ...} 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
    

 


 
 
 
 

 

 

  
  
  
  
  

 

  
    

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  ### 如下两个接口在这个user的例子中，不是很好体现这个接口的价值，因此我改用“用户相册”的例子 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【列表】/photo/album/list/ 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【请求方式】GET 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【描述】查看照片列表，当请求参数中有user_id时，得到指定用户的相册的列表，不然返回全体用户的相册列表。另外此接口须要返回记录总数，这样能够供其余应用作分页使用 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【参数】:user_id默认为None，:offset默认0，:limit默认20，返回数据的json列表以及总数据量 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【返回值】{"total_count": 101, "list": [{相册1}, {相册2}, {相册3}, ...]} 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
    

 


 
 
 
 

 

 

  
  
  
  
  

 

  
    

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【所有】/phtot/album/all/ 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【请求方式】GET 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【描述】返回指定用户的全部相册 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【参数】*user_id 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  【返回值】[{相册1}, {相册2}, {相册3}, ...] 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
    

 


 
 
 
 

 

 

  
  
  
  
  

 

  
    

 


 
 
 
 

 

 

  
  
  
  
  

 

  
    

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  -- 结束语 -- 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  不是每个接口都必须存在于每个项目，具体须要哪些接口，根据实际业务需求来添加。 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  此种规范的提供的操做全是原子级别的操做，当你要实现某个复杂的需求时，能够经过组合这几个接口实现你须要的功能。 

 


 
 
 
 

 

 

  
  
  
  
  

 

  
  以上规范并不能解决开发过程当中的所有问题（好比密码检查接口，你不可能在数据库中存明文密码吧？）。个人建议是，在遇到问题时，应优先使用这些接口来解决你的问题，不能解决时再考虑开发特殊接口处理。