Flask RESTful API 开发----基础篇 (1)

本文首发于Gevin的博客
原文连接：Flask RESTful API 开发----基础篇 (1)
未经 Gevin 受权，禁止转载

From zoomy

0. 前言

接下来一段时间，Gevin将开一个系列专题，讲Flask RESTful API的开发，本文是第1篇《Flask RESTful 基础》，本系列文章列表以下：

• 基础篇(1) --- Flask RESTful 基础 (掘金连接)
• 基础篇(2) --- 一个简单的Flask RESTful 实例 (掘金连接)
• To Be Continued...

1. RESTful 简介

我在博文《RESTful 架构风格概述》和《RESTful API 编写指南》中曾详细论述过我对RESTful的理解，以及规范的RESTful API开发须要涉及的内容，本节摘录几条重点内容，为下文作铺垫:

1. RESTful 是面向资源的，每一个资源至少有一个url与之对应
2. 统一数据交互接口，即经过http的GET, POST, PUT(or PATCH), 和 DELETE 进行资源的获取、建立、更新和删除
3. 资源（数据）以文本形式在网络上传输，一般以json或xml格式为载体
4. 无状态（之后讲认证时再展开论述）

2. Flask 对RESTful 架构风格的支持

Flask RESTful 开发相关的库不少，我也收集过一些（collection在此，不按期更新），其实，与Django不一样，Flask原生对RESTful的支持已经作的很好，不借助这些extension，同样能够开发出足够好的RESTful API，并且没有这些extension的束缚，咱们能够在开发过程当中，配合使用Flask生态中处理相应问题最好的extension，或者咱们本身最上手的extension，这也更加符合Flask的philosophy。Gevin在Flask RESTful 开发中，不使用各种flask rest扩展的主要缘由，正是每一个扩展都有不尽如意之处。

那么，咱们就来看一下Flask原生是如何支持RESTful开发的。

(注：Django RESTful开发主要基于Django REST Framework，Django的DRF理念对我一直很受用，我在Flask开发和Flask RESTful API开发中，借鉴了不少Django的设计理念。所以，对于如何作好Flask开发，Gevin有个观点是：不妨从Django的开发作起~ :P)

2.1 Flask对HTTP方法的支持

Flask原生支持全部的HTTP方法，如RESTful API中最经常使用的GET, POST, PUT, PATCH和DELETE，这些不需赘述解释，直接上代码便可：

@app.route('/http-method-test/', methods=['GET', 'POST', 'PUT', 'PATCH', 'DELETE'])
def http_method_example():
    if request.method == 'GET':
        return 'Send request with `GET` method'
    elif request.method == 'POST':
        return 'Send request with `POST` method'
    elif request.method == 'PUT':
        return 'Send request with `PUT` method'
    elif request.method == 'PATCH':
        return 'Send request with `PATCH` method'
    elif request.method == 'DELETE':
        return 'Send request with `DELETE` method'复制代码

另一种方式是采用Flask的MethodView:

class HttpMethodExample(MethodView):
    def get(self):
        return 'Send request with `GET` method'

    def post(self):
        return 'Send request with `POST` method'

    def put(self):
        return 'Send request with `PUT` method'

    def patch(self):
        return 'Send request with `PATCH` method'

    def delete(self):
        return 'Send request with `DELETE` method'

app.add_url_rule('/http-method-test2/', view_func=HttpMethodExample.as_view('http_method_example2'))复制代码

2.2 Flask 对序列化与反序列化的支持

RESTful 开发时，数据的载体一般为json或xml格式的文本，随着RESTful的不断发展，json更是成为了RESTful API 数据的主流载体。而Flask自己，已经对json的支持已经很是好了。

2.2.1 序列化

RESTful API开发中的序列化，经过包含了如下操做：

1. 将Python native格式的数据（如dict和list）转换为文本数据（如json或xml）
2. 将文本数据做为请求的response返回给客户端，response的http header里要同时附加application/json这个mimetype

这两步操做，Flask提供的一个快捷函数jsonify()能直接完成，其详情正以下面的Flask官方文档所述：

This function wraps dumps() to add a few enhancements that make life easier. It turns the JSON output into a Response object with the application/json mimetype. For convenience, it also converts multiple arguments into an array or multiple keyword arguments into a dict. This means that both jsonify(1,2,3) and jsonify([1,2,3]) serialize to [1,2,3].

很简单的事情，不应说这么多，直接上代码示例吧：

class SerializationExample(MethodView):
    def get(self):
        option = request.args.get('option')

        if option == 'list1':
            return self.test_list()
        if option == 'list2':
            return self.test_list2()
        if option == 'dict1':
            return self.test_dict1()
        if option == 'dict2':
            return self.test_dict2()
        if option == 'dict3':
            return self.test_dict3()


        msg = {
            'info': '`option` is needed in url as a url parameter',
            'avilable option values': 'list1, list2, test_dict1, test_dict2, test_dict2'
        }
        return jsonify(msg)



    def test_list(self):
        data = [{'a':1, 'b':2}, {'c':3, 'd':4}]
        return jsonify(result=data)

    def test_list2(self):
        data = [1,2,3,4,5,6,7,8]
        return jsonify(data)


    def test_dict1(self):
        data = {'a':1, 'b':2, 'c':3}
        return jsonify(data)

    def test_dict2(self):
        data = {'a':1, 'b':2, 'c':3}
        return jsonify(**data)

    def test_dict3(self):
        data = {'a':1, 'b':2, 'c':3}
        return jsonify(result=data)

app.add_url_rule('/serialization/', view_func=SerializationExample.as_view('serialization'))复制代码

上面代码的重点即，那几个以test_开头的函数，序列化的表现形式无外乎这几种。

2.2.2 反序列化

反序列化，即把文本形式的数据转换为Python native类型数据的过程。在RESTful API开发时，Flask内置的get_json()方法，可以把request中的json数据，转换为Python标准库中的dict或list。

Parses the incoming JSON request data and returns it. By default this function will return None if the mimetype is not application/json, but this can be overridden by the force parameter.

If parsing fails the on_json_loading_failed() method on the request object will be invoked.

示例代码：

@app.route('/deserialization/', methods=['get', 'post'])
def deserialization():
    if request.method == 'POST':
        data = request.get_json()
        if not data:
            return 'No json data found', 400

        result = {
            'json data in request': data
        }
        return jsonify(result)

    return 'Please post json data'复制代码

注：

Flask原生的序列化和反序列化方法，都是针对目前RESTful API 开发时最流行的json格式的，且只能作json与dict或list的相互转换，若是想序列化或反序列化对象实例，须要借助其余方法，这个会在之后的文章中作进一步解释。

3. What's More

• 我在GitHub上的项目restapi_example，存放了本系列内容的完整源码，你们能够随意查阅。

• 本章涉及的代码，完整示例请查看上面项目的chapter1分支

• RESTful API 开发时，测试API可用工具Postman

• 下一讲预告：Gevin将结合一个具体的应用实例，介绍RESTful API的设计与实现