共计 6999 个字符，预计需要花费 18 分钟才能阅读完成。
一、RESTful Api 设计风格
1、什么是 RESTFul
-
简介
REST 即表述性状态传递（英文：Representational State Transfer，简称 REST）是 Roy Fielding 博士在 2000 年他的博士论文中提出来的一种软件架构风格。它是一种针对网络应用的设计和开发方式，可以降低开发的复杂性，提高系统的可伸缩性。
RESTFul 是一种软件架构风格、设计风格，而不是标准，只是提供了一组设计原则和约束条件。它主要用于客户端和服务器交互类的软件。基于这个风格设计的软件可以更简洁，更有层次，更易于实现缓存等机制。
REST 指的是一组架构约束条件和原则。满足这些约束条件和原则的应用程序或设计就是 RESTful。遵循 restful 风格开发出来的应用程序接口，就叫 RESTFul API。
RESTFul 的接口都是围绕资源以及对资源的各种操作展开
-
资源
所谓的资源就是在网络上存在的任意实体，哪怕是一条消息。
-
操作
所谓的操作就是对资源的 CURD。在开发者设计良好的前提下，对网络资源的任意的动作都可抽象为对资源的 CURD。RESTFul 对网络资源的操作抽象为 HTTP 的 GET、POST、PUT、DELETE 等请求方法以完成对特定资源的增删改查
2、协议
API 与用户的通信协议总是使用 https 协议
3、域名
应尽量将 API 部署在专用域名下
https://www.xialigang.com
如果确定 API 很简单，不会有进一步扩展，可以放在主域名下
https://www.xialigang.com/api/
4、版本
应该将版本放入 URL
https://www.xialigang.com/api/v1/
可以将版本放入 http 头信息中
5、路径
说明
- 表示 API 的具体地址
注意
- 每个网址代表一种资源，所以网址中不能有动词，只能是名词，而且所用的名词往往与数据库中的表名对应
示例
-
错误示例
https://127.0.0.1/api/v1/getStudents/ -
正确示例
https://127.0.0.1/api/v1/students/
6、使用正确的 HTTP 请求方式
| 方法 | 行为 | 例子 |
|---|---|---|
| GET | 获取所有资源 | http://127.0.0.1:5000/api/source |
| GET | 获取指定资源 | http://127.0.0.1:5000/api/source/250 |
| POST | 创建新的资源 | http://127.0.0.1:5000/api/source |
| PUT | 更新指定资源 | http://127.0.0.1:5000/api/source/250 |
| DELETE | 删除指定资源 | http://127.0.0.1:5000/api/source/250 |
| DELETE | 删除所有资源 | http://127.0.0.1:5000/api/source/ |
7、过滤信息
-
概述
如果资源较多，服务器不能将所有的数据一次全部返回给客户端，API 提供参数，过滤返回结果 -
参数
-
limit 获取多少个资源
GET https://127.0.0.1:5000/api/v1/students/?limit=10
-
offset 偏移多少个资源
GET https://127.0.0.1:5000/api/v1/students/?offset=10 -
page 要获取哪页的资源
-
per_page 每页有多个资源
GET https://127.0.0.1:5000/api/v1/students/?page=1&per_page=5 -
sortby 根据哪个属性进行排序
-
orderby 排序的规则
GET https://127.0.0.1:5000/api/v1/students/?sortby=age&orderby=desc
-
类名小写_运算符_属性 = 值
GET https://127.0.0.1:5000/api/v1/students/?student_gt_age=20
-
8、状态码
| 状态码 | 请求方式 | 说明 |
|---|---|---|
| 200 | get | OK 服务器成功返回资源 |
| 201 | post、put、patch | Created 用户新建或者修改资源成功 |
| 202 | * | Accepted 表示请求已经进入后台排队 |
| 204 | delete | No Content 用户删除资源成功 |
| 400 | post、put、patch | Bad Request 用户发出的请求有错误 |
| 401 | * | Unauthorized 用户没有权限（令牌、用户名、密码错误） |
| 403 | * | Forbidden 表示用户得到授权（与 401 相对），但是访问是被禁止的 |
| 404 | * | Not Found 请求针对的是不存在的资源 |
| 405 | * | Method Not Allowed 用户请求的方式不被允许 |
| 406 | get | Not Acceptable 用户请求的格式不可得（比如用户请求 json 格式，但是只有 xml 格式） |
| 410 | get | Gone 用户请求的资源被永久删除，且不可在得到 |
| 422 | post、put、patch | Unprocessable Entity 创建对象时发生了验证错误 |
| 500 | * | Internal Server Error 服务器发生错误 |
9、错误处理
如果状态码是 4xx，就应该向用户返回错误信息，一般返回内容中以 error 作为键，错误信息作为值返回
{"error": "参数有误"
}
10、链接相关的资源
-
说明
返回的结果中提供了链接，链向其他 API 方法啊，需要让用户不查看文档（项目文档）就知道下一步该干什么
-
实例
地址
GET /students/<id>/{"name": "lucky", "age": 50, "link": "https://127.0.0.1/api/v1/test/" }restful 风格
{"name": "lucky", "age": 50, "link": {"rel": "collection 127.0.0.1:5000" "href": "127.0.0.1/api/v1/test/" "title": "测试界面" "type": "application/json" } }键
- rel 表示这个 API 与当前网址的关系
- href 表示 API 的路径
- title 表示 API 的标题
- type 表示返回数据的类型
11、工具
-
说明
postman 是一款非常好用的 API 开发测试工具，可以非常方便的模拟各种请求
-
提示
下载安装包，一路 NEXT 完成安装
网址：https://www.postman.com/
二、原生实现 RESTful
1、准备数据
# 测试数据
posts = [
{'id': 1,
'title': 'Python 语法',
'content': '别人都说 python 语法很简单，但是每次问题都出在语法上'
},
{'id': 2,
'title': 'HTML',
'content': '不就是几个标签的问题嘛，但是最好细心点'
}
]
2、获取资源
-
获取所有资源
# 获取资源列表 @app.route('/posts') def get_posts_list(): return jsonify({'posts': posts}) -
获取指定资源
# 获取指定资源 @app.route('/posts/<int:pid>') def get_posts(pid): p = list(filter(lambda p: p['id'] == pid, posts)) if len(p) == 0: abort(404) return jsonify({'posts': p[0]})
3、添加新的资源
# 添加新的资源
@app.route('/posts', methods=['POST'])
def create_posts():
if not request.json or 'title' not in request.json or 'content' not in request.json:
abort(400)
# 创建新资源
p = {'id': posts[-1]['id'] + 1,
'title': request.json['title'],
'content': request.json['content']
}
# 保存资源
posts.append(p)
return jsonify({'posts': p}), 201
4、更新指定的资源
# 修改指定资源
@app.route('/posts/<int:pid>', methods=['PUT'])
def update_posts(pid):
p = list(filter(lambda p: p['id'] == pid, posts))
if len(p) == 0:
abort(404)
if 'title' in request.json:
p[0]['title'] = request.json['title']
if 'content' in request.json:
p[0]['content'] = request.json['content']
return jsonify({'posts': p[0]}), 201
5、删除指定资源
# 删除指定资源
@app.route('/posts/<int:pid>', methods=['DELETE'])
def delete_posts(pid):
p = list(filter(lambda p: p['id'] == pid, posts))
if len(p) == 0:
abort(404)
posts.remove(p[0])
return jsonify({'result': '数据已删除'}), 204
6、删除所有资源
# 删除所有资源
@app.route('/posts', methods=['DELETE'])
def delete_posts(pid):
posts.clear()
return jsonify({'result': '数据已删除'}), 204
7、错误定制
@app.errorhandler(404)
def page_not_found(e):
return jsonify({'error': 'page not found'}), 404
@app.errorhandler(400)
def bad_request(e):
return jsonify({'error': 'bad request'}), 400
三、flask-restful
1、安装
pip install flask-restful
2、创建
from flask_restful import Api
api = Api()
from .ext_api import api
3、加载
from exts import api
api.init_app(app)
4、视图类
from flask_restful import Resource
from myApp.models import User
from flask import request
# 创建用户处理类
class UserApi(Resource):
def get(self, uid):
u = User.query.get(uid)
if u:
return {'code':0, 'error':'','data':{'id':uid, 'uusername':u.uusername, 'uage': u.uage, 'usex': u.usex, 'uinfo': u.uinfo}}
else:
return {'code':1, 'error':'获取失败','data':{}}, 404
def put(self, uid):
u = User.query.get(uid)
if not u:
return {'code':1, 'error':'获取失败','data':{}}, 404
json = request.json
u.uusername = json.get('uusername')
u.uage = json.get('uage')
u.save()
return {'code': 0, 'error': '',
'data': {'id': uid, 'uusername': u.uusername, 'uage': u.uage, 'usex': u.usex, 'uinfo': u.uinfo}}, 201
def delete(self, uid):
u = User.query.get(uid)
if not u:
return {'code': 1, 'error': '获取失败', 'data': {}}, 404
u.delete()
return {'code': 0, 'error': '', 'data': {}}, 204
class UserApiTwo(Resource):
def get(self):
u = User.query.all()
userList = []
for user in u:
userList.append({'id':user.id, 'uusername':user.uusername, 'uage': user.uage, 'usex': user.usex, 'uinfo': user.uinfo})
return {'code': 0, 'error': '', 'data': userList}
def delete(self):
uList = User.query.all()
for u in uList:
u.delete()
return {'code':0, 'error': '', 'data':''}, 204
def post(self):
json = request.json
u = User()
u.uusername = json.get('uusername')
u.uage = json.get('uage')
u.usex = bool(json.get('usex'))
u.uinfo = json.get('uinfo')
print(json)
if u.save():
return {'code': 0, 'error': '',
'data': {'id': u.id, 'uusername': u.uusername, 'uage': u.uage, 'usex': u.usex,'uinfo': u.uinfo}}, 201
return {'code':1 ,'error':'创建失败', 'data':''}, 400
5、配置路由
# 添加资源，可以一个资源指定多个路由地址
api.add_resource(UserAPI, '/users/<int:uid>', '/u/<int:uid>')
api.add_resource(UserListAPI, '/users/')
# 若创建 Api 对象时没有指定 app，那么指定 app 的位置应放在添加资源之后
6、拆分路由和视图
api 目录下一个文件就是一个模型相关的视图类，urls.py 仅做路由的匹配
from myApp.api.api_user import UserApi, UserListAPI
# 配置路由
api.add_resource(UserAPI, '/users/<int:uid>', '/u/<int:uid>')
api.add_resource(UserListAPI, '/users/')
7、添加认证
-
说明
Restful API 不保存状态，无法依赖 Cookie 及 Session 来保存用户信息，自然也无法使用 Flask-Login 扩展来实现用户认证。所以这里，我们就要介绍另一个扩展，Flask-HTTPAuth
-
安装
pip install flask-httpauth
-
示例
from itsdangerous import TimedJSONWebSignatureSerializer as Serializer from flask_httpauth import HTTPBasicAuth # 创建对象 auth = HTTPBasicAuth() # 认证的回调函数 @auth.verify_password def verify_password(username_or_token, password): # 去数据库有中进行查找 u = User.query.filter(User.uusername == username_or_token, User.upassword == password).first() print(username_or_token, '=====>',password) if u: # if username_or_token == 'lucky' and password == '123456': g.username = username_or_token return True # 验证 token s = Serializer(current_app.config['SECRET_KEY']) try: data = s.loads(username_or_token) g.username = data['username'] return True except: return False # 认证错误定制 @auth.error_handler def unauthorized(): return jsonify({'error': 'Unauthorized Access'}), 403获取 token
# 获取 token @app.route('/get_token') @auth.login_required def generate_token(): s = Serializer(app.config['SECRET_KEY'], expires_in=3600) return s.dumps({'username': g.username})保护指定的视图类
class UserAPI(Resource): # 添加认证 decorators = [auth.login_required]
