【Flask-RESTPlus系列】Part3：请求解析

0x00 内容概览

请求解析
1. 基本参数
2. 必需参数
3. 多值和列表
4. 其他目标
5. 参数位置
6. 参数多个位置
7. 高级类型处理
8. 解析器继承
9. 文件上传
10. 错误处理
11. 错误消息
参考链接

0x01 请求解析

注意：Flask-RESTPlus的整个请求解析器部分将被移除，并将替换成关于集成其他更善于处理输入、输出的包（例如marshmallow）的说明文档。但是考虑到已经被废弃，它将一直维护到2.0版本。如果你现在有代码使用它，并希望继续这样做，那么也无需担心，因为它不会很快消失。

Flask-RESTPlus的请求解析接口reqparse是模仿argparse接口实现的。它的设计目的是对Flask中flask.request对象上的任何变量提供简单和统一的访问方式。

1、基本参数

下面是一个请求解析器的简单示例。它在flask.Request.values字典中查找两个参数：一个整数和一个字符串：

from flask_restplus import reqparseparser = reqparse.RequestParser()
parser.add_argument('rate', type=int, help='Rate cannot be converted')
parser.add_argument('name') # Python3中默认类型为字符串
args = parser.parse_args()

注意：默认参数类型是unicode字符串。在Python3中为str类型，而在Python2中为unicode。

如果指定了help变量的值，那么在解析请求时，如果出现了类型错误，那么会将它渲染为错误信息。如果未指定help信息，那么默认的行为是返回类型错误信息本身。可以查看“11、错误信息”部分以了解更多细节。

注意：默认情况下，参数不是必需的。并且，如果请求中提供的某些参数不是RequestParser的部分内容，那么这些参数将会被忽略。

注意：请求解析器中声明的参数，如果在请求中并未设置这些参数值，那么它们将会默认设置为None。

2、必需参数

如果需要确保某个参数必须提供，那么可以在调用add_argument()时传入required=True的参数项：

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

此时，如果请求中未提供该参数，那么将会返回错误信息。

3、多值和列表

如果想为某个key接受多个值以构成列表，那么可以传入action=’append’：

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

此时的查询格式如下所示：

curl http://api.example.com -d "name=bob" -d "name=sue" -d "name=joe"

而程序中获取到的参数如下所示：

args = parser.parse_args()
args['name']    # ['bob', 'sue', 'joe']

如果期望一个逗号分隔的列表，那么可以使用action=’split’：

parser.add_argument('fruits', action='split')

此时的查询格式如下所示：

curl http://api.example.com -d "fruits=apple,lemon,cherry"

而程序中获取到的参数如下所示：

args = parser.parse_args()
args['fruits']    # ['apple', 'lemon', 'cherry']

4、其他目标

如果期望参数一旦被解析，就将其存储为其他名字，那么可以使用dest参数：

parser.add_argument('name', dest='public_name')args = parser.parse_args()
args['public_name']

5、参数位置

默认情况下，RequestParser尝试从flask.Request.values和flask.Request.json中解析值。

在add_argument()中使用location参数来指定获取值的其他位置。可以使用flask.Request上的任何变量，例如：

# 仅仅在POST body中查找
parser.add_argument('name', type=int, location='form')# 仅仅在querystring中查找
parser.add_argument('PageSize', type=int, location='args')# 从请求头中查找
parser.add_argument('User-Agent', location='headers')# 从http cookies中查找
parser.add_argument('session_id', location='cookies')# 从上传文件中查找
parser.add_argument('picture', type=werkzeug.datastructures.FileStorage, location='files')

注意：当location=’json’时只能使用type=list，点击此处查看更多。

注意：使用location=’form’既能验证表单数据，又能为表单字段文档化。

6、参数多位置

为location参数赋一个列表就能为参数指定多个位置：

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

当指定多个参数位置时，那么所有指定位置的参数将会组成一个MultiDict。其中，列表中最后位置处的参数将会优先存储在结果集中。

如果参数位置列表中包含headers位置，那么参数名将变成对大小写敏感，并且必须匹配它们的标题大小写名称（见str.title()）。

指定location=’headers’（而不是作为列表的某个元素）将保留大小写不敏感的特性。

7、高级类型处理

有时，我们需要其他原始类型来处理输入验证问题。为此，inputs模块中提供了一些常用的类型处理方法，如下：

boolean()用于广泛的布尔值处理
ipv4()和ipv6()用于IP地址
date_from_iso8601()和datetime_from_iso8601()用于ISO8601 date和datetime处理

只需要使用它们作为type参数的值即可：

parser.add_argument('flag', type=inputs.boolean)

查看inputs文档以了解所有可用的输入类型。

另外，我们也可以编写自己的输入类型：

def my_type(value):
    '''解析类型'''
    if not condition:
        raise ValueError('This is not my type')
    return parse(value)# Swagger文档化
my_type.__schema__ = {'type': 'string', 'format': 'my-custom-format'}

8、解析器继承

很多情况下，我们都需要为不同的资源指定不同的解析器。不过，如果这些不同的解析器之间存在大量相同的字段的话，将会存在大量重复编码的问题。为此，我们可以编写一个父解析器，父解析器中包含所有共同的参数，然后利用copy()方法来扩展解析器。另外，也可以利用replace_argument()来覆写父解析器中的任何参数，或者利用remove_argument()完全移除父解析器中的某个参数。例如：

from flask_restplus import reqparseparser = reqparse.RequestParser()
parser.add_argument('foo', type=int)parser_copy = parser.copy()
parser_copy.add_argument('bar', type=int)
# 此时，parser_copy中同时包含'foo'和'bar'参数parser_copy.replace_argument('foo', required=True, location='json')
# 此时，'foo'参数变成了一个必需的str类型的参数，并且查找位置为json；而不再是父解析器中定义的int类型的可选参数parser_copy.remove_argument('foo')
# 此时，parser_copy中不再包含'foo'参数

9、文件上传

为了利用RequestParser处理文件上传问题，我们需要将location变量值设置为files，并设置type值为FileStorage。如下所示：

from werkzeug.datastructures import FileStorageupload_parser = api.parser()
upload_parser.add_argument('file', location='files',
                           type=FileStorage, required=True)@api.route('/upload/')
@api.expect(upload_parser)
class Upload(Resource):
    def post(self):
        uploaded_file = args['file']  # 这是FileStorage实例
        url = do_something_with_file(uploaded_file)
        return {'url': url}, 201

10、错误处理

RequestParser处理错误的默认方式是在第一个错误产生时中断。当我们拥有需要花费一定时间来处理的参数时，这种方式是有好处的。然而，通常来说，将所有产生的错误都绑定在一起，然后同时一次性返回给客户端，这种方式则更加友好。这种方式既可以在Flask应用级别指定，也可以在特定的RequestParser实例级别指定。为了调用一个包含错误绑定选项的RequestParser，需要传入参数bundle_errors。例如：

from flask_restplus import reqparseparser = reqparse.RequestParser(bundle_errors=True)
parser.add_argument('foo', type=int, required=True)
parser.add_argument('bar', type=int, required=True)# 如果某个请求中同时不包含'foo'和'bar'，那么返回的错误将看起来如下所示：{
    "message":  {
        "foo": "foo error message",
        "bar": "bar error message"
    }
}# 默认操作将仅仅返回第一个错误
parser = RequestParser()
parser.add_argument('foo', type=int, required=True)
parser.add_argument('bar', type=int, required=True){
    "message":  {
        "foo": "foo error message"
    }
}

应用级别的配置key为“BUNDLE_ERRORS”。例如：

from flask import Flaskapp = Flask(__name__)
app.config['BUNDLE_ERRORS'] = True

警告：BUNDLE_ERRORS是一个全局设置，它将覆盖每个RequestParser实例中的bundle_errors选项值。

11、错误消息

每个字段的错误消息都可以通过在Argument（也包括RequestParser.add_argument）中使用help参数来自定义。

如果没有提供help参数，那么该字段的错误消息将会是类型错误本身的字符串表示。如果提供了help参数，那么错误消息将会是help参数的值。

help可能包含一个插入的符号{error_msg}，它将会替换成类型错误的字符串表示。这种方式能够实现自定义错误消息，同时保留原始的错误消息。如下所示：

from flask_restplus import reqparseparser = reqparse.RequestParser()
parser.add_argument(
    'foo',
    choices=('one', 'two'),
    help='Bad choice: {error_msg}'
)# 如果请求中的'foo'参数值为'three'，那么错误信息将会如下所示：
{
    "message":  {
        "foo": "Bad choice: three is not a valid choice",
    }
}

0x02 参考链接

http://flask-restplus.readthedocs.io/en/stable/parsing.html