使用 Flask 编写 RESTful API

HTTP 的常用请求方法如下:

HTTP 方法	行为	示例
GET	获取资源的信息	http://example.com/api/orders
GET	获取某个特定资源的信息	http://example.com/api/orders/123
POST	创建新资源	http://example.com/api/orders
PUT	更新资源	http://example.com/api/orders/123
PATCH	对 PUT 方法的补充，用来对已知资源进行局部更新	http://example.com/api/orders/123
DELETE	删除资源	http://example.com/api/orders/123

REST 设计不需要特定的数据格式。在请求中数据可以以 JSON 形式, 或者有时候作为 url 中查询参数项。

RESTful API规划

HTTP 方法	URL	动作
GET	http://127.0.0.1:5000/api/v1/books	查询图书列表，支持分页查询，分页的参数为JSON格式数据：{"limit":10, "offset":0}
POST	http://127.0.0.1:5000/api/v1/books	添加新图书
GET	http://127.0.0.1:5000/api/v1/books/[book_id]	查询指定 id 的一本图书
PUT	http://127.0.0.1:5000/api/v1/books/[book_id]	更新指定 id 的图书
PATCH	http://127.0.0.1:5000/api/v1/books/[book_id]	更新指定 id 的图书, 与 PUT 方法相同
DELETE	http://127.0.0.1:5000/api/v1/books/[book_id]	删除指定 id 的图书

添加、修改 图书时，图书信息为 JSON 数据， 数据格式示例：{"title":"Python Web","author":"Tony John","summary":"This is a good book","published":"2020"}

实际部署时，将 URL 中的 127.0.0.1:5000 替换为相应的 主机名 或 IP地址

创建项目

创建名为 flask-book-app 的 flask 项目(步骤略)

项目中需要的包：

1. flask： Python 编写的 Web 应用程序框架

2. python-dotenv: 从文件中读取键值对，并将其设置为环境变量

3. flask-sqlalchemy： 数据库 ORM

4. flask-restful: 快速构建 REST APIs 的 Flask 扩展

5. flask-marshmallow：序列化和反序列化模块, 用来将复杂的 orm 对象 与 python 原生数据类型之间相互转换的库

6. flask-cors： 跨域请求配置模块

7. marshmallow-sqlalchemy: 用于 flask-marshmallow 与 flask-sqlalchemy 的集成

添加配置文件 .flaskenv, 内容如以下代码：

FLASK_ENV=development
FLASK_APP=bookapp

使用包组织项目代码

Flask 对项目结构没有固定要求，可以将所有代码放在 app.py 文件中, 但是这样会导致代码难以阅读和修改，因此这里使用包来组织整个项目的代码。

项目的最终结构如以下图所示：

.
|-- bookapp              --- 包名
|   |-- __init__.py      --- 包构造文件，创建程序实例
|   |-- command.py       --- 命令函数
|   |-- models.py        --- 模型类
|   `-- views.py         --- 视图函数，编写 RESTful API 的方法
|-- venv                 --- 虚拟环境文件夹
`-- data.db              --- Sqlite 数据库文件

添加文件夹 bookapp, 并在该文件夹中添加两个文件： __init__.py, views.py

编辑文件 bookapp\__init__.py, 内容如以下代码：

from flask import Flask

app = Flask(__name__)


from bookapp import views

编辑 bookapp\views.py, 内容如以下代码：

from bookapp import app


@app.route('/')
def index():
    return 'Hello world'

运行项目, 效果如下图:

使用数据库

编辑 bookapp\__init__.py, 内容如以下代码：

import os

from flask import Flask
from flask_sqlalchemy import SQLAlchemy

app = Flask(__name__)

app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///' + \
    os.path.join(os.path.dirname(app.root_path), 'data.db')
app.config['SQLALCHEMY_TRACK_MODIFICATIONS'] = False

db = SQLAlchemy(app)

# 确保这一行放在最后面
from bookapp import views, models 

添加数据模型类

在 bookapp 文件夹中添加文件 models.py, 编辑代码如以下：

from bookapp import db


class Book(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    title = db.Column(db.String(50))  # 标题
    author = db.Column(db.String(50))  # 作者
    summary = db.Column(db.String(250))  # 摘要
    published = db.Column(db.String(4))  # 发行年份

添加的命令实现数据库初始化

在 bookapp 文件夹中添加文件 command.py, 编辑代码如以下：

import click
from bookapp import app, db
from bookapp.models import Book


@app.cli.command()
def forge():
    '''
    用于初始化数据库的指令， 在虚拟环境下运行： flask forge
    '''
    db.create_all()
    books = [
        {
            'title': 'A Fire Upon the Deep',
            'author': 'Vernor Vinge',
            'summary': 'The coldsleep itself was dreamless.',
            'published': '1992'
        },
        {
            'title': 'The Ones Who Walk Away From Omelas',
            'author': 'Ursula K. Le Guin',
            'summary': 'With a clamor of bells that set the swallows soaring, the Festival of Summer came to the city Omelas, bright-towered by the sea.',
            'published': '1973'
        },
        {
            'title': 'Dhalgren',
            'author': 'Samuel R. Delany',
            'summary': 'to wound the autumnal city.',
            'published': '1975'
        },
        {
            'title': 'JavaScript Programming',
            'author': 'Samuel R. Delany',
            'summary': 'to wound the autumnal city.',
            'published': '2015'
        },
        {
            'title': 'Flask Web Development',
            'author': 'Ursula K. Le Guin',
            'summary': 'With a clamor of bells that set the swallows soaring, the Festival of Summer came to the city Omelas, bright-towered by the sea.',
            'published': '2018'
        },
    ]

    for item in books:
        book = Book(
            title=item['title'],
            author=item['author'],
            summary=item['summary'],
            published=item['published']
        )
        db.session.add(book)
    db.session.commit()
    click.echo('database initialized.')

编辑 bookapp\__init__.py, 在最后一行添加 command 模块的导入, 如以下代码:

import os

from flask import Flask
from flask_sqlalchemy import SQLAlchemy

app = Flask(__name__)

app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///' + \
    os.path.join(os.path.dirname(app.root_path),	'data.db')
app.config['SQLALCHEMY_TRACK_MODIFICATIONS'] = False

db = SQLAlchemy(app)

# 确保这一行放在最后面, 
from bookapp import views, models, command  # 这里多了一个 command 模块

在项目的虚拟环境下执行 flask forge 命令初始化数据，并添加数据到数据库中：

(venv) PS D:\sources\python_repos\flask-book-app> flask forge
database initialized.

编写 API 方法 ( 组织 Flask-RESTful 资源对象)

编辑 bookapp\views.py, 内容如以下代码：

from bookapp import app, db, ma, api
from bookapp.models import Book
from flask import jsonify, redirect, request
from flask_restful import Resource


class BookSchema(ma.Schema):
    class Meta:
        # 需要序列化的字段, 只有在这里列出的字段名才会转为 json 数据
        fields = ('id', 'title', 'author', 'summary', 'published')


# 单个模型数据的序列化
book_schema = BookSchema()
# 多个模型数据的序列化
books_schema = BookSchema(many=True)


class BookListResource(Resource):

    def get(self):
        '''
        查询图书，分页参数的请求格式：http://127.0.0.1:5000/api/v1/books?limit=3&offset=3
        使用默认参数的访问路径：http://127.0.0.1:5000/api/v1/books        
        '''

        # 分页的默认值
        limit = 10     # 每页大小（返回记录数）
        offset = 0     # 跳过记录数       

        ##### 接收 json 格式的参数 开始 , 这个方式不支持 url 地址传递的参数
        #  如果要从URL中接收参数，请导入  from flask_restful.reqparse import RequestParser         
        try:  # 加入异常处理，以防接收不到正确参数时程序崩溃
            if(request.json):
                limit = request.json['limit']
                offset = request.json['offset']
        except Exception as e:
            pass
        ##### 接收 json 格式的参数 结束 

        query = Book.query.offset(offset).limit(limit)  # 分页查询
        total = Book.query.count()         # 记录总数
        books = books_schema.dump(query)   # 将查询结果由对象类型转为 python 数据
        return jsonify({                   # 以JSON格式数据返回查询结果 
            "offset": offset,
            "limit": limit,
            "total_count": total,
            "books": books
        })

    def post(self):
        '''
        添加一本图书, 每本图书四个属性，不能为缺少
        访问路径：http://127.0.0.1:5000/api/v1/books
        '''
        try:
            new_book = Book(                  # 创建新图书
                title=request.json['title'],
                author=request.json['author'],
                summary=request.json['summary'],
                published=request.json['published']
            )
            db.session.add(new_book)    # 添加图书
            db.session.commit()         # 提交会话
            return book_schema.dump(new_book)  # 将查询结果由对象类型转为 python 数据
        except Exception as e:
            return None
        # return request.json['title']


class BookResource(Resource):
    def get(self, book_id):
        '''
        查询指定 id 的图书, 访问路径：http://127.0.0.1:5000/api/v1/books/2
        '''
        book = Book.query.get_or_404(book_id)   # 查询指定id的图书
        return book_schema.dump(book)

    def patch(self, book_id):
        '''
        修改指定 id 的图书
        patch 指令是 put 指令的升级，允许局部更新
        访问路径：http://127.0.0.1:5000/api/v1/books/2 (同时带上要修改的属性值 )
        '''
        try:
            book = Book.query.get_or_404(book_id)  # 查询指定id的图书
            if 'title' in request.json:            # 修改数据
                book.title = request.json['title']
            if 'author' in request.json:
                book.author = request.json['author']
            if 'summary' in request.json:
                book.summary = request.json['summary']
            if 'published' in request.json:
                book.published = request.json['published']
            db.session.commit()            # 提交会话
            return book_schema.dump(book)  # 返回修改成功后的图书信息
        except Exception as e:
            return None

    def put(self, book_id):
        '''
        put 指令 和 patch 指令是一样的
        '''
        return self.patch(book_id)

    def delete(self, book_id):
        ''' 
        删除指定 id 的图书
        访问路径：http://127.0.0.1:5000/api/v1/books/2
        '''
        book = Book.query.get_or_404(book_id)  # 查询指定id的图书
        db.session.delete(book)                # 删除图书
        db.session.commit()                    # 提交会话
        return '', 204


@app.route('/', methods=['GET'])
def index():
    # 跳转到 api对应的地址
    return redirect('/api/v1/books')

绑定资源与URI

编辑 bookapp\__init__.py, 加入跨域配置 和 序列化模块, 代码如下：

import os

from flask import Flask
from flask_sqlalchemy import SQLAlchemy  # 导入数据库 ORM 模块
from flask_cors import CORS  # 导入跨域配置模块

# flask_marshmallow 序列化和反序列化模块，
# 用于将复杂的orm模型对象与python原生数据类型之间相互转换
from flask_marshmallow import Marshmallow

# flask_restful 快速构建 REST APIs 的Flask 扩展
# http://www.pythondoc.com/Flask-RESTful/
from flask_restful import Api

app = Flask(__name__)    # 创建Flask实例

# 跨域允许
CORS(app, resources={r'/*': {'origins': '*'}})

# 配置数据库连接
app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///' + \
    os.path.join(os.path.dirname(app.root_path),	'data.db')

# 关闭数据库对象修改的跟踪
app.config['SQLALCHEMY_TRACK_MODIFICATIONS'] = False

db = SQLAlchemy(app)    # 初始化扩展 SQLAlchemy， 传入程序实例 app
ma = Marshmallow(app)   # 初始化扩展 Marshmallow， 传入程序实例 app
api = Api(app)          # 初始化扩展 Api， 传入程序实例 app


from bookapp import views, models, command  # 确保这一行放在最后面

from bookapp.views import BookListResource, BookResource    # 导入资源类

# 从 BookListResource 添加 api 资源,
# 对应分页查询 和 添加图书 这两个不需要 id 的操作
# 使用默认参数分页查询数据的地址：http://127.0.0.1:5000/api/v1/books
# 指定参数的分页查询数据的地址和参数示例：http://127.0.0.1:5000/api/v1/books?limit=3&offset=3
# 添加数据的访问路径：http://127.0.0.1:5000/api/v1/books
api.add_resource(BookListResource, '/api/v1/books')  # 添加资源及访问路径

# 从 BookResource 添加 api 资源，
# 对应 单个对图书查询， 删除、修改这三个 要指定 id 的操作
# 删除、修改和查询的访问路径：http://127.0.0.1:5000/api/v1/books/2
api.add_resource(BookResource, '/api/v1/books/<int:book_id>')  # 添加资源及访问路径

测试 RESTful API

运行项目

在虚拟环境下执行命令： flask run 运行项目，运行结果如下所示：

(venv) PS D:\sources\python_repos\flask-book-app> flask run
 * Serving Flask app 'bookapp' (lazy loading)
 * Environment: development
 * Debug mode: on
 * Restarting with stat
 * Debugger is active!
 * Debugger PIN: 129-008-647
 * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)

安装扩展

在 Visual Studio Code 中使用安装名为 PostCode 的扩展, 如下图所示：

无参数的默认分页查询图书测试

带参数的分页查询图书测试

查询指定 id 的图书测试

添加新图书测试

修改图书测试

删除图书测试

---