Skip to content

Instantly share code, notes, and snippets.

Show Gist options
  • Save AllenCoder/d42c43951dc681d9be62dabf098ddfa0 to your computer and use it in GitHub Desktop.
Save AllenCoder/d42c43951dc681d9be62dabf098ddfa0 to your computer and use it in GitHub Desktop.
-- 引言 --
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,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}, ...]
-- 结束语 --
不是每一个接口都必须存在于每一个项目,具体需要哪些接口,根据实际业务需求来添加。
此种规范的提供的操作全是原子级别的操作,当你要实现某个复杂的需求时,可以通过组合这几个接口实现你需要的功能。
以上规范并不能解决开发过程中的全部问题(比如密码检查接口,你不可能在数据库中存明文密码吧?)。我的建议是,在遇到问题时,应优先使用这些接口来解决你的问题,不能解决时再考虑开发特殊接口处理。
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment