【Flask-RESTPlus系列】Part3：请求解析
0x00 内容概览
请求解析
基本参数
必需参数
多值和列表
其他目标
参数位置
参数多个位置
高级类型处理
解析器继承
文件上传
错误处理
错误消息
参考链接
0x01 请求解析
注意：Flask-RESTPlus的整个请求解析器部分将被移除，并将替换成关于集成其他更善于处理输入、输出的包（例如marshmallow）的说明文档。但是考虑到已经被废弃，它将一直维护到2.0版本。如果你现在有代码使用它，并希望继续这样做，那么也无需担心，因为它不会很快消失。
Flask-RESTPlus的请求解析接口reqparse是模仿argparse接口实现的。它的设计目的是对Flask中flask.request对象上的任何变量提供简单和统一的访问方式。
1、基本参数
下面是一个请求解析器的简单示例。它在flask.Request.values字典中查找两个参数：一个整数和一个字符串：
from flask_restplus import reqparse
parser = 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 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'参数
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 FileStorage
upload_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}, 20110、错误处理
RequestParser处理错误的默认方式是在第一个错误产生时中断。当我们拥有需要花费一定时间来处理的参数时，这种方式是有好处的。然而，通常来说，将所有产生的错误都绑定在一起，然后同时一次性返回给客户端，这种方式则更加友好。这种方式既可以在Flask应用级别指定，也可以在特定的RequestParser实例级别指定。为了调用一个包含错误绑定选项的RequestParser，需要传入参数bundle_errors。例如：
from flask_restplus import reqparse
parser = 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 Flask app = 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 reqparse
parser = 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",
}
}