Web后端学习笔记 Flask （12）Restful

Restful API规范

restful API是用于在前端与后台进行通信的一套规范，使用这个规范可以让前后端开发变得更加轻松：

1. 协议：http或者https

2. 数据传输格式：json

3. url链接：url链接中，不能有动词，只能有名词，并且对于一些名词，如果出现复数，就用复数的形式

4. http请求方法：

GET：在服务器上获取资源

POST：在服务器上新创建一个资源

PUT：在服务器上更新资源（客户端提供所有改变后的数据）

PATCH：在服务器上更新资源（只需提供需要改变的信息）

DELETE：从服务器上删除资源

举例：
GET/users/ ：获取所有用户

POST/user/：创建一个用户

GET/user/id/：根据id获取一个用户

PUT/user/id/：更新某个id的用户信息（需要提供用户的所=所有信息）

PATCH/user/id/：更新某个id的用户信息（只需提供需要修改的数据）

DELETE/user/id/：删除一个用户

状态码：

状态码	原生描述	描述
200	OK	服务器成功响应客户端请求
400	INVALID REQUEST	用户发出的请求有误，服务器没有进行新建或者修改数据
401	Unauthorized	用户没有权限访问这个请求
403	Forbidden	因为某些原因禁止访问这个请求
404	NOT FOUND	用户请求的url不存在
406	NOT Acceptable	用户请求不被服务器接受，例如服务器期望客户端发送某个字段，但是没有发送
500	Internal Server error	服务器内部错误，比如出现了bug

Restful插件：

通过 pip install flask-restful安装flask-restful插件

定义restful视图函数：如果使用flask-restful，那么定义视图函数的时候，需要继承自flask-restful.Resource这个类，然后再根据当前请求的method来定义响应的方法。类似于类视图的功能，可以分别定义get方法与post方法。

工具：postman做接口测试

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

app = Flask(__name__)
app.config.from_object(config)

api = Api(app=app)


class LoginView(Resource):
    def post(self):
        return {"username": "tom"}


api.add_resource(LoginView, '/login/', endpoint='login')


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


if __name__ == '__main__':
    app.run()

注意事项：

1. endpoint是用来给url_for反转url的时候使用的。如果不写endpoint，那么将会使用视图的名字的小写来作为endpoint。

2. add_resource的第二个参数是访问这个视图函数的url,这个url和之前的route一样，也可以传递参数，并且这个方法还可以传递多个url来指定这个视图函数。

class LoginView(Resource):
    # 如果add_resource绑定了多个url，如果没有传参，可以将视图函数中的参数设置为None
    # 此时即使url中没有传递参数，也不会报错
    def post(self, username=None):    
        return {"username": username}


api.add_resource(LoginView, '/login/<username>/', '/register/', endpoint='login')

注意事项：
1. 如果向返回json数据，那么就使用flask-restful，如果向渲染模板，那么好是采用视图函数或者类视图的方法。

2. url还是和之前的一样，可以传递参数。不同的是视图函数的是，可以绑定多个视图函数。

flask-restful参数

flask-restful插件提供了类似于WTForms来验证提交的数据是否合法，叫做reparse

class LoginView(Resource):
    # 如果add_resource绑定了多个url，如果没有传参，可以将视图函数中的参数设置为None
    # 此时即使url中没有传递参数，也不会报错
    def post(self):
        parse = reqparse.RequestParser()
        parse.add_argument("username", type=str, help="用户名验证错误")
        parse.add_argument("password", type=str, help="密码验证错误")
        args = parse.parse_args()
        return {"username": args.get("username"), "password": args.get("password")}


api.add_resource(LoginView, '/login/', endpoint='login')

在不传参数的时候，返回的结果：

在post方法中传递参数之后，可以看到返回的结果：

add_argument可以指定的字段：
1. default: 当没有传递相应参数的时候，设置这个参数的默认值

2. required：是否必须传递这一参数， 布尔值

3. type：指定提交的参数的类型，如果指定，那么将使用指定的数据类型来强制转换提交上来的值。

4. choices：选项，提交上来的值只有满足这个选项中的值才能验证通过

5. help：错误信息，如果验证失败，将会使用这个参数指定的值作为错误信息

6. trim：是否要取出前后的空格

type字段的值，可以使用python内置的数据类型，也可以使用flask-restful.input中的类型，例如：

url：判断传入的参数是否为url

regex：正则表达式

date：将这个字符串转换为datetime.date，如果转换失败，则会抛出异常

from flask import Flask, render_template, request
from flask_restful import Api, Resource, reqparse, inputs
import config

app = Flask(__name__)
app.config.from_object(config)

api = Api(app=app)


class LoginView(Resource):
    # 如果add_resource绑定了多个url，如果没有传参，可以将视图函数中的参数设置为None
    # 此时即使url中没有传递参数，也不会报错
    def post(self):
        parse = reqparse.RequestParser()
        parse.add_argument("username", type=str, help="用户名验证错误", trim=True)
        parse.add_argument("password", type=str, help="密码验证错误", trim=True)
        parse.add_argument("age", type=int, help="年龄验证错误", trim=True)
        parse.add_argument("render", type=str, choices=["female", "male"], trim=True, help="性别填写错误")
        parse.add_argument("link", type=inputs.url, trim=True, help="url填写错误")
        parse.add_argument("phone", type=inputs.regex(r"1[3578]\d{9}"), trim=True, help="电话号码格式错误")
        args = parse.parse_args()
        return {"username": args.get("username"),
                "password": args.get("password"),
                "age": args.get("age"),
                "render": args.get("render")}


api.add_resource(LoginView, '/login/', endpoint='login')


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


if __name__ == '__main__':
    app.run()

Flask-restful标准：
输出字段： 

对于一个视图函数，可以指定好一些字段用于返回。在可以使用ORM模型或者自定义模型的时候，它会自动获取模型中的相应字段，生成json数据，然后再返回给客户端。这其中需要导入flask_restful.marshal_with装饰器，并且需要写一个字典，来指示需要返回的字段，以及该字段的数据类型。 

from flask import Flask, render_template, request
from flask_restful import Api, Resource, fields, marshal_with
import config

app = Flask(__name__)
app.config.from_object(config)

api = Api(app=app)


class ArticleView(Resource):
    resource_fields = {
        "title": fields.String,
        "content": fields.String
    }    # 指定需要返回的字段

    @marshal_with(resource_fields)
    def get(self):
        return {"title": "xxx", "content": "yyy"}


api.add_resource(ArticleView, '/articles/', endpoint="articles")


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


if __name__ == '__main__':
    app.run()

有的字段没有值，在return的字典中没有写，也会返回为null值：

class ArticleView(Resource):
    resource_fields = {
        "title": fields.String,
        "content": fields.String
    }    # 指定需要返回的字段

    @marshal_with(resource_fields)
    def get(self):
        return {"title": "xxx"}    # 即使此时content字段没有值，也会返回为null,这样就保证了接口比较规范


api.add_resource(ArticleView, '/articles/', endpoint="articles")

返回的结果：

这种方式还有一个好处，就是如果相应的数据是一个模型，则可以直接返回模型的对象即可，而不用构建字典

from flask import Flask, render_template, request
from flask_restful import Api, Resource, fields, marshal_with
import config

app = Flask(__name__)
app.config.from_object(config)

api = Api(app=app)


class Article(object):
    def __init__(self, title, content):
        self.title = title
        self.content = content


article = Article(title="gone with wind", content="xsddkkjsdv")


class ArticleView(Resource):
    resource_fields = {
        "title": fields.String,
        "content": fields.String
    }    # 指定需要返回的字段

    @marshal_with(resource_fields)
    def get(self):
        return article    # 可以根据article对象中的属性自动构造字典，返回字典


api.add_resource(ArticleView, '/articles/', endpoint="articles")


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


if __name__ == '__main__':
    app.run()

复杂结构：

返回的字段的值任然是一个模型，则需要使用Nested()方法再定义一个字典，返回相应的字段

# 定义一个restful视图
class ArticleView(Resource):
    resource_field = {
        "title": fields.String,
        "content": fields.String,
        "author": fields.Nested({     # User类型
            "username": fields.String,
            "email": fields.String
        }),
        "tags": fields.Nested({
            "name": fields.String
        })
    }

    @marshal_with(resource_field)
    def get(self, article_id):
        article = db.session.query(Article).filter(Article.id == article_id).first()
        return article


api.add_resource(ArticleView, '/articles/<article_id>/', endpoint="article")

使用field.Nested()之后，返回的的数据如下所示：

重命名属性：

在读取模型中的某个字段之后，需要用一个新的名字将其返回，可以使用attribute属性实现：

例如，需要将article中的title属性返回，并赋予一个新的属性名：

# 定义一个restful视图
class ArticleView(Resource):
    resource_field = {
        "article_title": fields.String(attribute="title"),    # 改变属性的名字
        "article_content": fields.String(attribute="content"),
        "article_author": fields.Nested({     # User类型
            "username": fields.String,
            "email": fields.String
        }, attribute="author"),
        "article_tags": fields.Nested({
            "name": fields.String
        }, attribute="tags")
    }

    @marshal_with(resource_field)
    def get(self, article_id):
        article = db.session.query(Article).filter(Article.id == article_id).first()
        return article


api.add_resource(ArticleView, '/articles/<article_id>/', endpoint="article")

返回结果：

默认值：

在resource_field中定义的一些字段，如果模型中没有与之对应的字段，则该字段的值会被设置为null返回。除此之外，还可以给没有的字段设置默认值，最后返回的该字段的值就是默认值，而不是null.

class ArticleView(Resource):
    resource_field = {
        "article_title": fields.String(attribute="title"),    # 改变属性的名字
        "article_content": fields.String(attribute="content"),
        "article_author": fields.Nested({     # User类型
            "username": fields.String,
            "email": fields.String
        }, attribute="author"),
        "article_tags": fields.Nested({
            "name": fields.String
        }, attribute="tags"),
        "read_cnt": fields.Integer(default=100)
    }

    @marshal_with(resource_field)
    def get(self, article_id):
        article = db.session.query(Article).filter(Article.id == article_id).first()
        return article


api.add_resource(ArticleView, '/articles/<article_id>/', endpoint="article")

此时返回的read_cnt字段的值就是默认值100：

Flask-restful细节：

1. flask-restful结合蓝图使用

在flask-restful中使用蓝图，需要将蓝图定义到一个单独的文件即可，此时在定义api的时候，以蓝图为参数，而不用再以app作为定义api的参数，在主app主注册蓝图：

例如，定义蓝图的文件，articleViews.py

# -*- coding: utf-8 -*-

from flask import Blueprint
from flask_restful import Resource, fields, marshal_with, Api
from models import User, Article, Tag
from exts import db

article_bp = Blueprint("article", __name__, url_prefix="/article")
api = Api(article_bp)      # api


# 定义一个restful视图
class ArticleView(Resource):
    resource_field = {
        "article_title": fields.String(attribute="title"),    # 改变属性的名字
        "article_content": fields.String(attribute="content"),
        "article_author": fields.Nested({     # User类型
            "username": fields.String,
            "email": fields.String
        }, attribute="author"),
        "article_tags": fields.Nested({
            "name": fields.String
        }, attribute="tags"),
        "read_cnt": fields.Integer(default=100)
    }

    @marshal_with(resource_field)
    def get(self, article_id):
        article = db.session.query(Article).filter(Article.id == article_id).first()
        return article


api.add_resource(ArticleView, "/<article_id>/", endpoint="article")

在主app.py文件中注册蓝图：

from flask import Flask, render_template, request
import config
from exts import db
from models import User, Article, Tag
from articleViews import article_bp

app = Flask(__name__)
app.config.from_object(config)
db.init_app(app=app)

app.register_blueprint(article_bp)   # 注册蓝图


@app.route('/')
def index():
    user = User(username="kong", email="123tg@gmail.com")
    article = Article(title="gone", content="hover")
    article.author = user
    tag1 = Tag(name="java")
    tag2 = Tag(name="python")
    article.tags.extend([tag1, tag2])
    db.session.add(article)
    db.session.commit()
    return "Hello"


if __name__ == '__main__':
    app.run()

其中models文件为定义ORM模型的文件：models.py

# -*- coding: utf-8 -*-
from exts import db


class User(db.Model):
    __tablename__ = "user"
    id = db.Column(db.Integer, primary_key=True, autoincrement=True)
    username = db.Column(db.String(50), nullable=False)
    email = db.Column(db.String(50), nullable=False)


# tag和article之间是多对多的关系
article_tag = db.Table("article_tag",
                       db.Column("article_id", db.Integer, db.ForeignKey("article.id"), primary_key=True),
                       db.Column("tag_id", db.Integer, db.ForeignKey("tag.id"), primary_key=True),
                       )


class Article(db.Model):
    __tablename__ = "article"
    id = db.Column(db.Integer, primary_key=True, autoincrement=True)
    title = db.Column(db.String(100), nullable=False)
    content = db.Column(db.Text)

    author_id = db.Column(db.Integer, db.ForeignKey("user.id"))

    author = db.relationship("User", backref="articles")
    tags = db.relationship("Tag", secondary=article_tag, backref="articles")


class Tag(db.Model):
    __tablename__ = "tag"
    id = db.Column(db.Integer, primary_key=True)
    name = db.Column(db.String(50))

2. flask-restful渲染模板

falsk-restful规定的数据交互的形式是JSON，所以即使返回渲染的模板（及render_templlate(html文件)），此时在浏览器中显示的还是字符串形式的，而不会当作html代码被浏览器解析：此时需要借助一个装饰器，@api.representation("text/html")来定义一个函数，在这个函数中对html代码进行封装，再进行返回

# -*- coding: utf-8 -*-

from flask import Blueprint, render_template, make_response
from flask_restful import Resource, fields, marshal_with, Api
from models import User, Article, Tag
from exts import db

article_bp = Blueprint("article", __name__, url_prefix="/article")
api = Api(article_bp)      # api


@api.representation("text/html")      # 保证restful也能够通过render_template渲染模板
def output_html(data, code, headers):
    # data是字符串形式的html文本
    resp = make_response(data)    # 构造Response对象
    return resp


# 定义一个restful视图
class ArticleView(Resource):
    resource_field = {
        "article_title": fields.String(attribute="title"),    # 改变属性的名字
        "article_content": fields.String(attribute="content"),
        "article_author": fields.Nested({     # User类型
            "username": fields.String,
            "email": fields.String
        }, attribute="author"),
        "article_tags": fields.Nested({
            "name": fields.String
        }, attribute="tags"),
        "read_cnt": fields.Integer(default=100)
    }

    @marshal_with(resource_field)
    def get(self, article_id):
        article = db.session.query(Article).filter(Article.id == article_id).first()
        return article


class ArticleListView(Resource):
    def get(self):
        return render_template("html/list.html")
        # 此时，restful返回的依然是字符串形式的html文本，不能被浏览器解析


api.add_resource(ArticleView, "/<article_id>/", endpoint="article")
api.add_resource(ArticleListView, '/list/', endpoint="list")