适用于 Java 的 Azure JSON 共享库 - 版本 1.1.0

JsonSerializable

JsonSerializable 用于定义如何使用流式序列化对对象进行 JSON 序列化和反序列化，其中对象本身管理其处理方式的逻辑。 接口提供一个基于 toJson 实例的 API，用于处理将 对象写入 到 ， JsonWriter 以及一个静态 fromJson API，实现必须提供该 API 来定义如何通过从 JsonReader 读取来创建对象，如果未提供 UnsupportedOperationException 实现，则将引发 。

JsonToken

JsonToken 是一个基本枚举，指示 JSON 流中的当前状态。

JsonReader

JsonReader 提供基本、读取基元和装箱基元类型，以及读取数组、映射和对象以及用于读取 JSON 的 API 的便利性。 JsonReader 提供 是为了允许任何基础 JSON 分析程序（例如 Jackson 或 GSON）实现它，前提是实现通过此包的 test-jar () JsonReaderContractTests 提供的测试。

JsonReader 在调用 之前 nextToken 不会在 JSON 流中向前推进，这意味着 JsonReader.getInt ，可以无限期地调用 并返回相同的整数，而不会出错，直到 nextToken 推进 JSON 流向前。

JsonReader 允许在 JSON 类型之间进行类型转换，例如尝试将 JSON 字符串转换为数字，反之亦然;对于常用的非标准 JSON 值（例如 NaN 、、 INF -INF 、 Infinity 和 -Infinity ），则允许类型转换。

JsonReader 不获取 JSON 输入源的所有权，因此，如果使用 或 Reader 提供 InputStream JSON，则不会关闭任何资源。

JsonReader 的泛型 readUntyped API 跟踪所读取对象的嵌套深度。 如果嵌套超过 的阈值 1000 ， IllegalStateException 则会引发 以防止 StackOverflowError 。

JsonWriter

JsonWriter 提供基本、编写基元和装箱基元类型，以及编写数组、映射和对象以及用于编写 JSON 的 API 的便利性。 JsonWriter 提供 是为了允许任何基础 JSON 编写器（例如 Jackson 或 GSON）实现它，前提是实现通过包的 test-jar ( JsonWriterContractTests ) 提供的测试。

JsonWriter 允许使用 或 写入常用的非标准 JSON 值，例如 NaN 、 INF 、 -INF Infinity 、 和 -Infinity 。 writeRawValue writeNumberField

JsonWriter 当写入为字段 writeNumberField writeBinaryField writeBooleanField 、 Boolean 、 Number 、 或 String 时，如果需要写入空 byte[] 字段，则不会写入 null 、、 或 writeStringField 值，请使用 。 writeNullField

JsonWriter 必须定期刷新，以确保写入到它的内容刷新到基础容器类型，通常为 OutputStream 或 Writer 。 未能刷新可能会导致内容丢失。 关闭 会 JsonWriter 刷新内容，因此最佳做法 JsonWriter 是在 try-with-resources 块中使用 ，在该 JsonWriter 块中，使用完成后会关闭 。

JsonWriter 不获取 JSON 输出源的所有权，因此，如果 JSON 正在写入 或 Writer ， OutputSteam 则不会关闭任何资源。

JSON 状态管理

若要确保正在写入的 JSON 有效，请使用 JsonWriteContext 维护 JSON 的状态， JsonWriter 并在每次尝试写入时都会验证操作是否有效。 的 JsonWriter 实现必须确保正确跟踪状态，例如，当未写入任何内容时，JSON 状态必须为 ROOT ，并且 ROOT 不允许写入 JSON 字段名称。

JsonProvider

JsonProvider 是一个服务提供程序接口，允许 JsonReader 使用类路径上的实现创建 和 JsonWriter 。 JsonProvider 如果类路径上找不到实现，还可以创建此包提供的默认实现。

JsonOptions

JsonOptions 包含 的所有 实现都必须遵循 的配置 JsonReader JsonWriter 。 目前，只有一种配置用于确定 JSON 读取和写入中是否支持非数字数字 NaN 、、 INF Infinity -INF 、、 和 -Infinity ，并且默认设置 true 为 ，即允许非数字数字。

提供 SPI 实现

JsonReader 和 JsonWriter 是 和 JsonProviders 用于 JsonProvider 启用从类路径加载实现的服务提供程序接口。 Azure JSON 包提供了一个默认实现，如果在类路径上找不到该实现，将使用该实现。 若要提供自定义实现，请在自己的包中实现 JsonReader 、 JsonWriter 和 JsonProvider ，并指示该包提供 的 JsonProvider 实例。 若要确保实现正确，请包含 test Azure JSON 的作用域依赖项，并扩展 JsonReaderContractTests 、 JsonWriterContractTests 和 JsonProviderContractTests 。 这些测试概述了 、 JsonWriter 和 JsonProvider 设置 JsonReader 的所有基本协定要求，并测试了一些复杂的方案，以提供对任何实现的验证。

有关如何使用 Azure JSON 的深入示例，请查看 示例自述 文件。

如果遇到任何 bug，请通过 GitHub 问题提交问题 ，或查看 适用于 Azure Java SDK 的 StackOverflow 。

开始使用 使用 Azure Core 生成的 Azure 库。

有关参与此存储库的详细信息，请参阅 参与指南 。