现在单页 Web 项目很流行,使用各种 Js 框架,通过 Ajax 和服务器的 Api 进行交互,实现类似原生 app 效果,很酷,对 Flask 来说小菜一碟,是时候了解下 Flask-RESTful 了
开始前先了解下 RESTful,阮一峰老师有这样的解释:
网络应用程序,分为前端和后端两个部分。当前的发展趋势,就是前端设备层出不穷(手机、平板、桌面电脑、其他专用设备……)。 因此,必须有一种统一的机制,方便不同的前端设备与后端进行通信。这导致API构架的流行,甚至出现”API First”的设计思想。RESTful API是目前比较成熟的一套互联网应用程序的API设计理论
也就是说 RESTful 一个框架和互联网应用的设计原则,遵循这个设计原则,可以让应用脱离前台展现的束缚,支持不同的前端设备。
安装
Flask 的 RESTful 模块是 flask-restful ,使用 pip 安装:
1 |
|
如果安装顺利,可以在 Python Shell 环境下导入
1 |
|
小试牛刀
安装好后,简单试试。 flask-restful 像之前的 bootstrop-flask 以及 flask-sqlalchamy 模块一样,使用前需要对 Flask 应用进行初始化,然后会得到当前应用的 api 对象,用 api 对象进行资源绑定和路由设置:
1 |
|
上面代码中从 flask_restful 中引入的 Resource 类是用来定义资源的,具体资源必须是 Resource 的子类,下面定义一个 HelloRESTful 资源:
1 |
|
接着,给资源绑定 URI:
1 |
|
在终端或者命令行下运行 python app.py
启动应用
访问 localhost:5000
或者 127.0.0.1:5000
查看效果,将会看到 JSON 格式的数据输出:
1 |
|
也可以用 curl 工具在终端或者命令行下发送请求:
1 |
|
curl 的参数 -s 是开启安静模式的意思
资源
从上面代码中可以看到,资源是 Resource 类的子类,以请求方法( GET、POST 等)名称的小写形式定义的方法,能对对应方法的请求作出相应,例如上面资源类中定义的 get
方法可以对 GET
请求作出相应,还可以定义 put
、post
、delete
等,称之为视图方法。
例如创建一个 todo 字样,支持获取代办事项和新增代办事项:
1 |
|
- 通过 GET 方式,提供 todo_id, 从 todos 列表中获取待办事项内容
- 通过 PUT 方式,提供 todo_id, 从请求体中获取到内容,作为待办事项内容
- 两种方法都返回 todo_id 所对应的待办事项内容
为 Todo 资源指定 URI:
1 |
|
启动项目,用 curl 工具测试:
1 |
|
Flask-RESTful 支持多种视图方法的返回值:
1 |
|
为三个资源指定 URI:
1 |
|
启动项目后,用 curl 工具来测试:
1 |
|
路由
从上面可以看到,通过 api.add_resource 方法来为资源设置路由
第一个参数是资源类,第二个参数是路由,和之前介绍的 @app.route
注解参数一样
可以为一个资源制定多个理由,例如:
1 |
|
http://localhost:5000/todo/
和 http://localhost:5000/mytodo/
都将指向 Todo
既然路由,就应该有 endpoint
,通过命名参数 endpoint
指定:
1 |
|
设置路由的 endpoint
为 todo_ep
,如果不指定,endpoint
就是资源类名的小写形式
endpoint
是 Flask 中对具体路由的内部的具体定义,一般作为 url_for
方法的第一个参数,即通过 endpoint
获得该路由的 URL,在列出 RESTful 资源 URL 时非常有用。
请求解析
RESTful 服务器对请求数据有很强的依赖,就请求数据的获取及校验是很繁琐的事情,还好 Flask-RESTful 提供了非常好的请求解析工具 reqparse
,不仅可以获取请求数据,还可以对数据进行校验并返回合适的错误消息。
1 |
|
看下效果:
1 |
|
- 当参数校验失败,自动返回 400 状态码,以及错误信息,通过命名参数 help 设置错误信息,不提供会有默认信息,如比选参数 name 的错误信息。
- 默认情况下有多个参数错误,会以定义参数的顺序,逐个显示错误,定义解析器时将 bundle_errors 设置为 True,则可显示多个错误,如
parser = reqparse.RequestParser(bundle_errors=True)
,或者设置应用配置,如app.config['BUNDLE_ERRORS'] = True
- 默认情况下参数都是从请求表单中获取,定义参数时命名参数 location 可以指定从 form、headers、args(即 querystring)还是从 cookies 等中获取,如
parser.add_argument('id', type=int, help='必须提供参数 id', location='args')
请求解析器支持继承,可以定义最高级别的解析器,逐渐细化,最后应用的具体资源上:
1 |
|
格式化输出
请求解析处理用收到的信息,对于输入的信息也可以处理,通过 Flask-RESTful 提供的类 fields 和注解 marshal_with 来实现:
1 |
|
- 定义一个字段格式化模板,属性用 fields 的类型方法定义
- 在响应方法上加上
marshal_with
注解,指定格式化模板,和封装属性名
格式化模板属性名,需要在响应函数返回的对象属性中匹配,如果需要会要对字段重命名,可以这样:
1 |
|
返回值中没有可以定义默认值:
1 |
|
总结
本节课程简单介绍了 Flask 如何玩 RESTful,通过对 RESTful 的说明,讲解了 Flask-RESTful 模块的用法,并简单讲解了资源、路由,以及请求解析和格式化输出等技术
参考