-- 引言 -- 
 
 
 
 
 
 
 
 
 
 
 
 
  
  
  
 
 
  
  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” 
 
 
 
 
 
 
 
 
 
 
 
 
  
  
  
 
 
  
  注意： 
 
 
 
 
 
 
 
 
 
 
 
 
  
  
  
 
 
  
  1、以下接口中的“返回值”均为请求成功时的返回值，存在ok_json中的data里 
 
 
 
 
 
 
 
 
 
 
 
 
  
  
  
 
 
  
  2、在参数前面加上:的（如:user_id），说明此参数非必须；在参数前面加*的（如*user_id），说明此参数必须 
 
 
 
 
 
 
 
 
 
 
 
 
  
  
  
 
 
  
  3、列表返回值的结果，默认使用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,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},...] 
 
 
 
 
 
 
 
 
 
 
 
 
  
  
  
 
 
  
   
 
 
 
 
 
 
 
 
 
 
 
 
  
  
  
 
 
  
   
 
 
 
 
 
 
 
 
 
 
 
 
  
  
  
 
 
  
   
 
 
 
 
 
 
 
 
 
 
 
 
  
  
  
 
 
  
  -- 结束语 -- 
 
 
 
 
 
 
 
 
 
 
 
 
  
  
  
 
 
  
  不是每一个接口都必须存在于每一个项目，具体需要哪些接口，根据实际业务需求来添加。 
 
 
 
 
 
 
 
 
 
 
 
 
  
  
  
 
 
  
  此种规范的提供的操作全是原子级别的操作，当你要实现某个复杂的需求时，可以通过组合这几个接口实现你需要的功能。 
 
 
 
 
 
 
 
 
 
 
 
 
  
  
  
 
 
  
  以上规范并不能解决开发过程中的全部问题（比如密码检查接口，你不可能在数据库中存明文密码吧？）。我的建议是，在遇到问题时，应优先使用这些接口来解决你的问题，不能解决时再考虑开发特殊接口处理。