你用过 Json,但你却不知道什么是 JsonSchema ?也不知道它在工程中的最佳实践?

80 阅读3分钟

学会这款 全新技术的 Java 脚手架 ,从此面试不再怕!

Trump-mjga-logo_cn.png

slogan_long_2.png

有不少开发经验非常多的同学,他们对 JSON 的使用非常熟练,但却对 JSON Schema 一无所知。这让我不禁思考:为什么 JSON Schema 这样一个强大的工具,在工程实践中却没有得到应有的重视?今天,我们就来聊聊 JSON Schema,以及它在工程中的最佳实践。

什么是 JSON Schema?

JSON(JavaScript Object Notation)是一种轻量级的数据交换格式,广泛应用于前后端数据传输、配置文件、API 响应等场景。然而,JSON 本身并没有提供数据验证的机制。也就是说,你可以随意定义一个 JSON 对象,但它是否符合预期的结构、数据类型、取值范围等,JSON 本身是无法保证的。

这就是 JSON Schema 的用武之地。JSON Schema 是一种用于描述 JSON 数据结构的规范,它允许你定义 JSON 数据的格式、类型、约束条件等。通过 JSON Schema,你可以确保 JSON 数据在传输、存储、处理过程中符合预期的规范。

举个例子

假设我们有一个简单的 JSON 对象,描述了一个用户的基本信息:

{
  "name": "John Doe",
  "age": 30,
  "email": "john.doe@example.com"
}

如果我们希望对这个 JSON 对象进行验证,确保 name 是字符串,age 是正整数,email 是有效的电子邮件格式,我们可以定义一个 JSON Schema:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "age": {
      "type": "integer",
      "minimum": 0
    },
    "email": {
      "type": "string",
      "format": "email"
    }
  },
  "required": ["name", "age", "email"]
}

在这个 Schema 中,我们定义了 name 必须是字符串,age 必须是正整数,email 必须是有效的电子邮件格式,并且这三个字段都是必需的。

JSON Schema 的核心概念

1. 类型(Type)

JSON Schema 支持多种数据类型,包括 stringnumberintegerobjectarraybooleannull。通过 type 关键字,你可以指定 JSON 数据的类型。

2. 属性(Properties)

对于 object 类型的数据,你可以使用 properties 关键字来定义对象的属性及其对应的 Schema。

3. 必需字段(Required)

通过 required 关键字,你可以指定哪些字段是必需的。如果 JSON 数据中缺少这些字段,验证将失败。

4. 格式(Format)

format 关键字允许你对字符串进行更严格的验证。例如,email 格式会验证字符串是否符合电子邮件地址的格式,date-time 格式会验证字符串是否符合日期时间格式。

5. 约束条件(Constraints)

JSON Schema 提供了多种约束条件,如 minimummaximumminLengthmaxLength 等,用于对数据进行更精细的控制。

JSON Schema 在工程中的最佳实践

1. API 数据验证

在微服务架构中,API 是服务之间通信的桥梁。通过 JSON Schema,你可以在 API 的请求和响应中对数据进行验证,确保数据的完整性和一致性。

例如,假设我们有一个创建用户的 API,请求体如下:

{
  "name": "John Doe",
  "age": 30,
  "email": "john.doe@example.com"
}

我们可以使用 JSON Schema 对请求体进行验证:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1
    },
    "age": {
      "type": "integer",
      "minimum": 0
    },
    "email": {
      "type": "string",
      "format": "email"
    }
  },
  "required": ["name", "age", "email"]
}

在 Spring Boot 中,你可以使用 org.everit.json.schema 库来进行 JSON Schema 验证:

import org.everit.json.schema.Schema;
import org.everit.json.schema.loader.SchemaLoader;
import org.json.JSONObject;
import org.json.JSONTokener;

public class UserValidator {
    private final Schema schema;

    public UserValidator() {
        JSONObject schemaJson = new JSONObject(new JSONTokener(getClass().getResourceAsStream("/user-schema.json")));
        this.schema = SchemaLoader.load(schemaJson);
    }

    public void validate(JSONObject userJson) {
        schema.validate(userJson);
    }
}

2. 配置文件验证

在复杂的系统中,配置文件往往包含大量的参数和选项。通过 JSON Schema,你可以确保配置文件的正确性,避免因配置错误导致的系统故障。

例如,假设我们有一个配置文件 config.json

{
  "database": {
    "host": "localhost",
    "port": 3306,
    "username": "root",
    "password": "password"
  },
  "cache": {
    "enabled": true,
    "ttl": 3600
  }
}

我们可以定义一个 JSON Schema 来验证这个配置文件:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "database": {
      "type": "object",
      "properties": {
        "host": {
          "type": "string"
        },
        "port": {
          "type": "integer",
          "minimum": 0,
          "maximum": 65535
        },
        "username": {
          "type": "string"
        },
        "password": {
          "type": "string"
        }
      },
      "required": ["host", "port", "username", "password"]
    },
    "cache": {
      "type": "object",
      "properties": {
        "enabled": {
          "type": "boolean"
        },
        "ttl": {
          "type": "integer",
          "minimum": 0
        }
      },
      "required": ["enabled", "ttl"]
    }
  },
  "required": ["database", "cache"]
}

3. 数据存储验证

在将数据存储到数据库之前,使用 JSON Schema 对数据进行验证,可以确保数据的完整性和一致性。特别是在使用 NoSQL 数据库(如 MongoDB)时,JSON Schema 可以作为一种轻量级的数据验证机制。

结语

JSON Schema 是一个强大而灵活的工具,它可以帮助我们在工程实践中更好地管理和验证 JSON 数据。通过 JSON Schema,我们可以确保数据的完整性和一致性,减少因数据错误导致的系统故障。希望这篇文章能让你对 JSON Schema 有一个更深入的了解,并在实际项目中加以应用。


后记:后来我在团队推行 JSON Schema 时发现,最大的阻力不是技术实现,而是开发者思维的转变。就像《人月神话》中所说:"概念完整性是一个系统设计中最重要的考虑因素"。而 JSON Schema,正是维护这种完整性的现代武器。