php json schema,JSON Schema Validation介绍

工作中经常会开发一些接口公布出去，接口以HTTPHandler方式挂载在ASP.NET上，是以*.filetype的后缀形式路由到具体的处理类中。接口参数以JSON格式通过post方法写在Request body中，宿主的ERP系统并没有提供对应的参数校验框架，因此无法像其他基于其他API框架的形式，对输入参数进行统一的校验。

本文针对这种情况，将介绍下JSON.NET自带的JSON Schema校验方式。

之前在API实现中，对于多个参数的校验，往往是一并验证其合法性，否则只能依次校验单个参数，这样代码会显得很冗长。

如，若要对每个参数都进行校验，其方法实现大体如下：void DoSomething(object parma1, object parma2, object parma3)

{

if(param1 is invalid) throw exeception(param1 is invalid)

if(param2 is invalid) throw exeception(param2 is invalid)

if(param3 is invalid) throw exeception(param3 is invalid)

//do something

}

上述参数的合法性校验的代码块，不利于代码的阅读，也会使得这些非业务的处理方法充斥在整个方法中，干扰了关键的业务。因此，对于一些关键参数却无对应错误业务场景的参数，我都放在一起来校验：

如：void DoSomething(object parma1, object parma2, object parma3)

{

if((param1 is invalid) or (parma2 is invalid) or (parma3 is invalid)

throw exeception(params has invalid)

//do something

}

这样从代码长度来看是简洁了，可读性高了，可却给API使用者带来了困惑，对于多个参数来说，这里无法返回具体是哪个参数非法，给使用者带来了差错负担。因为平时很多API都是公布给部门多个同事使用，虽然API文档中有参数示例，但因为对于系统不是很熟悉，总免不了要来询问，每次都要一一解答，查看参数，个人觉得不胜其烦。于是想看看如何实现更友好、简洁的统一校验参数。

JSON Validation

由于API方法的参数都来自于HTTP请求中的Body，body是JSON格式的字符串，因此自然想到从JSON入手。项目中用的是JSON.NET,通过其官网文档发现有JSON validation这个功能，于是花了一上午的时间大致看了下各个文档，有了一定的了解。下面通过一个简单的例子来介绍下JSON Validation的使用方式，假设我们通过JSON串来表示产品目录，每个产品包含以下几个属性：* productId：产品标识

* productName:产品名称

* price： 售价

* tags： 可选的标签

那么我们可能会得到以下的JSON串：{

"productId": 1,

"productName": "A green door",

"price": 12.50,

"tags":["home", "green"]

}

JSON Scheme

JSON.NET Schema是用来校验任何JSON的合法性，它可以对已存在的JSON串进行校验或者用来校验你读取或写入的JSON格式。具体的介绍参考 JSON Schema。

下面来看一下Schema的结构：{

"$schema": "http://json-schema.org/draft-07/schema#",

"$id": "http://example.com/product.schema.json",

"title": "Product",

"description": "A product in the catalog",

"type": "object"

}

各属性含义如下：* Schema Keyword： $shema和$id

* Scheme Annotations: title和description

* Validation Keyword: type

实际上Scheme Keyword和Schema Annotation在一般情况下都是可以忽略的，我们要关注的是Validation Keyword和下面要介绍的properties.

根据产品的特性，productId可以是一个唯一的数字值，且不能为空。

因此我们在前面的JSON Schema中添加一下特性：* properties： 这个是validation keyword的关键字，用于表述对具体元素的校验规则；

* productId：假设为整形，且不能为空；

* required：validation关键字，是一个数组，表示数组内的元素不能缺省。

加入之后的JSON Schema如下：{

"$schema": "http://json-schema.org/draft-07/schema#",

"$id": "http://example.com/product.schema.json",

"title":"Product",

"description":"A product catalog",

"type":"object",

"properties": {

"productId":{

"description":"The unique identifier form a product",

"type":"integer"

}

},

"required":["productId"]

}

对于productName字段，type应该为string， 且不能为空，因此也是应该在required数组里面。

下面来谈谈price， type当然不能是integer了，因为正常都是包含小数的，所以应该是数值型number即可。而天下没有免费的午餐，所以我们可以添加规定值必须大于0.

将上述两个字段添加后的Schema如下：{

"$schema": "http://json-schema.org/draft-07/schema#",

"$id": "http://example.com/product.schema.json",

"title": "Product",

"description": "A product from Acme's catalog",

"type": "object",

"properties": {

"productId": {

"description": "The unique identifier for a product",

"type": "integer"

},

"productName": {

"description": "Name of the product",

"type": "string"

},

"price": {

"description": "The price of the product",

"type": "number",

"exclusiveMinimum": 0

}

},

"required": [ "productId", "productName", "price" ]

}

这里的exclusiveMinium:0,表示输入的值必须大于0. 如果对于exclusiveMinium关键词属性不清晰，可以参见JSON Schema的说明文档： json-schema-validation。

接下来再看看tags属性，一个商品可以有很多标签，但标签之间应该不能重复。所以tags的校验应该是一个数组，且数组元素之间是唯一的。

只对tags属性来看："tags": {

"description": "Tags for the product",

"type": "array",

"items": {

"type": "string"

},

"minItems": 1,

"uniqueItems": true

}

可以看到这里type为array表示一个数组，items是对数组里面的每个元素而言，minItems和uniqueItems则其义自见了。

嵌套的Schema

有时候我们的JSON串可能是嵌套的，如产品有尺寸的属性，用长、宽、高来表示。这时尺寸是product的元素，而尺寸本身也是一个对象，与product拥有相同的JSON validation结构。在我们的Validation中，只需要将dimensions的type指定为object，即可以用properties来校验其子元素。

将上述部分全部整合后的JSON Schema validation如下：{

"$schema": "http://json-schema.org/draft-07/schema#",

"$id": "http://example.com/product.schema.json",

"title": "Product",

"description": "A product from Acme's catalog",

"type": "object",

"properties": {

"productId": {

"description": "The unique identifier for a product",

"type": "integer"

},

"productName": {

"description": "Name of the product",

"type": "string"

},

"price": {

"description": "The price of the product",

"type": "number",

"exclusiveMinimum": 0

},

"tags": {

"description": "Tags for the product",

"type": "array",

"items": {

"type": "string"

},

"minItems": 1,

"uniqueItems": true

},

"dimensions": {

"type": "object",

"properties": {

"length": {

"type": "number"

},

"width": {

"type": "number"

},

"height": {

"type": "number"

}

},

"required": [ "length", "width", "height" ]

}

},

"required": [ "productId", "productName", "price" ]

}

最后，我们给出一个符合上述validation的JSON串：{

"productId": 1,

"productName": "An ice sculpture",

"price": 12.50,

"tags": [ "cold", "ice" ],

"dimensions": {

"length": 7.0,

"width": 12.0,

"height": 9.5

}

}

JSON.NET提供了在线校验的工具，可以根据你定义的Schema Validation实时反馈输入的JSON串是否合法。对于日常开发时，可以先根据参数将对应的Schema定义好，这样可以节省不少调试的时间。Online Validation Tool.

Reference: