作为一个后端开发人员,永远不要相信你的用户输入,也不要相信自己~所以,参数校验是一个非常重要的环节,千万千万不要忽视。
最近也涉及到很多需要严格参数校验的接口开发工作,之前使用过很多方式进行参数校验,主要有以下两种:
- 在接口内部直接依次if else校验,这种只针对比较简单单一的接口;
- 自己针对不同参数校验需求,定制的参数校验方法,在相应接口内调用。但是写多了会发现重复代码较多;
- 使用marshmallow的序列化类进行校验,使用较为方便和清晰,但是他主要是针对模型类序列化使用的,我大多时候只是校验json参数而已。
然后了解到了今天写的主角:jsonschema库,专为json数据校验而生,更加的灵活,使用字典配置化的方式定义校验。
一、 安装方式: pip install jsonschema
若不想自己定义schema,可在https://jsonschema.net/home输入示例json在线生成schema哦!
二、官方简单示例
这里先直接上一个官方的示例代码,了解下jsonschema的使用方式:
>>> from jsonschema import validate
>>> # A sample schema, like what we'd get from json.load()
>>> schema = {
... "type" : "object",
... "properties" : {
... "price" : {"type" : "number"},
... "name" : {"type" : "string"},
... },
... }
>>> # If no exception is raised by validate(), the instance is valid.
>>> validate(instance={"name" : "Eggs", "price" : 34.99}, schema=schema)
>>> validate(
... instance={"name" : "Eggs", "price" : "Invalid"}, schema=schema,
... ) # doctest: +IGNORE_EXCEPTION_DETAIL
Traceback (most recent call last):
...
ValidationError: 'Invalid' is not of type 'number'
这里再做个简单名词解释:
- schema变量就是定义的具体参数校验配置;
-
type
指定该层级参数类型,object
为json对象,array
为数组,number
为数字包含小数,string
为字符串,integer
为整数... -
properties
指定该层级具体字段名及属性限制; -
required
指定该层级必须的字段名,未在其中的字段可缺失; -
validate
方法即调用参数验证的方式,指定instance
待校验的json对象,schema
指定使用的校验配置;
...
下面将针对两个实例做使用代码展示。
三、需求实例
准备了两个实例进行学习,明白后基本能够学会该校验方式的基本使用。
- 需求一:
需要对下列结构的用户参数进行校验,user_id
为大于0的整数;user_name
为字符串;age
为一定范围内的整数;other
字段为嵌套json的非必须字段,但若other字段存在,则hobby
字段为字符串且必须,height
字段为数值型非必须。
{
"user_id": 123456,
"user_name": "John",
"age": 12,
"other": {
"hobby": "swimming",
"height": 170.3
}
}
- 需求二:需要对下列结构的公司参数进行校验,model字段为字符串;count字段为不小于0的整数;data为数组结构,内嵌json数据,内嵌字段company_name与cust_uid不可缺失,value值为字符串,不为空且小于一定长度。
{
"model": "st",
"count": 4,
"data": [
{"company_name": "测试公司1", "cust_uid": "asd4a676762jjhj"},
{"company_name": "测试公司2", "cust_uid": "andfu58jkskjds3"}
]
}
四、代码结构
为了增加代码的复用性和可读性,我将模拟项目内代码规范,使用分层代码结构+装饰器进行参数校验功能实现,代码结构如下:
代码结构
- app.py:模拟接口文件,其内包含接收json参数且需要进行参数校验的接口函数;
- decorators.py:用于存放项目内的装饰器函数,这里只有一个参数校验装饰器;
- schema.py:定义各类参数校验的配置字典,也应该算是使用
jsonschema
库的核心
五、代码示例
以下开始直接分享针对两个需求的参数校验代码,一定注意各个字段名含义及层级关系,可对应上文中的需求介绍来了解每行是在做什么。
schema.py
# 需求1的用户校验schema字典定义
schema_user = {
"type": "object",
"required": ["user_id", "user_name", "age"],
"properties": {
"user_id": {
"type": "integer",
"minimum": 1
},
"user_name": {
"type": "string",
"minLength": 1,
"maxLength": 20
},
"age": {
"type": "integer",
"minimum": 1,
"maximum": 120
},
"other": {
"type": "object",
"required": ["hobby"],
"properties": {
"hobby": {"type": "string"},
"height": {"type": "number"}
}
}
}
}
# 需求2的公司校验schema字典定义
schema_company = {
"type": "object",
"required": ["data", "count"],
"properties": {
"model": {
"type": "string"
},
"count": {
"type": "integer",
"minimum": 1
},
"data": {
"type": "array",
"items": {
"type": "object",
"required": ["company_name", "cust_uid"],
"properties": {
"company_name": {
"type": "string",
"minLength": 1
},
"cust_uid": {
"type": "string",
"minLength": 10,
"maxLength": 100
}
}
}
}
}
}
-
decorators.py
该装饰器接收一个schema参数,即上面定义的shema校验字典对象,可针对接收data参数的接口或方法进行data参数校验,校验通过再返回data数据,否则打印或抛出异常参数信息, 我这里为了演示没有抛出异常,只是做了打印处理。
from jsonschema import validate, ValidationError
# data参数校验装饰器,可指定不同的校验schema
def json_validate(schema):
def wrapper(func):
def inner(data, *args, **kwargs):
try:
validate(data, schema)
except ValidationError as e:
print("参数校验失败:{}!".format(e.message))
else:
print("参数校验通过!")
return func(data, *args, **kwargs)
return inner
return wrapper
-
app.py
用户数据处理接口及公司数据处理接口,需要接收原始用户或公司的json数据参数,这里导入上面定义的装饰器和schema字典实现简洁的参数校验功能。
from decorators import json_validate
from schema import schema_user, schema_company
@json_validate(schema=schema_company)
def company_api(data):
# 公司数据操作接口示例
print("company_api执行入库操作!")
return data
@json_validate(schema=schema_user)
def user_api(data):
# 用户数据操作接口示例
print("use_api执行入库操作!")
return data
六. 测试校验
在app.py
下进行测试校验输出:
- 正确的参数测试:
if __name__ == '__main__':
company_dict = {
"model": "st",
"count": 4,
"data": [
{"company_name": "测试公司1", "cust_uid": "asd4a676762jjhj"},
{"company_name": "测试公司2", "cust_uid": "andfu58jkskjds3"}
]
}
company_api(company_dict)
user_dict = {
"user_id": 123456,
"user_name": "John",
"age": 12,
"other": {
"hobby": "swimming",
"height": 170.3
}
}
user_api(user_dict)
输出:
参数校验通过!
company_api执行入库操作!
参数校验通过!
use_api执行入库操作!
- 错误的用户参数输入测试:
- 用户年龄输入:0,小于最小值限制
if __name__ == '__main__':
user_dict = {
"user_id": 123456,
"user_name": "John",
"age": 0,
"other": {
"hobby": "swimming",
"height": 170.3
}
}
user_api(user_dict)
输出:
参数校验失败:0 is less than the minimum of 1!
- 内嵌字典不传hobby参数
if __name__ == '__main__':
user_dict = {
"user_id": 123456,
"user_name": "John",
"age": 12,
"other": {
"height": 170.3
}
}
user_api(user_dict)
输出:
参数校验失败:'hobby' is a required property!
- 错误的公司参数输入测试:
- 内嵌字典参数cust_uid输入空字符串:''
if __name__ == '__main__':
company_dict = {
"model": "st",
"count": 4,
"data": [
{"company_name": "测试公司1", "cust_uid": ""},
{"company_name": "测试公司2", "cust_uid": "andfu58jkskjds3"}
]
}
company_api(company_dict)
输出:
参数校验失败:'' is too short!
- count输入小数:3.1
if __name__ == '__main__':
company_dict = {
"model": "st",
"count": 3.1,
"data": [
{"company_name": "测试公司1", "cust_uid": "asd"},
{"company_name": "测试公司2", "cust_uid": "andfu58jkskjds3"}
]
}
company_api(company_dict)
输出:
参数校验失败:3.1 is not of type 'integer'!
以上,就不再一一测试每种情况了。
七、 总结
jsonschema使用类似配置字典的方式来定义参数校验,使用起来十分的清晰,理解起来也比较简单,后期更改也更容易。且报错信息也比较清晰,一般无需再定制化错误信息,个人目前更加喜欢这个方式来进行json参数的校验。
本篇文章还使用了装饰器的方式对需要验参的方法进行装饰,复用性更强,且使主体逻辑更加简洁,还是那句话,装饰器是个好东西,jsonschema也是好东西,都要尽量用起来才是真的啊~
本文对jsonschema更细节的内容未做介绍,又更深的需求情参考官方文档进行对照学习,希望对你有帮助。