教程
avatar of this article's author EarlGrey
Flask 编译
如何自定义Flask中的响应类

有翻译或理解不对的地方,望大家指正!

Flask框架中的响应类,命名很贴切,叫Response。不过Flask应用中很少直接调用这个类。而是将其作为路由函数所返回响应数据的内部容器,容器里还包含了用于创建HTTP响应的其他信息。

但是没多少人知道,Flask框架其实允许应用将默认的响应类,替换为自定义类。这就给了我们研究小窍门的机会。在本文中,我将展示如何利用Flask的这个特性,简化你的代码。

Flask中的响应类是如何工作的?

大部分应用并不直接使用Flask中的响应类(Response class),但这并不是说这个类没有用武之地;实际上,Flask会为每个请求创建响应对象。那么,它是如何实现的呢?

Flask用来处理请求的函数返回时,响应周期就开始了。在网络应用中,路由通常最后会调用render_template函数,渲染引用的模板文件,将其作为字符串返回:

@app.route('/index')
def index():
    # ...
    return render_template('index.html')

但是,你可能也知道,Flask的路由函数可以选择额外返回两个值,这两个值将被分别设为HTTP状态码和自定义的HTTP响应标头:

@app.route('/data')
def index():
    # ...
    return render_template('data.json'), 201, {'Content-Type': 'application/json'}

在上面的例子中,状态码被设为201,取代了Flask默认的200,即请求被成功处理的状态码。这个例子还定义了内容类型标头(Content-Type header),表明HTTP响应中包含JSON数据,因为如果你不明确设置内容类型的话,Flask会默认设置为HTML。

上面的例子介绍了HTTP响应的三个基本组成部分,即数据或正文、状态码和标头。Flask的应用实例拥有一个make_response函数,可以接受路由函数的返回值(可以是单个值,也可以是有1-3个值的元组),并将其填入响应对象(Response object)中。

你可以通过Python控制台会话(console session),看看整个过程。首先创建一个虚拟环境,并安装Flask,然后开启Python会话,并输入下面的代码:

>>> from flask import Flask
>>> app = Flask(__name__)
>>> app.make_response('Hello, World')
<Response 12 bytes [200 OK]>
>>> app.make_response(('Hello, World', 201))
<Response 12 bytes [201 CREATED]>

这里,我创建了一个简单的Flask应用实例,之后调用了make_response()方法创建响应类对象。第一次调用时,我传了一个字符串作为参数,所以响应对象中使用了默认的状态码和标头。第二次调用时,我传入了有两个值的元组,强制返回了非默认的状态码。注意,第二次调用时使用了两个括号,里层的括号将字符串和状态码包在了元组中。由于make_response()函数只接受一个参数,所以必须要这样做。

Flask在创建了代表路由函数返回值的响应对象(Response object)之后,还会做一些处理。包括将响应对象传入自定义的after_request处理程序(handlers),在这一步,应用还有有机会插入或修改标头、更改正文或状态码,如果愿意的话,甚至是启用崭新的的响应对象取而代之。最后,Flask会获取最终的响应对象,渲染成HTTP响应,并发送给客户端。

Flask中的响应类

我们来看看响应类中最有趣的特性。下面的类定义,展示了我眼中这个类所具备的灵活属性和方法:

class Response:
    charset = 'utf-8'
    default_status = 200
    default_mimetype = 'text/html'

    def __init__(self, response=None, status=None, headers=None,
                 mimetype=None, content_type=None, direct_passthrough=False):
        pass

    @classmethod
    def force_type(cls, response, environ=None):
        pass

注意,如果你去翻阅Flask的源码,是找不到上述类定义的。Flask中的Response类,实际上衍生自Werkzeug库中的一个同名类。而Werzeug中的Response类继承的是BaseResponse类,这个类中就包含了上述定义。

charsetdefault_statusdefault_mimetype这三个类属性定义了相应的默认值。如果任何一个默认值不适用你的应用,那么你可以创建Response类的子类,定义你自己的默认值,而不必在每一个响应对象中设置自定义值。例如,如果你的应用是一个所有的路由均返回XML格式数据的API接口,你就可以在自定义的类中,将default_mimetype改为application/xml,这样Flask就会默认返回XML响应。稍后你会看到如何实现。

这里,我不会详细介绍__init__构造函数(你可以阅读Werkzeug的文档),但请注意,Flask响应对象中的三个重要元素,即响应正文、状态码和标头,是作为参数传入的。在子类中,构造函数可以改变创建响应的相应规则。

响应类中的force_type()类方法,是唯一比较复杂,但又很重要的元素。有时候,Werkzeug或是Flask需要自行创建响应对象,比如出现应用错误,并需要将其返回给客户端时。在这种情况下,响应对象不是应用提供的,而是由框架创建的。在使用自定义响应类的应用中,Flask和Werkzeug无法知道自定义类的细节,所以它们使用标准响应类来创建响应。响应类中的force_type()方法,被设计为可以接受不同响应类的实例,并会将其转换成自身的格式。

我敢肯定,你一定被force_type()方法的描述搞糊涂了。说白了,就是如果Flask碰到了一个不是其期望的响应对象,就会使用该方法进行转换。我下面要讲的第三个使用场景,就利用了这个特点,让Flask的路由函数返回诸如字典、列表或者是其他任何自定义对象,作为请求的响应对象。

好了,理论就讲这么多了。接下来,我来告诉大家如何应用上面有关响应类的小技巧。准备好了吗?

使用自定义的响应类

到现在为止,我确定你也会认为:在部分有趣的场景下,使用自定义的响应类是有利的。在给出实际例子之前,我想告诉你在Flask中设置并使用自定义的响应类是多么的简单。请看下面的这个例子:

from flask import Flask, Response

class MyResponse(Response):
    pass

app = Flask(__name__)
app.response_class = MyResponse

# ...

在上面的代码中,我定义了一个名叫MyResponse的自定义响应类。通常,自定义响应类会增加或修改默认类的行为,所以一般都会通过创建Flask中Response类的子类来实现。要想让Flask使用自定义类,我只需要设置app.response_class即可。

Flask类中的response_class是一个类属性,所以我们可以稍微修改上面的例子,创建一个设置了自定义响应类的Flask子类:

from flask import Flask, Response

class MyResponse(Response):
    pass

class MyFlask(Flask)
    response_class = MyResponse

app = MyFlask(__name__)

# ...

例1:更改响应对象的默认值

第一个例子极其简单。假设你的应用中大部分或全部端点(endpoints)都返回的是XML。对于这样的应用,将默认的内容类型设置为application/xml是合理的。可以通过下面这个仅有两行代码的响应类轻松实现:

class MyResponse(Response):
    default_mimetype = 'application/xml'

容易,对吧?如果将其设为应用的默认响应类,那么你在编写返回XML的函数时,就不用担心忘记设置内容类型了。举个例子:

@app.route('/data')
def get_data():
    return '''<?xml version="1.0" encoding="UTF-8"?>
<person>
    <name>John Smith</name>
</person>
'''

上面这个路由使用的是默认响应类,其内容类型会被设置为text/html,因为那是默认类型。使用自定义响应类,可以免去你在所有XML路由的返回语句中,额外加上标头的麻烦。另外,如果有的路由需要其他的内容类型,你仍可以替换掉默认值,就像对待一般的响应类一样。

@app.route('/')
def index():
    return '<h1>Hello, World!</h1>', {'Content-Type': 'text/html'}

例2:自动决定内容类型

下一个例子更复杂一点。假设我们的应用中HTML路由与XML路由的数量差不多,所以按照第一个例子的做法就不行了,因为不管你选用哪种默认类型,都会有一半的路由需要替换内容类型。

更好的解决办法,则是创建一个能够通过分析响应文本,决定正确的内容类型的响应类。下面的这个类实现了该功能:

class MyResponse(Response):
    def __init__(self, response, **kwargs):
        if 'mimetype' not in kwargs and 'contenttype' not in kwargs:
            if response.startswith('<?xml'):
                kwargs['mimetype'] = 'application/xml'
        return super(MyResponse, self).__init__(response, **kwargs)

在这个简单的例子中,我首先确保响应对象中没有明确设置内容类型。然后,我检查响应的正文是否以<?xml开头,是的话就意味着数据是XML文档格式。如果两个条件同时成立,我会在传入父类构造函数的参数中,插入XML内容类型。

有了这个自定义响应类,任何满足XML格式要求的文档都会自动被标记为XML内容类型,而其他响应则会继续获得默认的内容类型。而且,在所有的类中,我仍然可以在必要时声明内容类型。

例3:自动返回JSON响应

最后一个例子,针对的是利用Flask创建API接口时常见的一个小问题。API接口通常返回的是JSON净负荷(JSON Payload,这就要求你使用jsonify()函数将Python字典类型转换成JSON数据,并且还得在响应对象中将内容类型设置为JSON内容类型。请看下面这个例子:

@app.route('/data')
def get_data():
    return jsonify({'foo': 'bar'})

问题是,每个返回JSON的路由都需要这样处理,那么对接口数量众多的的API来说,你就得大量重复调用jsonify()函数。从代码可读性角度来讲,你按照下面的方式处理是不是更好?

@app.route('/data')
def get_data():
    return {'foo': 'bar'}

下面是一个支持使用上述语法的自定义响应类,它不会影响应用中使用其他内容类型的路由正常工作:

class MyResponse(Response):
    @classmethod
    def force_type(cls, rv, environ=None):
        if isinstance(rv, dict):
            rv = jsonify(rv)
        return super(MyResponse, cls).force_type(rv, environ)

这个例子需要稍微解释一下,因为比较复杂。Flask仅认可一小部分的类型,作为路由函数能够返回的有效响应类型。基本上,你可以返回任意与字符串和二进制相关的类型(strunicodebytesbytearray)。如果你喜欢,甚至可以返回一个已经创建好的响应对象。如果你返回的是字符串或二进制类型,Flask会发现这些是响应类知道如何处理的类型,并会将你返回的数据直接传入响应类的构造函数。

但是,如果你返回的是不支持的类型,比如说上述例子中的字典,会发生什么情况?如果返回的响应类型不是Flask预期的,那么Flask就会默认它是未知响应对象,不会以其为参数创建响应对象了,而是使用响应类的force_type()类方法,强制转换未知类型。上面的例子中,响应子类替换了该方法,但仅仅是通过调用jsonify()进行转换,之后就会让基类接手处理,就好像什么都没发生一样。

是个很好的窍门吧?尤其是这样做不会影响其他响应的正常工作。对于返回正常响应类型的路由,该子类不会做任何处理,所有的调用请求会全部传入父类中。

结语

我希望本文能够帮助大家更好地理解FLask中响应对象的工作原理。如果你知道其他使用Flask响应类的小窍门,请务必与我分享!

上一篇
下一篇