使用 JsonSchema 验证 API 的返回格式

Intro

最近我们的 API 提供给了别的团队的小伙伴用，按照他们的需求做了接口的改动，API 返回的数据结构有一些变化，我们提供的接口有缓存，数据库更新之后不会马上刷新，于是就想验证一下数据是不是已经更新成最新的版本，都更新好了之后就告诉别的团队的小伙伴做集成，那么如何来验证是不是最新版本 API 呢？现在我们的 API 基本上都是 JSON，于是就想尝试使用 Json Schema 来验证我们的 API

What

Json 是 JavaScript Object Notation 的缩写，它是一种简化的数据交换格式，是目前互联网服务间进行数据交换最常见的一种交换格式，具有简洁、可读性好等特点。

Json Schema 是用来定义 json 数据约束的一个标准，可以清晰的描述JSON数据的结构，是一种描述JSON数据的JSON数据。。根据这个约定模式，交换数据的双方可以理解 json 数据的要求和约束，也可以据此对数据进行验证，保证数据交换的正确性。

Why

为什么我们要使用 JSON schema 呢，在我们日常的使用中你也可以已经在使用了，只是没有察觉，我们在编辑一些 JSON 配置文件的时候，有时候会有一些提示，自动提示匹配的属性名，这其实就是 Json shcema 带来的好处，一些比较知名的项目的配置文件大多会提供一个自己的 json schema，这不仅仅会为开发者们带来配置的便利，也会便于实现 json 格式的校验

总结一下 Json Schema 能够带来的好处

• 智能提示 json-schema-lint
• 格式校验，自动化测试
• Mock 数据生成，基于 schema 的数据生成

支持 Json-Schema 的编辑器有很多

• Android Studio
• CLion
• IntelliJ IDEA
• JSONBuddy
• Neovim
• PhpStorm
• PyCharm
• ReSharper
• Rider
• RubyMine
• Visual Studio 2013+
• Visual Studio Code
• Visual Studio for Mac
• WebStorm
• …

Sample

对于下面这样一段 json

{

  "productId": 1,

  "productName": "A green door",

  "price": 12.50,

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

}

JsonSchema 示例：

{

  "$schema": "https://json-schema.org/draft/2020-12/schema", // schema 规范版本，可以没有

  "$id": "https://example.com/product.schema.json", // json schema 地址，可以没有

  "title": "Product", // json schema 的标题信息，可以没有

  "description": "A product from Acme's catalog", // json schema 的描述信息，可以没有

  "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 // 约束最小值不能小于0

    },

    "tags": { // 属性名称

      "description": "Tags for the product", // 属性描述

      "type": "array", // 属性类型

      "items": {

        "type": "string" // 属性类型

      },

      "minItems": 1, // 约束条件，至少要有一个元素

      "uniqueItems": true // 不能有重复项

    }

  },

  "required": [ "productId", "productName", "price" ] // 必须的属性，不存在则不符合 schema 的约束

}

JSON Schema 的核心定义了以下基本类型：

• string
• number
• integer
• object
• array
• 布尔值
• null

除了上面的这些验证类型，还有很多验证，具体可以参考：https://json-schema.org/draft/2020-12/json-schema-validation.html

Pracetice

我选择的是 JsonSchema.Net，这个是基于 System.Text.Json 来实现的一个 Json schema 的扩展，使用起来也还好，上手也比较简单

构建 json schema 的简单示例：

var jsonSchema = new JsonSchemaBuilder()

    .Properties(

        ("name", new JsonSchemaBuilder()

            .Type(SchemaValueType.String)

            .MinLength(1)

            .MaxLength(10)

        ),

        ("age", new JsonSchemaBuilder()

            .Type(SchemaValueType.Number)

            .Minimum(1)

        )

        )

    .Required("name")

    .Build();

这个示例构建了一个简单的 json 对象，这个对象有两个属性一个 name 一个 age，其中 name 是必须的属性，

name 是一个最小长度为1，最大长度为 10 的字符串，age 是一个最小值为 1 的数字

除了使用 JsonSchemaBuilder 自己构建一个 json schema，现在有很多在线的基于一段 json 自动生成 json schema 的工具，我们也可以从一个 json schema 文件或者一个 Stream或者一段 schema 文本来获取一个 json schema，本质就是读取一段 json 反序列成了一个 json schema 对象

const string testJsonSchema = @"

{

  ""$schema"": ""https://json-schema.org/draft/2020-12/schema"",

  ""type"": ""object"",

  ""properties"": {

    ""Data"": {

      ""type"": ""array"",

      ""items"":

        {

          ""type"": ""object"",

          ""properties"": {

            ""NoticeTitle"": {

              ""type"": ""string""

            },

            ""NoticeCustomPath"": {

              ""type"": ""string""

            },

            ""NoticePublishTime"": {

              ""type"": ""string""

            }

          },

          ""required"": [

            ""NoticeTitle"",

            ""NoticeCustomPath"",

            ""NoticePublishTime""

          ]

        }

    },

    ""PageNumber"": {

      ""type"": ""integer""

    },

    ""PageSize"": {

      ""type"": ""integer""

    },

    ""TotalCount"": {

      ""type"": ""integer""

    },

    ""PageCount"": {

      ""type"": ""integer""

    },

    ""Count"": {

      ""type"": ""integer""

    }

  },

  ""required"": [

    ""Data"",

    ""PageNumber"",

    ""PageSize"",

    ""TotalCount"",

    ""PageCount"",

    ""Count""

  ]

}

";

var schema = JsonSchema.FromText(testJsonSchema);

有了 json schema 之后我们就可以用来验证 json 是否合法了，JsonSchema 中有一个 ValidationResults Validate(JsonElement root, ValidationOptions? options = null) 的方法

在 2.2.0 之前的版本你需要将 json 转换为 JsonElement 来进行验证，下面是文档给出的示例，你需要先获取获取一个 JsonDocument，然后使用 JsonDocument 的 RootElement 来验证

JsonSchema schema = new JsonSchemaBuilder()

    .Properties(

        (

            "myProperty", new JsonSchemaBuilder()

                .Type(SchemaValueType.String)

                .MinLength(10)

        )

    )

    .Required("myProperty");

var emptyJson = JsonDocument.Parse("{}").RootElement;

var booleanJson = JsonDocument.Parse("{\"myProperty\":false}").RootElement;

var stringJson = JsonDocument.Parse("{\"myProperty\":\"some string\"}").RootElement;

var shortJson = JsonDocument.Parse("{\"myProperty\":\"short\"}").RootElement;

var numberJson = JsonDocument.Parse("{\"otherProperty\":35.4}").RootElement;

var nonObject = JsonDocument.Parse("\"not an object\"").RootElement;



var emptyResults = schema.Validate(emptyJson);

var booleanResults = schema.Validate(booleanJson);

var stringResults = schema.Validate(stringJson);

var shortResults = schema.Validate(shortJson);

var numberResults = schema.Validate(numberJson);

var nonObjectResults = schema.Validate(nonObject);

感觉这样太不方便，于是就写了两个扩展方法来方便直接从 JsonDocument 和 string 来验证

public static ValidationResults Validate(this JsonSchema jsonSchema, JsonDocument jsonDocument, ValidationOptions? validationOptions = null)

{

    return jsonSchema.Validate(jsonDocument.RootElement, validationOptions);

}



public static ValidationResults Validate(this JsonSchema jsonSchema, string jsonString, ValidationOptions? validationOptions = null)

{

    using var jsonDocument = JsonDocument.Parse(jsonString);

    return jsonSchema.Validate(jsonDocument, validationOptions);

}

并且提了 PR，现在使用 2.2.0 版本就可以直接用了

var validateResults = schema.Validate("{}");

WriteLine(validateResults.IsValid);

返回的结果中 IsValid 就代表了这个 Json 是否符合这个 json schema 的约束，true 就是满足约束，false 就是不满足

默认的验证结果，不会返回具体的错误信息，你可以指定一个 ValidationOption，指定 OutputFormat 为 Detailed 来返回具体的错误信息

var schema = JsonSchema.FromText(testJsonSchema);



var validationOptions = new ValidationOptions()

{

    OutputFormat = OutputFormat.Detailed

};



var invalidJson = @"{

  ""Data"": [

    {

      ""NoticeExternalLink"": null

    }

  ],

  ""PageNumber"": 1,

  ""PageSize"": 10,

  ""TotalCount"": 5,

  ""PageCount"": 1,

  ""Count"": 5

}

";



var validateResult = schema.Validate(invalidJson, validationOptions);

WriteLine(validateResult.IsValid);

WriteLine(validateResult.Message);

输出结果如下：

False

Required properties [NoticeTitle, NoticeCustomPath, NoticePublishTime] were not present

验证 API 返回结果：

using var httpClient = new HttpClient();

var result = await httpClient.GetStringAsync("http://reservation.weihanli.xyz/api/notice");

validateResult = schema.Validate(result, validationOptions);

WriteLine(validateResult.IsValid);

WriteLine(validateResult.Message);

More

这个库的作者除了实现了 JsonSchema 的支持，还提供了对于 JsonPath、JsonPatch 等支持，有需要的可以关注一下 https://github.com/gregsdennis/json-everything

作者还提供了一个扩展库，可以基于强类型的 Model 直接生成一个 schema，不需要再自己构建 schema

除了这个库你也可以选择别的库来实现，Newtonsoft.Json.Schema 是基于 Newtosoft.Json 实现的 JsonSchema 的支持，也可以尝试一下

References

• https://json-schema.org/
• https://www.tutorialspoint.com/json/json_schema.htm
• https://json-schema.org/learn/getting-started-step-by-step.html
• https://json-schema.org/draft/2020-12/json-schema-validation.html
• https://json-schema.apifox.cn/
• https://www.jsonschemavalidator.net/
• https://www.schemastore.org/json/
• https://github.com/gregsdennis/json-everything
• https://github.com/gregsdennis/json-everything/pull/238
• https://github.com/WeihanLi/SamplesInPractice/blob/master/JsonSample/SystemTextJsonSample/JsonSchemaSample.cs

文章转自微信公众号@amazingdotnet