jsonschema+装饰器实现更简单的python参数校验

作为一个后端开发人员，永远不要相信你的用户输入，也不要相信自己~所以，参数校验是一个非常重要的环节，千万千万不要忽视。
最近也涉及到很多需要严格参数校验的接口开发工作，之前使用过很多方式进行参数校验，主要有以下两种：

在接口内部直接依次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更细节的内容未做介绍，又更深的需求情参考官方文档进行对照学习，希望对你有帮助。

jsonschema+装饰器 实现更简单的python参数校验

一、 安装方式： pip install jsonschema