【原】第47天：Web 开发 RESTful

现在单页 Web 项目很流行，使用各种 Js 框架，通过 Ajax 和服务器的 Api 进行交互，实现类似原生 app 效果，很酷，对 Flask 来说小菜一碟，是时候了解下 Flask-RESTful 了

开始前先了解下 RESTful，阮一峰老师有这样的解释:

网络应用程序，分为前端和后端两个部分。当前的发展趋势，就是前端设备层出不穷（手机、平板、桌面电脑、其他专用设备......）。因此，必须有一种统一的机制，方便不同的前端设备与后端进行通信。这导致API构架的流行，甚至出现"API First"的设计思想。RESTful API是目前比较成熟的一套互联网应用程序的API设计理论

也就是说 RESTful 一个框架和互联网应用的设计原则，遵循这个设计原则，可以让应用脱离前台展现的束缚，支持不同的前端设备。

安装

Flask 的 RESTful 模块是 flask-restful ，使用 pip 安装:

pip install flask-restful

如果安装顺利，可以在 Python Shell 环境下导入

>>> from flask_restful import Api>>>

小试牛刀

安装好后，简单试试。flask-restful 像之前的 bootstrop-flask 以及 flask-sqlalchamy 模块一样，使用前需要对 Flask 应用进行初始化，然后会得到当前应用的 api 对象，用 api 对象进行资源绑定和路由设置：

from flask import Flaskfrom flask_restful import Api, Resource
app = Flask(__name__)
api = Api(app) # 初始化得到 api 对象

上面代码中从 flask_restful 中引入的 Resource 类是用来定义资源的，具体资源必须是 Resource 的子类，下面定义一个 HelloRESTful 资源:

class HelloRESTful(Resource): def get(self): return {'greet': 'Hello Flask RESTful!'}

接着，给资源绑定 URI：

api.add_resource(HelloRESTful, '/')
if __name__ == '__main__': # 别忘了启动应用的代码 app.run(debug=True)

在终端或者命令行下运行 python app.py 启动应用

访问 localhost:5000 或者 127.0.0.1:5000 查看效果，将会看到 JSON 格式的数据输出:

{ "greet": "Hello Flask RESTful!"}

也可以用 curl 工具在终端或者命令行下发送请求:

curl http://localhost:5000 -s{ "greet": "Hello Flask RESTful!"}

curl 的参数 -s 是开启安静模式的意思

资源

从上面代码中可以看到，资源是 Resource 类的子类，以请求方法( GET、POST 等)名称的小写形式定义的方法，能对对应方法的请求作出相应，例如上面资源类中定义的 get 方法可以对 GET 请求作出相应，还可以定义 put、post、delete 等，称之为视图方法。

例如创建一个 todo 字样，支持获取代办事项和新增代办事项：

# 初始化待办列表todos = { 'todo_1': "读《程序员的自我修养》", 'todo_2': "买点吃的", 'todo_3': "去看星星"}class Todo(Resource): # 根据 todo_id 获取代办事项 def get(self, todo_id): return { todo_id: todos[todo_id] }
# 新增一个待办事项 def put(self, todo_id): todos[todo_id] = request.form['data'] return {todo_id: todos[todo_id]}

• 通过 GET 方式，提供 todo_id, 从 todos 列表中获取待办事项内容
• 通过 PUT 方式，提供 todo_id, 从请求体中获取到内容，作为待办事项内容
• 两种方法都返回 todo_id 所对应的待办事项内容

为 Todo 资源指定 URI:

api.add_resource(Todo, '/todo/<string:todo_id>/')

启动项目，用 curl 工具测试:

# 读取 key 为 todo_1 的待办事项 curl http://localhost:5000/todo/todo_1/{ "todo_1": "\u8bfb\u300a\u7a0b\u5e8f\u5458\u7684\u81ea\u6211\u4fee\u517b\u300b"}
# 创建一个 key 为 todo_4 的代办事项 curl http://localhost:5000/todo/todo_4/ -d "data=学习 Flask" -X PUT{ "todo_4": "\u5b66\u4e60 Flask"}

# 读取刚添加的待办事项 todo_4 curl http://localhost:5000/todo/todo_4/{ "todo_4": "\u5b66\u4e60 Flask"}

Flask-RESTful 支持多种视图方法的返回值:

class Todo1(Resource): def get(self): # 直接返回 return { 'task': 'Hello world'}
class Todo2(Resource): def get(self): # 返回内容及状态码 return {'task': 'Hello world'}, 201
class Todo3(Resource): def get(self): # 返回内容，状态码以及 Header return {'task': 'Hello world'}, 200, {'Etag': 'some-opaque-string'}

为三个资源指定 URI：

api.add_resource(Todo1, '/todo_1/')api.add_resource(Todo1, '/todo_2/')api.add_resource(Todo1, '/todo_3/')

启动项目后，用 curl 工具来测试:

curl http://localhost:5000/todo_1/{ "task": "Hello world"}
# -请求 todo_2 并显示出 HTTP 标头，HTTP 状态码为 201 curl http://localhost:5000/todo_2/ -iHTTP/1.0 201 CREATEDContent-Type: application/jsonContent-Length: 30Server: Werkzeug/0.16.0 Python/3.7.5rc1Date: Thu, 31 Oct 2019 14:12:54 GMT
{ "task": "Hello world"}
# -请求 todo_3 并显示出 HTTP 标头，HTTP 状态码为 200 ，标头中还有 Etag curl http://localhost:5000/todo_3/ -iHTTP/1.0 200 OKContent-Type: application/jsonContent-Length: 30Etag: some-opaque-stringServer: Werkzeug/0.16.0 Python/3.7.5rc1Date: Thu, 31 Oct 2019 14:14:57 GMT
{ "task": "Hello world"}


路由

从上面可以看到，通过 api.add_resource 方法来为资源设置路由

第一个参数是资源类，第二个参数是路由，和之前介绍的 @app.route 注解参数一样

可以为一个资源制定多个理由，例如:

api.add_resource(Todo, '/todo/', '/mytodo/')

http://localhost:5000/todo/ 和 http://localhost:5000/mytodo/ 都将指向 Todo

既然路由，就应该有 endpoint，通过命名参数 endpoint 指定:

api.add_resource(Todo, '/todo/', endpoint='todo_ep')

设置路由的 endpoint 为 todo_ep，如果不指定，endpoint 就是资源类名的小写形式

endpoint 是 Flask 中对具体路由的内部的具体定义，一般作为 url_for 方法的第一个参数，即通过 endpoint 获得该路由的 URL，在列出 RESTful 资源 URL 时非常有用。

请求解析

RESTful 服务器对请求数据有很强的依赖，就请求数据的获取及校验是很繁琐的事情，还好 Flask-RESTful 提供了非常好的请求解析工具 reqparse，不仅可以获取请求数据，还可以对数据进行校验并返回合适的错误消息。

from flask_restful import reqparse # 引入 reqparse 模块# ...
parser = reqparse.RequestParser() # 定义全局的解析实体# 定义参数 id，类型必须是整数parser.add_argument('id', type=int, help='必须提供参数 id')# 定义参数 name，且为必填parser.add_argument('name', required=True)# ...
class Reqparser(Resource): def get(self): args = parser.parse_args() # 获取解析器中定义的参数 并校验 return args
api.add_resource(Reqparser, '/reqparser/') # 指定路由

看下效果:

# 提供一个非整数参数 id curl http://localhost:5000/reqparser/ -d "id=noint" -X GET{ "message": { "id": "\u53c2\u6570 id \u5fc5\u987b\u662f\u6574\u6570" }}
# 不提供参数 namecurl http://localhost:5000/reqparser/{ "message": { "name": "Missing required parameter in the JSON body or the post body or the query string" }}

• 当参数校验失败，自动返回 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')

请求解析器支持继承，可以定义最高级别的解析器，逐渐细化，最后应用的具体资源上：

from flask_restful import reqparse
parser = reqparse.RequestParser()parser.add_argument('foo', type=int)
parser_copy = parser.copy() # 继承parser_copy.add_argument('bar', type=int) # parser_copy 将有两个参数
# 改变继承来的参数 foo 必填且的获取位置为 querystringparser_copy.replace_argument('foo', required=True, location='args')
# 删除继承来的参数 fooparser_copy.remove_argument('foo')

格式化输出

请求解析处理用收到的信息，对于输入的信息也可以处理，通过 Flask-RESTful 提供的类 fields 和注解 marshal_with 来实现：

from flask_restful import Resource, fields, marshal_with
resource_fields = { 'name': fields.String, 'address': fields.String, 'date_updated': fields.DateTime(dt_format='rfc822'),}
class TodoFormat(Resource): @marshal_with(resource_fields, envelope='resource') def get(self): return db_get_todo() # 某个获得待办事项的方法

• 定义一个字段格式化模板，属性用 fields 的类型方法定义
• 在响应方法上加上 marshal_with 注解，指定格式化模板，和封装属性名

格式化模板属性名，需要在响应函数返回的对象属性中匹配，如果需要会要对字段重命名，可以这样:

fields = { # name 将被重命名为 private_name 'name': fields.String(attribute='private_name'), 'address': fields.String}

返回值中没有可以定义默认值:

fields = { # 为 name 设置默认值 'name': fields.String(default='Anonymous User'), 'address': fields.String}

总结

本节课程简单介绍了 Flask 如何玩 RESTful，通过对 RESTful 的说明，讲解了 Flask-RESTful 模块的用法，并简单讲解了资源、路由，以及请求解析和格式化输出等技术

示例代码：Python-100-days-day047

参考

• http://www./blog/2014/05/restful_api.html
• http://www./blog/2011/09/restful.html
• https://flask-restful./en/latest/
• http://www./blog/2019/09/curl-reference.html

系列文章

    第46天：Flask数据持久化

    第45天：Web表单

    第44天：Flask 框架集成Bootstrap

    第43天：Python filecmp&difflib模块

    第42天：Python paramiko 模块

    第41天：Python operator 模块

    第0-40天：从0学习Python 0-40合集