1 概述
scarecrow(稻草人)是基于数据库模型,使用SQLAlchemy提供REST风格API接口的简单快速生成方式, 生成的接口满足JSON规范要求。
scarecrow主要的核心代码源于1847业务系统的核心模块,并参照了部分tornado-restless的代码, 并初步具备RBAC(Role-Based Access Control)功能。
2 框架组织结构简介
<proj-name>
| -- <scarecrow>
| -- <tornado_rbac>
| -- __init__.py # RBAC权限管控模块
| -- model.py # RBAC数据库模型
| -- __init__.py
| -- api.py # tornado Application类
| -- errors.py # HTTP状态码模块
| -- globals.py # 全局参数模块
| -- handler.py # 路由处理模块
| -- wrapper.py # SQLAlchemy封装模块
| -- models.py # 数据库模型
| -- run.py # 程序运行入口
3 API接口风格介绍
举例说明:
比如,数据库中有一个表,表名为resource,它的接口为:
http://host-ip:host-port/api/tms/resource
注:/api/tms为接口URI的一个前缀,可以任意设置
那么它具备的访问方法为:
(1)POST
即创建接口,请求数据为resource表中的字段,返回的数据中会有errorcode标识创建成功与否的字段,
成功的话还会插入成功的数据,失败的话则没有。
操作示例:
curl -d '{"name":"hello"}' -H "Content-Type:application/json" http://host-ip:host-port/api/tms/resource
(2)DELETE
即删除接口,此类接口有二种,一类是根据条件删除,一类是根据主键删除
1> 根据条件删除
curl -X DELETE http://host-ip:host-port/api/tms/resource?name=hello
问号后面带的为删除条件,即满足name为hello的删除
2> 根据主键删除
curl -X DELETE http://host-ip:host-port/api/tms/resource/1,2
删除主键为1和2的数据,可以是批量删除,数据之间用逗号隔开
(3)PUT
即更新接口,此类接口也同样有二种,一类是根据条件更新,一类是根据主键更新
1> 根据条件删除
curl -X PUT -d '{"name":"haha"}' -H "Content-Type:application/json" http://host-ip:host-port/api/tms/resource?name=hello
将name为hello更新为haha
2> 根据主键删除
curl -X PUT -d '{"name":"haha"}' -H "Content-Type:application/json" http://host-ip:host-port/api/tms/resource/1,2
将主键为1和2的name更新为haha,同样可以是批量更新,数据之间用逗号隔开
(4)GET
即获取类接口,此类接口内容比较丰富:
1> 全部获取
curl http://host-ip:host-port/api/tms/resource
2> 根据主键获取
curl http://host-ip:host-port/api/tms/resource/1,2
3> 获取表中的某一列(某几列)
curl http://host-ip:host-port/api/tms/resource/name,id
即获取出来的数据只有name和id二列的值
4> 根据条件筛选数据
curl http://host-ip:host-port/api/tms/resource?name=hello\&id=2
即筛选name为hello并且id为2的数据
那么此时你是否会说,如果我要模糊搜索呢?也是支持的,例如
curl http://host-ip:host-port/api/tms/resource?filters=[{"name":"name", "op":"like", "value":"hel"}]
即搜索name中有出现hel字样的数据,它其它类似于数据库中的操作,支持的操作有:
is_null
is_not_null
is
is_not
==, eq, equals, equals_to
!=, ne, neq, not_equal_to, does_not_equal
>, gt
<, lt
>=, ge, gte, geq
<=, le, lte, leq
ilike
not_ilike
like
not_like
match
in
not_in
has
any
between
contains
startswith
endswith
attr_is
method_is
实际在用的时候,可能会有用到一些像or/not之类的操作,那么这儿是否也支持呢?答案是支持的,不过目前
只支持filters/or_/not_三大类,比如
curl http://host-ip:host-port/api/tms/resource?or_=[{"name":"name", "op":"like", "value":"hel"},{"name":"id", "op":"==", "value":"2"}]
搜索name中出现hel字样的数据或者id为2的数据,not_与之类似。
那如果要做多表联查呢?是不是也支持呢?哈哈,也是支持的,这儿支持那种多对多数据的查询,例如
curl http://host-ip:host-port/api/tms/resource/id/node
即根据resource的id值查找与之相关联的node信息
4 使用介绍
(1) 依赖环境
* python 2.6以上版本
* Tornado
* 数据库(支持PostgreSQL/MySQL等)
* SQLAlchemy
(2) 设置数据库连接
在globals.py中修改connector的值,程序启动时会根据这个值自动创建数据库,同时可以根据命令行参数
db的值去删除数据库,即设置db=drop。
(3) 创建tornado Application实例,并传递到ApiManager中去,然后使用这一实例创建相应的api.
Example:
import tornado.httpserver, tornado.web, tornado.ioloop
from scarecrow import ApiManager
app = tornado.web.Application([])
api = ApiManager(application=app)
api.create_api('resource', methods=api.METHODS_ALL, allow_patch_many=True)
# methods设置的是允许访问的方法,
# allow_patch_many是批量更新、删除开关,
# url_prefix设置URI的前缀
if __name__ == '__main__':
app.listen(8888)
tornado.ioloop.IOLoop.instance().start()
5 与Tornado-restless相比较
(1) Tornado-restless只支持python 3.0以上版本;
(2) 与Tornado-restless相比,scarecrow具备了Tornado-restless的所有风格接口,还多出了多表联查功能、
or_/not_类型的条件筛选、获取表中某几列的数据以及RBAC功能;
(3) 在使用上scarecrow要相对方便些,Tornado-restless在创建api的时候需要传进去的是一个表的class,而scarecrow只需要一个
表名,后面就能自己识别并转换能一个TableObject,除此之外,还可以将scarecrow应用到只知道数据库名称不知道数据库模型中去,
只要嵌入这么个程序,就能将数据库中的表提供api接口出来。