作为一个后端开发人员，永远不要相信你的用户输入，也不要相信自己~所以，参数校验是一个非常重要的环节，千万千万不要忽视。
最近也涉及到很多需要严格参数校验的接口开发工作，之前使用过很多方式进行参数校验，主要有以下两种：
- 在接口内部直接依次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更细节的内容未做介绍，又更深的需求情参考官方文档进行对照学习，希望对你有帮助。