摘要：勵以最少的安裝方式進(jìn)行最佳實(shí)踐。上面的例子接收了一個對象并準(zhǔn)備將其序列化。裝飾器會通過進(jìn)行轉(zhuǎn)換。從對象中提取的唯一字段是。是一個特殊的字段，它接受端點(diǎn)名稱并為響應(yīng)中的端點(diǎn)生成一個?？梢圆榭错?xiàng)查看完整列表。

簡介

安裝

快速入門

一個最小的 api 例子

資源豐富的路由

端點(diǎn)

參數(shù)解析

數(shù)據(jù)格式化

完整 TODO 應(yīng)用例子

Flask-RESTful是一個Flask的擴(kuò)展，它增加了對快速構(gòu)建REST APIs的支持。它是一種輕量級的抽象，可以與現(xiàn)有的ORM/庫一起工作。Flask-RESTful勵以最少的安裝方式進(jìn)行最佳實(shí)踐。如果你對Flask很熟悉的，F(xiàn)lask-RESTful會很容易上手。

本文環(huán)境：python3

pip3 install flask-restful

下面來編寫一個最小的Flask-RESTful API:

from flask import Flask
from flask_restful import Resource, Api

app = Flask(__name__)
api = Api(app)

class HelloWorld(Resource):
    def get(self):
        return {"hello": "world"}

api.add_resource(HelloWorld, "/")

if __name__ == "__main__":
    app.run(debug=True) 

保存代碼到api.py測試時打開debug模式會提供代碼重載，以及更詳細(xì)的錯誤信息。注意調(diào)試模式不可用在生產(chǎn)環(huán)境。接下來打開命令窗口輸入命令執(zhí)行py 文件

$ python api.py
 * Running on http://127.0.0.1:5000/
 * Restarting with reloader

新建一個命令窗口，使用curl測試下API

$ curl http://127.0.0.1:5000/
{"hello": "world"}

Flask-RESTful 提供的最主要的基礎(chǔ)就是資源，資源是構(gòu)建在Flask 可插拔的視圖之上，只要在你的資源上定義方法就能很容易的訪問多個 HTTP 方法，一個待辦事項(xiàng)應(yīng)用的基礎(chǔ) CRUD資源的編寫像這樣：

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

app = Flask(__name__)
api = Api(app)

todos = {}

class TodoSimple(Resource):
    def get(self, todo_id):
        # 從 todos 字典中讀取數(shù)據(jù) 注:此處沒有對不存在的 key 做處理
        return {todo_id: todos[todo_id]}

    def put(self, todo_id):
        # 將數(shù)據(jù)保存到 todos 字典中
        todos[todo_id] = request.form["data"]
        return {todo_id: todos[todo_id]}

# 增加資源到 api, 匹配字符串到資源方法的變量
api.add_resource(TodoSimple, "/")

if __name__ == "__main__":
    app.run(debug=True)

保存到文件后執(zhí)行，使用 curl測試一下

$ curl http://localhost:5000/todo1 -d "data=Remember the milk" -X PUT
{"todo1": "Remember the milk"}

$ curl http://localhost:5000/todo1
{"todo1": "Remember the milk"}

$ curl http://localhost:5000/todo2 -d "data=Change my brakepads" -X PUT
{"todo2": "Change my brakepads"}

$ curl http://localhost:5000/todo2
{"todo2": "Change my brakepads"}

如果有安裝 python 的 requests 庫也可以用以下方法測試 （Python庫系列之requests）：

>>> from requests import put, get
>>> put("http://localhost:5000/todo1", data={"data": "Remember the milk"}).json()
{"todo1": "Remember the milk"}
>>> get("http://localhost:5000/todo1").json()
{u"todo1": u"Remember the milk"}
>>> put("http://localhost:5000/todo2", data={"data": "Change my brakepads"}).json()
{u"todo2": u"Change my brakepads"}
>>> get("http://localhost:5000/todo2").json()
{u"todo2": u"Change my brakepads"}

Flask-RESTful支持視圖方法多種類型的返回值，像 Flask 一樣，你可以返回任何迭代器，它會被轉(zhuǎn)化成一個包含原始響應(yīng)對象的響應(yīng)，F(xiàn)lask-RESTful還支持使用多個返回時來設(shè)置響應(yīng)碼以及響應(yīng)頭，如下：

class Todo1(Resource):
    def get(self):
        # 默認(rèn)返回200
        return {"task": "Hello world"}

class Todo2(Resource):
    def get(self):
        # 將響應(yīng)碼設(shè)為201
        return {"task": "Hello world"}, 201

class Todo3(Resource):
    def get(self):
        # 將響應(yīng)碼設(shè)置為201,并返回自定義頭
        return {"task": "Hello world"}, 201, {"Etag": "some-opaque-string"}

api.add_resource(Todo1, "/t1")
api.add_resource(Todo2, "/t2")
api.add_resource(Todo3, "/t3")

保存到文件后執(zhí)行，使用 curl 測試一下

$curl http://127.0.0.1:5000/t1 -I
HTTP/1.0 200 OK
Content-Type: application/json
Content-Length: 30
Server: Werkzeug/0.12.2 Python/3.6.4
Date: Wed, 03 Jan 2018 15:07:07 GMT

$curl http://127.0.0.1:5000/t2 -I
HTTP/1.0 201 CREATED
Content-Type: application/json
Content-Length: 30
Server: Werkzeug/0.12.2 Python/3.6.4
Date: Wed, 03 Jan 2018 15:07:10 GMT

$curl http://127.0.0.1:5000/t3 -I
HTTP/1.0 201 CREATED
Content-Type: application/json
Content-Length: 30
Etag: some-opaque-string
Server: Werkzeug/0.12.2 Python/3.6.4
Date: Wed, 03 Jan 2018 15:05:58 GMT

很多時候在一個 API 中，你的資源可以通過多個URLs訪問。你可以把多個 URLs 傳給 Api 對象的 add_resource() 方法。每一個 URL 都能訪問到你的資源

api.add_resource(HelloWorld,
    "/",
    "/hello")

你還可以將路徑的部分匹配為資源方法的變量

api.add_resource(Todo,
    "/todo/", endpoint="todo_ep")

注：
如果一個請求與你的應(yīng)用程序端點(diǎn)中的任何一個都不匹配，F(xiàn)lask-RESTful 將會返回404錯誤，并附帶一段有關(guān)其它最相似匹配的端點(diǎn)建議。你可以通過在配置中將ERROR_404_HELP設(shè)置為 False禁用此項(xiàng)。

盡管 Flask 提供了便捷的方式獲取請求的數(shù)據(jù)（例：查詢字符串或POST 表單編碼的數(shù)據(jù)），驗(yàn)證表單依舊很痛苦。Flask-RESTful 內(nèi)置了支持驗(yàn)證請求數(shù)據(jù)，它使用了一個類似argparse 的庫。

from flask_restful import reqparse

parser = reqparse.RequestParser()
parser.add_argument("rate", type=int, help="Rate to charge for this resource")
args = parser.parse_args()

注：與 argparse 模塊不同的是，reqparse.RequestParser.parse_args() 返回了 Python 字典而不是一個自定義的數(shù)據(jù)結(jié)構(gòu)。

使用 reqparse 模塊同樣可以自由地提供全面的錯誤信息。如果一個參數(shù)沒有通過校驗(yàn)，F(xiàn)lask-RESTful 將會以一個400的錯誤請求以及高亮的錯誤信息回應(yīng)。

$ curl -d "rate=foo" http://127.0.0.1:5000/todos
{"status": 400, "message": "foo cannot be converted to int"}

inputs模塊提供許多常用的轉(zhuǎn)換函數(shù)，像 inputs.date() 和 inputs.url()。

調(diào)用 parse_args 傳入 strict=True 能夠確保當(dāng)請求包含了你的解析器中未定義的參數(shù)時拋出一個異常。

args = parser.parse_args(strict=True)

默認(rèn)情況下，在你的迭代返回中所有的字段都將會原樣呈現(xiàn)。當(dāng)你處理 Python 數(shù)據(jù)結(jié)構(gòu)的時候會覺得它很棒，但在處理對象時會變得非常令人沮喪。為了解決這個問題，F(xiàn)lask-RESTful 提供了fields 模塊以及 marshal_with()裝飾器。類似 Django ORM 和 WTForm ，你可以使用 fields 模塊來描述響應(yīng)的數(shù)據(jù)結(jié)構(gòu)。

from flask_restful import fields, marshal_with

resource_fields = {
    "task":   fields.String,
    "uri":    fields.Url("todo_ep")
}

class TodoDao(object):
    def __init__(self, todo_id, task):
        self.todo_id = todo_id
        self.task = task

        # This field will not be sent in the response
        self.status = "active"

class Todo(Resource):
    @marshal_with(resource_fields)
    def get(self, **kwargs):
        return TodoDao(todo_id="my_todo", task="Remember the milk")

上面的例子接收了一個 python對象并準(zhǔn)備將其序列化。marshal_with()裝飾器會通過resource_fields()進(jìn)行轉(zhuǎn)換。從對象中提取的唯一字段是 task。fields.Url是一個特殊的字段，它接受端點(diǎn)名稱并為響應(yīng)中的端點(diǎn)生成一個URL。您需要的許多字段類型已經(jīng)包含在其中?？梢圆榭?fields 項(xiàng)查看完整列表。

from flask import Flask
from flask_restful import reqparse, abort, Api, Resource

app = Flask(__name__)
api = Api(app)

TODOS = {
    "todo1": {"task": "build an API"},
    "todo2": {"task": "?????"},
    "todo3": {"task": "profit!"},
}


def abort_if_todo_doesnt_exist(todo_id):
    if todo_id not in TODOS:
        abort(404, message="Todo {} doesn"t exist".format(todo_id))

parser = reqparse.RequestParser()
parser.add_argument("task")


# Todo
# 顯示單個待辦任務(wù)，并允許刪除待辦任務(wù)項(xiàng)
class Todo(Resource):
    def get(self, todo_id):
        abort_if_todo_doesnt_exist(todo_id)
        return TODOS[todo_id]

    def delete(self, todo_id):
        abort_if_todo_doesnt_exist(todo_id)
        del TODOS[todo_id]
        return "", 204

    def put(self, todo_id):
        args = parser.parse_args()
        task = {"task": args["task"]}
        TODOS[todo_id] = task
        return task, 201


# TodoList
# 展示所有 todos 的列表，允許以POST的方式新建一個 tasks
class TodoList(Resource):
    def get(self):
        return TODOS

    def post(self):
        args = parser.parse_args()
        todo_id = int(max(TODOS.keys()).lstrip("todo")) + 1
        todo_id = "todo%i" % todo_id
        TODOS[todo_id] = {"task": args["task"]}
        return TODOS[todo_id], 201

# 設(shè)置 api 資源路由
api.add_resource(TodoList, "/todos")
api.add_resource(Todo, "/todos/")


if __name__ == "__main__":
    app.run(debug=True)

例子使用：

$ python api.py
 * Running on http://127.0.0.1:5000/
 * Restarting with reloader

獲取 Todo 列表

$ curl http://localhost:5000/todos
{"todo1": {"task": "build an API"}, "todo3": {"task": "profit!"}, "todo2": {"task": "?????"}}

獲取單個 Todo 任務(wù)

$ curl http://localhost:5000/todos/todo3
{"task": "profit!"}

刪除一個任務(wù)

$ curl http://localhost:5000/todos/todo2 -X DELETE -v

> DELETE /todos/todo2 HTTP/1.1
> Host: localhost:5000
> User-Agent: curl/7.52.1
> Accept: */*
>
* HTTP 1.0, assume close after body
< HTTP/1.0 204 NO CONTENT
< Content-Type: application/json
< Content-Length: 0
< Server: Werkzeug/0.12.2 Python/3.6.4
< Date: Wed, 03 Jan 2018 16:07:19 GMT

添加一個新的任務(wù)

$ curl http://localhost:5000/todos -d "task=something new" -X POST -v

> POST /todos HTTP/1.1
> Host: localhost:5000
> User-Agent: curl/7.52.1
> Accept: */*
> Content-Length: 18
> Content-Type: application/x-www-form-urlencoded
>
* upload completely sent off: 18 out of 18 bytes
* HTTP 1.0, assume close after body
< HTTP/1.0 201 CREATED
< Content-Type: application/json
< Content-Length: 32
< Server: Werkzeug/0.12.2 Python/3.6.4
< Date: Wed, 03 Jan 2018 16:05:27 GMT
<
{
    "task": "something new"
}
* Curl_http_done: called premature == 0
* Closing connection 0

更新任務(wù)

$ curl http://localhost:5000/todos/todo3 -d "task=something different" -X PUT -v

> PUT /todos/todo3 HTTP/1.1
> Host: localhost:5000
> User-Agent: curl/7.52.1
> Accept: */*
> Content-Length: 24
> Content-Type: application/x-www-form-urlencoded
>
* upload completely sent off: 24 out of 24 bytes
* HTTP 1.0, assume close after body
< HTTP/1.0 201 CREATED
< Content-Type: application/json
< Content-Length: 38
< Server: Werkzeug/0.12.2 Python/3.6.4
< Date: Wed, 03 Jan 2018 16:09:05 GMT
<
{
    "task": "something different"
}
* Curl_http_done: called premature == 0
* Closing connection 0

Python

Flask-RESTful

curl

requests

Flask-RESTful — Flask-RESTful 0.3.6 documentation