快速創建Flask Restful API項目

前言

Python必學的兩大web框架之一Flask，俗稱微框架。它只需要一個文件，幾行代碼就可以完成一個簡單的http請求服務。

但是我們需要用flask來提供中型甚至大型web restful api服務的時候就需要我們來規划項目結構。

Django 框架有自身的生成項目結構的命令和生成app的命令，但是Flask沒有。

這篇文章主要介紹使用工具幫助我們進行一些Flask rest api項目初始化的工作

cookiecutter-flask-restful 介紹

cookiecutter-flask-restful是一個基於cookiecutter的Flask rest api項目生成器，你可以用它快速生成Flask restful api項目。

目前支持的python版本：3.6 | 3.7 | 3.8

項目特性

• Flask應用工廠函數，使用藍圖
• 集成Flask命令行接口
• 數據遷移
• JWT登錄認證
• 分頁工具類
• 單元測試
• 使用環境變量配置
• 集成swagger UI

主要使用的包

• Flask
• Flask-RESTful
• Flask-Migrate
• Flask-SQLAlchemy
• Flask-Marshmallow
• Flask-JWT-Extended
• marshmallow-sqlalchemy
• passlib
• tox
• pytest
• factoryboy
• dotenv
• apispec

快速開始

安裝cookiecutter

$ pip3 install cookiecutter

創建第一個項目

$ cookiecutter https://github.com/karec/cookiecutter-flask-restful

一路按回車鍵，就會生成一個新項目。

項目名字暫且叫myproject, app名字暫且叫myapi。

運行項目

如果項目使用了pipenv管理虛擬環境：

安裝依賴：

$ cd myproject
$ pipenv install -r requirements.txt

# 進入到虛擬環境
$ pipenv shell

$ pip install -e .
$ myapi db upgrade
$ myapi init
$ myapi --help

啟動項目：

$ pipenv run flask run

測試項目：

登錄請求：

$ curl -X POST -H "Content-Type: application/json" -d '{"username": "admin", "password": "admin"}' http://localhost:5000/auth/login

登錄返回：

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE1ODYyMjUyNzIsIm5iZiI6MTU4NjIyNTI3MiwianRpIjoiZDM3NmViODktYWFkOC00ODZkLWE1NmUtZDdiNmQ3NjNhYmI2IiwiZXhwIjoxNTg2MjI2MTcyLCJpZGVudGl0eSI6MSwiZnJlc2giOmZhbHNlLCJ0eXBlIjoiYWNjZXNzIn0.-xCHCJHS3lKeiar-Z12HSOwd2DxAb9EeKFg9zMKWHfU",
  "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE1ODYyMjUyNzIsIm5iZiI6MTU4NjIyNTI3MiwianRpIjoiMTcyNmI0ODEtMDJjYi00NWFhLTgyOWUtOGY0ODJlYmFlZTEyIiwiZXhwIjoxNTg4ODE3MjcyLCJpZGVudGl0eSI6MSwidHlwZSI6InJlZnJlc2gifQ.fpFH_vw8Lp-_xjDVoFLjF6HnjOKXR7PCLKIp8v9gSSU"
}

---

獲取所有用戶請求：

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE1ODYyMjUyNzIsIm5iZiI6MTU4NjIyNTI3MiwianRpIjoiZDM3NmViODktYWFkOC00ODZkLWE1NmUtZDdiNmQ3NjNhYmI2IiwiZXhwIjoxNTg2MjI2MTcyLCJpZGVudGl0eSI6MSwiZnJlc2giOmZhbHNlLCJ0eXBlIjoiYWNjZXNzIn0.-xCHCJHS3lKeiar-Z12HSOwd2DxAb9EeKFg9zMKWHfU" http://127.0.0.1:5000/api/v1/users

獲取所有用戶返回：

{
    "total": 3,
    "pages": 1,
    "next": "/api/v1/users?page=1&per_page=50",
    "prev": "/api/v1/users?page=1&per_page=50",
    "results": [
        {
            "active": true,
            "id": 1,
            "email": "[e-mail]",
            "username": "admin"
        },
        {
            "active": true,
            "id": 2,
            "email": "",
            "username": ""
        },
        {
            "active": true,
            "id": 3,
            "email": "string",
            "username": "string"
        }
    ]
}

---

刷新token請求：

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZGVudGl0eSI6MSwiaWF0IjoxNTEwMDAwNDQxLCJ0eXBlIjoicmVmcmVzaCIsImp0aSI6IjRmMjgxOTQxLTlmMWYtNGNiNi05YmI1LWI1ZjZhMjRjMmU0ZSIsIm5iZiI6MTUxMDAwMDQ0MSwiZXhwIjoxNTEyNTkyNDQxfQ.SJPsFPgWpZqZpHTc4L5lG_4aEKXVVpLLSW1LO7g4iU0" http://127.0.0.1:5000/auth/refresh

刷新token返回：

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoiYWNjZXNzIiwiaWRlbnRpdHkiOjEsImlhdCI6MTUxMDAwMDYxOCwiZnJlc2giOmZhbHNlLCJqdGkiOiIzODcxMzg4Ni0zNGJjLTRhOWQtYmFlYS04MmZiNmQwZjEyNjAiLCJuYmYiOjE1MTAwMDA2MTgsImV4cCI6MTUxMDAwMTUxOH0.cHuNf-GxVFJnUZ_k9ycoMMb-zvZ10Y4qbrW8WkXdlpw"
}

---

如果沒有使用pipenv管理虛擬環境，直接使用的系統python環境:

$ cd myproject
$ pip install -r requirements.txt
$ pip install -e .

# 初始化項目
$ myapi db upgrade
$ myapi init
$ myapi --help

測試項目同上

項目環境變量配置

環境變量在.flaskenv文件中

FLASK_ENV=development
FLASK_APP="myapp.app:create_app"
SECRET_KEY=changeme
DATABASE_URI="sqlite:////tmp/myapp.db"
CELERY_BROKER_URL=amqp://guest:guest@localhost/  # only present when celery is enabled
CELERY_RESULT_BACKEND_URL=amqp://guest:guest@localhost/  # only present when celery is enabled

請根據你的實際情況進行配置。

測試

直接用tox

$ tox

使用pytest

$ pip install pytest pytest-runner pytest-flask pytest-factoryboy factory_boy
$ pytest

使用docker-compose 和 Makefile

make tests

如果出現連接失敗，你需要更改redis | rabbitmq地址

使用wsgi服務啟動

gunicorn示例:

$ pip install gunicorn
$ gunicorn myapi.wsgi:app

uwsgi示例：

$ pip install uwsgi
$ uwsgi --http 127.0.0.1:5000 --module myapi.wsgi:app

使用celery

啟動celery

$ celery worker -A myapi.celery_app:app --loglevel=info

如果你的配置沒有問題，在終端你會看到：

[tasks]
  . myapi.tasks.example.dummy_task

調用task：

>>> from myapi.tasks.example import dummy_task
>>> result = dummy_task.delay()
>>> result.get()
'OK'

使用celery extension:

>>> from myapi.extensions import celery
>>> celery.send_task('myapi.tasks.example.dummy_task').get()
'OK'

使用Docker

注意：目前Docker的配置只有開發環境

構建鏡像：

$ docker build -t myapp .

啟動鏡像：

$ docker run --env-file=.flaskenv myapp myapi init
$ docker run --env-file=.flaskenv -p 5000:5000 myapp myapi run -h 0.0.0.0
 * Serving Flask app "myapi.app:create_app" (lazy loading)
 * Environment: development
 * Debug mode: on
 * Running on http://0.0.0.0:5000/ (Press CTRL+C to quit)
 * Restarting with stat
 * Debugger is active!
 * Debugger PIN: 214-619-010

使用docker-compose啟動：

$ docker-compose up -d
$ docker ps
$ docker exec -it <container_id> myapi init

使用docker-compose 和 Makefile啟動

make init

Makefile 命令

make init # 初始化環境
make build # 構建鏡像
make run # 啟動鏡像
make db-migrate # 遷移數據
make db-upgrade # 數據映射到數據庫
make test # 執行測試

使用Swagger

打開UI頁面地址：http://localhost:5000/swagger-ui

頁面如下：

在config.py文件進行配置：

• APISPEC_TITLE: 頁面標題，默認： {{cookiecutter.project_name}}
• APISPEC_VERSION: api版本，默認： 1.0.0
• OPENAPI_VERSION: OpenAPI 版本，默認： 3.0.2
• SWAGGER_JSON_URL: JSON規范校驗地址, 默認： /swagger.json
• SWAGGER_UI_URL: 頁面UI地址，默認： /swagger-ui
• SWAGGER_URL_PREFIX: 藍圖URL前綴, 默認： None

Enjoy your code, good luck.