Flask-RESTful 请求解释

参考资料：https://flask-restful.readthedocs.io/en/latest/reqparse.html

---

Flask-RESTful 的请求解释模块 reqparse 作用于 Flask 中 flask.request 对象。

from flask_restful import reqparse

parser = reqparse.RequestParser()
parser.add_argument('rate', type=int, help='Rate cannot be converted')
parser.add_argument('name')
args = parser.parse_args()

看一个完整例子：

from flask import Flask, request, render_template
from flask_restful import Resource, Api, reqparse

class Todo(Resource):
    def __init__(self):
        self.parser = reqparse.RequestParser()
        self.parser.add_argument(
            'name', 
            type=str, 
            required=True, 
            help='parameter name is required'
        )

    def get(self):
        args = self.parser.parse_args() 
        return args

    def post(self):
        args = self.parser.parse_args()
        return args
api.add_resource(Todo, '/')

用 add_argument() 方法添加需解释的参数名，然后用 parse_args() 方法解释成 Python 的字典。

如果你指定了 help 参数的值，在解析的时候当类型错误被触发的时候，它将会被作为错误信息给呈现出来。如果你没有指定 help 信息的话，默认行为是返回类型错误本身的信息。

现在我们用 GET 方法请求 http://127.0.0.1:5000/?name=tom：

{ "name": "tom"}

如果请求参数错误，比如 http://127.0.0.1:5000/?age=18：

{
    "message": {
        "name": "parameter name is required"
    }
}

---

必需的参数

要传递一个值的参数，只需要添加 required=True 来调用 add_argument()。

parser.add_argument('name', type=str, required=True,
help="Name cannot be blank!")

---

多个值&列表

如果你要传递一个键包含多个值，你可以设置 action='append'：

parser.add_argument('name', action='append')

如果你传递是参数是：

{'name': ['tom', 'paul', john]}

解析出来的参数就是：

args = parser.parse_args()
args['name']    # ['tom', 'paul', john]

---

参数别名

如果你希望为传递来的参数设置别的变量名，可以设置 dest ：

parser.add_argument('name', type=str, dest='public_name')

args = parser.parse_args()
args['public_name']

现在可以用 public_name 来读取 name 变量。

---

参数的解释位置

默认情况下，reqparse 会从 flask.Request.values 和 flask.Request.json 中解析值。

如果想从其他位置（比如：form、args、headers、cookies、files）解释参数，可使用 add_argument() 的 location 参数来指定要从哪些位置拉取值。flask.Request 上的任何变量都可以使用。

# Look only in the POST body
parser.add_argument('name', type=int, location='form')

# Look only in the querystring
parser.add_argument('PageSize', type=int, location='args')

# From the request headers
parser.add_argument('User-Agent', location='headers')

# From http cookies
parser.add_argument('session_id', location='cookies')

# From file uploads
parser.add_argument('picture', type=werkzeug.datastructures.FileStorage, location='files')

要设置多个解释位置，可以这样：

parser.add_argument('text', location=['headers', 'values'])

---

解析器继承

通常情况下，你会为你写的每个 RequestParser 写一个不同的解析器。如果多个 Resource 有部分相同的参数名，那么我们可以先编写包含相同参数名的解析器，然后通过 copy() 方法复制后再扩充解释器。

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、bar 两个参数了。

replace_argument() 方法可以覆盖解释器中原有的参数：

parser_copy.replace_argument('foo', required=True, location='json')

remove_argument() 方法可以删除解释器中指定的参数：

parser_copy.remove_argument('foo')

---

错误处理

RequestParser 默认的错误处理方式是在发生第一个错误时中止，所以也只会返回第一个错误的信息，通常我们会希望是把所有错误都处理完然后把错误信息捆绑到一起再返回，这时我们需要用到 bundle_errors 关键字：

class Todo(Resource):
    def __init__(self):
        self.parser = reqparse.RequestParser(bundle_errors=True)
        self.parser.add_argument(
            'name', 
            type=str, 
            required=True, 
            help='parameter name is required'
        )
        self.parser.add_argument(
            'age', 
            type=int, 
            required=True,
            help='parameter age is required'
            )

    def get(self):
        args = self.parser.parse_args() 
        return args

    def post(self):
        args = self.parser.parse_args()
        return args
api.add_resource(Todo, '/')

当上诉 API 的两个参数都有错误的时候，得到这样的错误信息：

{
    "message": {
        "age": "parameter age is required",
        "name": "parameter name is required"
    }
}