JAVA 生成结构化 JSON 不稳定？加入 JSON Schema 引导提示 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

JAVA 生成结构化 JSON 不稳定？JSON Schema 来救场！

大家好！今天我们来聊聊一个在使用 Java 处理 JSON 数据时经常遇到的问题：生成结构化 JSON 的不稳定性。很多时候，我们依赖于各种库来生成 JSON，但当数据结构稍微复杂，或者需要严格保证输出格式时，就容易出现问题。今天我将重点介绍如何利用 JSON Schema 来引导和约束 JSON 的生成过程，从而提高其稳定性和可靠性。

JSON 生成不稳定性的根源

在深入 JSON Schema 之前，我们先来分析一下 JSON 生成不稳定的常见原因：

数据类型不一致： Java 是一种强类型语言，而 JSON 相对来说类型约束较弱。例如，Java 的 Integer 和 Double 都可能被序列化为 JSON 中的 number 类型，但具体是整数还是浮点数，取决于具体的值。如果接收方对数据类型有严格要求，就会出现问题。
字段缺失或冗余： 在复杂的业务场景下，不同的模块可能需要不同字段的 JSON 数据。如果生成 JSON 的逻辑没有统一的管理，很容易出现字段缺失或冗余，导致兼容性问题。
字段顺序不确定： 尽管 JSON 规范没有明确规定字段的顺序，但在某些情况下，接收方可能依赖于特定的字段顺序。不同的 JSON 库在序列化时，字段顺序可能会有所不同，导致问题。
空值处理不一致： 对于 Java 中的 null 值，不同的 JSON 库有不同的处理方式。有些库会将其序列化为 JSON 的 null，有些库则会直接忽略该字段。
枚举类型处理： Java 的枚举类型在序列化为 JSON 时，通常会转换为字符串。但不同的序列化库可能使用枚举值的 name() 方法或者 toString() 方法，导致输出不一致。
日期格式不统一： 日期在 JSON 中通常以字符串形式表示，但不同的库可能使用不同的日期格式。
动态数据结构： 有时候我们需要生成一些结构不确定的 JSON，例如包含动态 Key 的 Map。在这种情况下，很难保证生成的 JSON 符合预期的结构。

JSON Schema 的概念与作用

JSON Schema 是一种用于描述 JSON 数据结构的词汇表。它可以用来验证 JSON 数据是否符合预期的结构和数据类型，也可以用来自动生成文档、客户端代码等。

简单来说，JSON Schema 就像是 JSON 数据的“合同”，定义了数据的结构、类型、必需字段、可选字段、取值范围等等。

JSON Schema 的主要作用包括：

数据验证： 确保 JSON 数据符合预期的结构和数据类型。
数据文档化： 提供 JSON 数据的清晰描述，方便开发者理解和使用。
代码生成： 根据 JSON Schema 自动生成客户端代码、数据模型等。
契约测试： 在微服务架构中，可以使用 JSON Schema 来进行契约测试，确保服务之间的接口兼容性。

使用 JSON Schema 引导 JSON 生成

现在我们来看看如何使用 JSON Schema 来引导 Java 中的 JSON 生成过程，从而提高 JSON 的稳定性和可靠性。

1. 定义 JSON Schema

首先，我们需要定义一个 JSON Schema，描述我们期望的 JSON 结构。例如，我们定义一个描述用户的 JSON Schema：

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "User",
  "description": "A schema for a user object",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "description": "The unique identifier for the user."
    },
    "firstName": {
      "type": "string",
      "description": "The user's first name."
    },
    "lastName": {
      "type": "string",
      "description": "The user's last name."
    },
    "email": {
      "type": "string",
      "format": "email",
      "description": "The user's email address."
    },
    "age": {
      "type": "integer",
      "description": "The user's age.",
      "minimum": 0
    },
    "isActive": {
      "type": "boolean",
      "description": "Indicates if the user is active."
    },
    "roles": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": ["admin", "user", "guest"]
      },
      "description": "The user's roles."
    },
    "address": {
      "type": "object",
      "properties": {
        "street": {
          "type": "string"
        },
        "city": {
          "type": "string"
        },
        "zipCode": {
          "type": "string",
          "pattern": "^\d{5}(?:-\d{4})?$"
        }
      },
      "required": ["street", "city", "zipCode"]
    }
  },
  "required": ["id", "firstName", "lastName", "email", "age"]
}

这个 JSON Schema 定义了一个 User 对象，包含 id、firstName、lastName、email、age、isActive、roles 和 address 字段。它还定义了每个字段的类型、描述、取值范围等。例如：

id 字段必须是整数类型。
email 字段必须是字符串类型，并且符合 email 格式。
age 字段必须是整数类型，并且大于等于 0。
roles 字段必须是字符串数组，并且每个字符串必须是 "admin"、"user" 或 "guest" 中的一个。
address 字段必须是一个对象，包含 street、city 和 zipCode 字段，其中 zipCode 字段必须符合邮政编码格式。
id、firstName、lastName、email 和 age 字段是必需的。

2. 使用 JSON Schema 验证 JSON 数据

在生成 JSON 之前，我们可以使用 JSON Schema 验证数据，确保数据符合预期的结构和类型。

我们可以使用 org.everit.jsonvalidator 库来进行 JSON Schema 验证。首先，我们需要添加 Maven 依赖：

<dependency>
    <groupId>org.everit.jsonvalidator</groupId>
    <artifactId>org.everit.jsonvalidator</artifactId>
    <version>1.5.1</version>
</dependency>

然后，我们可以使用以下代码来验证 JSON 数据：

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

import java.io.InputStream;

public class JsonSchemaValidator {

    public static void validate(JSONObject json, String schemaPath) {
        try (InputStream schemaStream = JsonSchemaValidator.class.getResourceAsStream(schemaPath)) {
            JSONObject rawSchema = new JSONObject(new JSONTokener(schemaStream));
            Schema schema = SchemaLoader.load(rawSchema);
            schema.validate(json);
            System.out.println("JSON data is valid.");
        } catch (ValidationException e) {
            System.err.println("JSON data is invalid:");
            e.getAllMessages().forEach(System.err::println);
            throw new IllegalArgumentException("Invalid JSON data", e); // Re-throw for handling in calling code
        } catch (Exception e) {
            System.err.println("Error loading schema or validating JSON:");
            e.printStackTrace();
            throw new RuntimeException("Error during schema validation", e); // Re-throw for handling in calling code
        }
    }

    public static void main(String[] args) {
        // Example usage
        String schemaPath = "/user-schema.json"; // Place the JSON schema file in the resources folder
        JSONObject validJson = new JSONObject();
        validJson.put("id", 123);
        validJson.put("firstName", "John");
        validJson.put("lastName", "Doe");
        validJson.put("email", "[email protected]");
        validJson.put("age", 30);

        JSONObject invalidJson = new JSONObject();
        invalidJson.put("id", "abc"); // Invalid type
        invalidJson.put("firstName", "John");
        invalidJson.put("lastName", "Doe");
        invalidJson.put("email", "[email protected]");
        invalidJson.put("age", 30);

        try {
            validate(validJson, schemaPath);
        } catch (IllegalArgumentException e) {
            System.err.println("Validation failed for validJson: " + e.getMessage());
        }

        try {
            validate(invalidJson, schemaPath);
        } catch (IllegalArgumentException e) {
            System.err.println("Validation failed for invalidJson: " + e.getMessage());
        }
    }
}

在这个例子中，我们首先从 classpath 中加载 JSON Schema，然后使用 SchemaLoader 将其转换为 Schema 对象。最后，我们使用 schema.validate(json) 方法来验证 JSON 数据。如果 JSON 数据不符合 Schema，会抛出 ValidationException 异常，我们可以捕获这个异常并进行处理。

3. 使用 JSON Schema 生成 Java 类

为了更好地利用 JSON Schema，我们可以使用工具根据 JSON Schema 自动生成 Java 类。这样可以确保 Java 对象与 JSON Schema 定义的结构完全一致，减少数据类型转换和字段映射的错误。

我们可以使用 jsonschema2pojo-maven-plugin 插件来生成 Java 类。首先，我们需要添加 Maven 依赖：

<plugin>
    <groupId>org.jsonschema2pojo</groupId>
    <artifactId>jsonschema2pojo-maven-plugin</artifactId>
    <version>1.2.1</version>
    <configuration>
        <sourceDirectory>${basedir}/src/main/resources/schema</sourceDirectory>
        <targetPackage>com.example.model</targetPackage>
        <outputDirectory>${basedir}/src/main/java</outputDirectory>
        <annotationStyle>jackson2</annotationStyle>
    </configuration>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
        </execution>
    </executions>
</plugin>

然后，将 JSON Schema 文件放在 src/main/resources/schema 目录下，运行 mvn generate-sources 命令即可生成 Java 类。生成的 Java 类会包含 JSON Schema 中定义的字段，并且会使用 Jackson 注解进行标注，方便 JSON 序列化和反序列化。

例如，根据上面定义的 User JSON Schema，可以生成如下 Java 类：

package com.example.model;

import java.util.List;
import com.fasterxml.jackson.annotation.JsonInclude;
import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.annotation.JsonPropertyOrder;

@JsonInclude(JsonInclude.Include.NON_NULL)
@JsonPropertyOrder({
    "id",
    "firstName",
    "lastName",
    "email",
    "age",
    "isActive",
    "roles",
    "address"
})
public class User {

    @JsonProperty("id")
    private Integer id;
    @JsonProperty("firstName")
    private String firstName;
    @JsonProperty("lastName")
    private String lastName;
    @JsonProperty("email")
    private String email;
    @JsonProperty("age")
    private Integer age;
    @JsonProperty("isActive")
    private Boolean isActive;
    @JsonProperty("roles")
    private List<String> roles = null;
    @JsonProperty("address")
    private Address address;

    @JsonProperty("id")
    public Integer getId() {
        return id;
    }

    @JsonProperty("id")
    public void setId(Integer id) {
        this.id = id;
    }

    @JsonProperty("firstName")
    public String getFirstName() {
        return firstName;
    }

    @JsonProperty("firstName")
    public void setFirstName(String firstName) {
        this.firstName = firstName;
    }

    @JsonProperty("lastName")
    public String getLastName() {
        return lastName;
    }

    @JsonProperty("lastName")
    public void setLastName(String lastName) {
        this.lastName = lastName;
    }

    @JsonProperty("email")
    public String getEmail() {
        return email;
    }

    @JsonProperty("email")
    public void setEmail(String email) {
        this.email = email;
    }

    @JsonProperty("age")
    public Integer getAge() {
        return age;
    }

    @JsonProperty("age")
    public void setAge(Integer age) {
        this.age = age;
    }

    @JsonProperty("isActive")
    public Boolean getIsActive() {
        return isActive;
    }

    @JsonProperty("isActive")
    public void setIsActive(Boolean isActive) {
        this.isActive = isActive;
    }

    @JsonProperty("roles")
    public List<String> getRoles() {
        return roles;
    }

    @JsonProperty("roles")
    public void setRoles(List<String> roles) {
        this.roles = roles;
    }

    @JsonProperty("address")
    public Address getAddress() {
        return address;
    }

    @JsonProperty("address")
    public void setAddress(Address address) {
        this.address = address;
    }

}

package com.example.model;

import com.fasterxml.jackson.annotation.JsonInclude;
import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.annotation.JsonPropertyOrder;

@JsonInclude(JsonInclude.Include.NON_NULL)
@JsonPropertyOrder({
    "street",
    "city",
    "zipCode"
})
public class Address {

    @JsonProperty("street")
    private String street;
    @JsonProperty("city")
    private String city;
    @JsonProperty("zipCode")
    private String zipCode;

    @JsonProperty("street")
    public String getStreet() {
        return street;
    }

    @JsonProperty("street")
    public void setStreet(String street) {
        this.street = street;
    }

    @JsonProperty("city")
    public String getCity() {
        return city;
    }

    @JsonProperty("city")
    public void setCity(String city) {
        this.city = city;
    }

    @JsonProperty("zipCode")
    public String getZipCode() {
        return zipCode;
    }

    @JsonProperty("zipCode")
    public void setZipCode(String zipCode) {
        this.zipCode = zipCode;
    }

}

4. 使用生成的 Java 类生成 JSON 数据

有了生成的 Java 类，我们可以使用 Jackson 库来生成 JSON 数据。

import com.example.model.User;
import com.example.model.Address;
import com.fasterxml.jackson.databind.ObjectMapper;

public class JsonGenerator {

    public static void main(String[] args) throws Exception {
        User user = new User();
        user.setId(123);
        user.setFirstName("John");
        user.setLastName("Doe");
        user.setEmail("[email protected]");
        user.setAge(30);
        user.setIsActive(true);

        Address address = new Address();
        address.setStreet("123 Main St");
        address.setCity("Anytown");
        address.setZipCode("12345");
        user.setAddress(address);

        ObjectMapper mapper = new ObjectMapper();
        String json = mapper.writeValueAsString(user);
        System.out.println(json);
    }
}

在这个例子中，我们首先创建了一个 User 对象，并设置了其字段的值。然后，我们使用 ObjectMapper 将 User 对象转换为 JSON 字符串。由于我们使用了根据 JSON Schema 生成的 Java 类，并且使用了 Jackson 注解，因此生成的 JSON 数据会完全符合 JSON Schema 定义的结构和类型。

5. 集成验证和生成流程

最后，我们可以将 JSON Schema 验证和 JSON 生成流程集成起来，确保生成的 JSON 数据始终符合 JSON Schema 的定义。

import com.example.model.User;
import com.example.model.Address;
import com.fasterxml.jackson.databind.ObjectMapper;
import org.everit.json.schema.Schema;
import org.everit.json.schema.ValidationException;
import org.everit.json.schema.loader.SchemaLoader;
import org.json.JSONObject;
import org.json.JSONTokener;

import java.io.InputStream;

public class IntegratedJsonWorkflow {

    private static final String SCHEMA_PATH = "/user-schema.json";

    public static String generateAndValidateJson(User user) {
        try {
            ObjectMapper mapper = new ObjectMapper();
            String jsonString = mapper.writeValueAsString(user);
            JSONObject jsonObject = new JSONObject(jsonString);

            validateJson(jsonObject); // Validate before returning

            return jsonString;

        } catch (Exception e) {
            System.err.println("Error generating or validating JSON: " + e.getMessage());
            throw new RuntimeException("Failed to generate and validate JSON", e);
        }
    }

    private static void validateJson(JSONObject json) {
        try (InputStream schemaStream = IntegratedJsonWorkflow.class.getResourceAsStream(SCHEMA_PATH)) {
            JSONObject rawSchema = new JSONObject(new JSONTokener(schemaStream));
            Schema schema = SchemaLoader.load(rawSchema);
            schema.validate(json);
            System.out.println("JSON data is valid.");
        } catch (ValidationException e) {
            System.err.println("JSON data is invalid:");
            e.getAllMessages().forEach(System.err::println);
            throw new IllegalArgumentException("Invalid JSON data", e);
        } catch (Exception e) {
            System.err.println("Error loading schema or validating JSON:");
            e.printStackTrace();
            throw new RuntimeException("Error during schema validation", e);
        }
    }

    public static void main(String[] args) {
        User user = new User();
        user.setId(123);
        user.setFirstName("John");
        user.setLastName("Doe");
        user.setEmail("[email protected]");
        user.setAge(30);
        user.setIsActive(true);

        Address address = new Address();
        address.setStreet("123 Main St");
        address.setCity("Anytown");
        address.setZipCode("12345");
        user.setAddress(address);

        try {
            String jsonOutput = generateAndValidateJson(user);
            System.out.println("Generated JSON: " + jsonOutput);
        } catch (RuntimeException e) {
            System.err.println("JSON generation and validation failed: " + e.getMessage());
        }
    }
}

在这个例子中，我们首先使用 ObjectMapper 将 User 对象转换为 JSON 字符串，然后使用 JSON Schema 验证 JSON 字符串。如果 JSON 字符串不符合 Schema，会抛出异常。

JSON Schema 的高级用法

除了上面介绍的基本用法之外，JSON Schema 还有很多高级用法，可以更灵活地描述 JSON 数据结构。

$ref： 可以使用 $ref 关键字来引用其他的 JSON Schema，实现 Schema 的复用。
oneOf、anyOf、allOf、not： 可以使用这些关键字来定义复杂的条件约束。
dependencies： 可以使用 dependencies 关键字来定义字段之间的依赖关系。
format： 可以使用 format 关键字来指定字段的格式，例如 email、date、uri 等。
自定义关键字： 可以自定义关键字来扩展 JSON Schema 的功能。

使用表格总结 JSON Schema 的常用关键字

关键字	描述	示例
`$schema`	指定 JSON Schema 的版本。	`"$schema": "http://json-schema.org/draft-07/schema#"`
`title`	Schema 的标题。	`"title": "User"`
`description`	Schema 的描述。	`"description": "A schema for a user object"`
`type`	指定 JSON 数据的类型，可以是 `object`、`array`、`string`、`number`、`integer`、`boolean` 或 `null`。	`"type": "object"`
`properties`	定义 JSON 对象的属性。	`"properties": { "id": { "type": "integer" }, "name": { "type": "string" } }`
`required`	指定 JSON 对象中必需的属性。	`"required": ["id", "name"]`
`items`	定义 JSON 数组中元素的类型。	`"items": { "type": "string" }`
`enum`	指定 JSON 数据的取值范围。	`"enum": ["admin", "user", "guest"]`
`minimum`	指定数值的最小值。	`"minimum": 0`
`maximum`	指定数值的最大值。	`"maximum": 100`
`pattern`	指定字符串的正则表达式。	`"pattern": "^\d{5}(?:-\d{4})?$"`
`format`	指定字符串的格式，例如 `email`、`date`、`uri` 等。	`"format": "email"`
`$ref`	引用其他的 JSON Schema。	`"$ref": "address-schema.json"`
`oneOf`	指定 JSON 数据必须符合多个 Schema 中的一个。	`"oneOf": [{ "type": "string" }, { "type": "integer" }]`
`anyOf`	指定 JSON 数据必须符合多个 Schema 中的至少一个。	`"anyOf": [{ "type": "string" }, { "type": "integer" }]`
`allOf`	指定 JSON 数据必须符合多个 Schema 中的所有。	`"allOf": [{ "type": "object", "properties": { "id": { "type": "integer" } } }, { "type": "object", "properties": { "name": { "type": "string" } } }]`
`not`	指定 JSON 数据不能符合某个 Schema。	`"not": { "type": "string" }`
`dependencies`	指定字段之间的依赖关系。	`"dependencies": { "credit_card": ["billing_address"] }`

总结：构建稳定的 JSON 生成流程

总而言之，通过定义 JSON Schema，利用 JSON Schema 验证数据，并根据 JSON Schema 生成 Java 类，我们可以构建一个稳定的 JSON 生成流程，减少数据类型转换和字段映射的错误，提高 JSON 数据的可靠性和兼容性。希望今天的分享对大家有所帮助！