---
url: /zh/reference/json-values.md
description: Wow 的 JSON 如何写出状态、命令和事件所持有的每个平台值类，Manifest 的 schema 给它的类型和格式，以及它另外读取什么、拒绝什么。
---

# JSON 中的值

Wow 的 JSON（`WowJson`）写出并读取服务的状态、命令和事件：在事件存储中、在快照中、在 Kafka 上和经由 HTTP。本页列出它写成标量的每个平台值类，以及 Manifest 的 schema 为这个类给出的 JSON 类型和格式，和 Wow 的 JSON 为它写出的文本。

* 这些类是 JVM 的类：Kotlin 的 `Int` 是 `int`，可空或作为类型实参时是 `Integer`；`ByteArray` 是 `byte[]`。一行只匹配它的类本身，不匹配子类。
* JavaScript 的 `number` 只能精确持有至多 2^53 − 1（`9007199254740991`）的整数：客户端把更大的 `long` 读作 `bigint`。
* 枚举按名字写出，与其 schema 的 `enum` 列出的一样：`Month` 写作 `"JANUARY"`。
* 属性若持有另一个写成标量的平台类（`Charset`、`Path`、`AtomicLong`），构建会停下，除非声明了它的 schema（[Manifest](../guide/manifest#a-type-written-by-a-custom-serializer)）。
* 有一个测试让每一行与代码一致：它的类、JSON 类型和格式与 Manifest 的描述一致，它列出的每个值与 Wow 的 JSON 写出的一致。

写出的形式是 Wow 承诺的，也是不是 Wow 的客户端应当写出的。最后一列说明 Wow 的 JSON 另外读取什么、拒绝什么，并由测试逐一保证：

* JSON 种类与其类不同的值会被拒绝；`java.time` 值、`URL`、`Currency` 或 `Character` 的空字符串也会被拒绝（Jackson 会把它读作 `null`）。命令体中含有这样的值时，命令以 `wow.command.malformed` 被拒绝，并带一条违规：属性在命令体中的路径（`items[0].quantity`）和它的代码 `wrong-kind`、`out-of-range`、`invalid-format` 或 `not-in-enumeration`，消息写明期望的和给出的种类。
* Wow 1.x 到 6.x 运行在 Jackson 2 上，它把日期、时间和时长写成数字和数组。这些形式都按各自所在行的说明读取，因此从这些版本延续下来的存储可以读取；这些类的其他数字或数组会被拒绝。
* `kotlin.time.Duration` 拒绝数字：它是 ISO-8601 文本。
* `Month` 读取它的名字或从 1 开始的序号，拒绝 `0`。

| 类 | JSON | 写出 | 另外读取的，以及拒绝的 |
| --- | --- | --- | --- |
| `boolean`、`Boolean` | `boolean` | `true`、`false` | 拒绝数字 `1`、字符串 `"true"`，对 `boolean` 还拒绝 `null`。 |
| `int`、`Integer` | `integer`、`int32` | `1`、`2147483647`、`-2147483648` | 拒绝浮点数 `1.5`、`1e2` 或 `1.0`，字符串 `"7"`，以及超出范围的数 `2147483648`。 |
| `short`、`Short` | `integer`、`int32` | `1`、`-32768`、`32767` | 拒绝浮点数或字符串（与 `int` 相同），以及超出范围的数 `40000`。 |
| `byte`、`Byte` | `integer`、`int32` | `1`、`-128`、`127` | 拒绝超出范围的数 `200` 或 `-129`：单凭 Jackson 会把 200 回绕为 -56。 |
| `Year` | `integer`、`int32` | `2026`、`0`、`-1`、`12026` | 拒绝字符串 `"2026"`，以及超出 `int` 的数 `3000000000`。 |
| `long`、`Long` | `integer`、`int64` | `1`、`9223372036854775807` | 拒绝浮点数或字符串（与 `int` 相同），以及超出范围的数 `9223372036854775808`。 |
| `BigInteger` | `integer`、`bigint` | `123456789012345678901234567890`，任意长度 | 拒绝浮点数 `1.5` 或 `1e3`，以及字符串 `"12"`。 |
| `float`、`Float` | `number`、`float` | `1.5`、`0.1`、`3.4028235E38`、`-0.0`；非数和无穷写作字符串，`"NaN"`、`"Infinity"`、`"-Infinity"` | 读取这三个字符串 `"NaN"`、`"Infinity"` 和 `"-Infinity"`，以及超出范围的数，`1e39` 读作 `"Infinity"`，按 IEEE 754 的舍入。拒绝其他字符串 `"1.5"`。 |
| `double`、`Double` | `number` | `0.1`、`1.0`、`1.0E300`、`-0.0`；非数和无穷写作字符串，`"NaN"`、`"Infinity"`、`"-Infinity"` | 读取这三个字符串 `"NaN"`、`"Infinity"` 和 `"-Infinity"`，以及超出范围的数，`1e400` 读作 `"Infinity"`，按 IEEE 754 的舍入。拒绝其他字符串 `"1.5"`。 |
| `BigDecimal` | `number`、`decimal` | 它的数字与标度，保留末尾的零，`2.50`、`0.000001`；负标度或很小的值写成指数形式，`1E+3`、`1E-7` | 读取任意指数，`1e400` 读作 `1E+400`，不会溢出。拒绝字符串 `"2.50"`。 |
| `Instant` | `string`、`date-time` | UTC，`"2026-01-02T03:04:05Z"`；小数部分按需写到纳秒，`"2026-01-02T03:04:05.123456789Z"`；9999 之后的年份带符号，`"+12026-01-01T00:00:00Z"`，1 之前的，`"-0001-01-01T00:00:00Z"` | 读取偏移，`"2026-01-02T03:04:05+08:00"` 读作 `"2026-01-01T19:04:05Z"`，也读取小写，`"2026-01-02t03:04:05z"` 读作 `"2026-01-02T03:04:05Z"`。读取纪元秒的小数，`1767323045.123456789` 读作 `"2026-01-02T03:04:05.123456789Z"`，即 Wow 1.x 到 6.x 写出的形式；也读取整数，`1767323045` 读作 `"2026-01-02T03:04:05Z"`，这些版本在默认配置下都不曾写出它。拒绝数组 `[2026,1,2]`、没有偏移的时间 `"2026-01-02T03:04:05"` 和只有日期的文本 `"2026-01-02"`。 |
| `OffsetDateTime` | `string`、`date-time` | 保留偏移，`"2026-01-02T03:04:05+08:00"` | 读取时保留写入时的偏移，`"2026-01-02T03:04:05+08:00"` 读作 `"2026-01-02T03:04:05+08:00"`。读取纪元秒的小数，`1767294245.5` 读作 `"2026-01-01T19:04:05.5Z"`，即 Wow 1.x 到 6.x 写出的形式：这样存储的值不带偏移，读作 UTC。拒绝数组 `[2026]` 和没有偏移的时间 `"2026-01-02T03:04:05"`。 |
| `ZonedDateTime` | `string`、`date-time` | 写出偏移，不写时区：Asia/Shanghai 2026 年 1 月 2 日 03:04:05 写作 `"2026-01-02T03:04:05+08:00"` | 读取时保留它的偏移，为固定偏移，因为不写出地区：`"2026-01-02T03:04:05+08:00[Asia/Shanghai]"` 读作 `"2026-01-02T03:04:05+08:00"`。读取纪元秒的小数，`1767294245.000000000` 读作 `"2026-01-01T19:04:05Z"`，即 Wow 1.x 到 6.x 写出的形式：这样存储的值不带偏移或时区，读作 UTC。拒绝数组 `[2026]`。 |
| `Date` | `string`、`date-time` | UTC，总是写出毫秒，`"2026-01-02T03:04:05.123Z"` | 读取偏移，`"2026-01-02T03:04:05.123+08:00"` 读作 `"2026-01-01T19:04:05.123Z"`，以及纪元毫秒，`1767323045123` 读作 `"2026-01-02T03:04:05.123Z"`，即 Wow 1.x 到 6.x 写出的形式。拒绝只有日期的文本 `"2026-01-02"`、毫秒的小数 `1767323045.5`、数组 `[1]` 和其他文本 `"yesterday"`。 |
| `Calendar` | `string`、`date-time` | 与 Date 相同，为 UTC：不写出它的时区，`"2026-01-02T03:04:05.123Z"` | 读取纪元毫秒，`1767323045123` 读作 `"2026-01-02T03:04:05.123Z"`，即 Wow 1.x 到 6.x 写出的形式，为 UTC，与 `Date` 相同。拒绝只有日期的文本 `"2026-01-02"` 和毫秒的小数 `1767323045.5`。 |
| `LocalDate` | `string`、`date` | `"2026-01-02"`；9999 之后的年份带符号，`"+12026-01-01"`；负年份，`"-0001-01-01"` | 读取 `[2026,1,2]`，读作 `"2026-01-02"`，即 Wow 1.x 到 6.x 写出的形式。拒绝日期时间 `"2026-01-02T03:04:05"`、数字 `20455`、空字符串 `""`、不带符号的 9999 之后的年份 `"12026-01-01"`、`"2026-1-2"` 和不存在的日期 `"2026-02-30"`。 |
| `LocalTime` | `string`、`time` | 总是写出秒，`"03:04:05"`、`"03:04:00"`；小数部分按需，`"03:04:05.12"` | 读取 `[3,4,5,123000000]`，读作 `"03:04:05.123"`，即 Wow 1.x 到 6.x 写出的形式。拒绝数字 `3600`、`"3:04"` 和偏移 `"03:04:05+08:00"`。 |
| `OffsetTime` | `string`、`time` | `"03:04:05+08:00"`；秒为零时省略，`"03:04Z"` | 读取 `[3,4,5,"+08:00"]`，读作 `"03:04:05+08:00"`，即 Wow 1.x 到 6.x 写出的形式。拒绝数字 `3600` 和没有偏移的时间 `"03:04:05"`。 |
| `Duration` | `string`、`duration` | ISO-8601，`"PT1H30M"`、`"PT0S"`；天写作小时，`"PT48H"`；负值，`"PT-1.5S"`；精确到纳秒，`"PT0.000000001S"` | 读取天，`"P1D"` 读作 `"PT24H"`，小写，`"pt1h"` 读作 `"PT1H"`，以及秒的小数，`5400.000000000` 读作 `"PT1H30M"`，即 Wow 1.x 到 6.x 写出的形式，或整数秒，`5400` 读作 `"PT1H30M"`。拒绝数组 `[1]`、月和年 `"P1M"` 以及任何其他文本 `"90m"`。 |
| `Period` | `string`、`duration` | ISO-8601，`"P1Y2M3D"`、`"P0D"`；周写作天，`"P14D"`；负值，`"P-1M"` | 读取周，`"P2W"` 读作 `"P14D"`。拒绝时间部分 `"PT1H"`、数字 `1` 和数组 `[1]`。 |
| `kotlin.time.Duration` | `string`、`duration` | 与 Duration 相同，`"PT1H30M"`；负值，`"PT-1H-30M"`；无穷大，`"PT2562047788015215H30M7S"` | 读取天，`"P1D"` 读作 `"PT24H"`，以及无穷时长的文本或更长的文本，`"PT9999999999999999H"` 读作 `"PT2562047788015215H30M7S"`。拒绝 Kotlin 自己的形式 `"1h 30m"`、月 `"P1M"` 和数字 `5`。 |
| `UUID` | `string`、`uuid` | 小写，36 个字符，`"00000000-0000-0001-0000-000000000002"` | 读取大写，`"00000000-0000-0001-0000-00000000000A"` 读作 `"00000000-0000-0001-0000-00000000000a"`。拒绝任何其他形式 `"x"`。 |
| `URI` | `string`、`uri` | 原样，已编码，`"https://example.com/a%20b"`、`"urn:isbn:123"`、`"/relative"` | 读取空 URI `""`。拒绝非法字符 `"a b"`。 |
| `URL` | `string`、`uri` | `"https://example.com/a"` | 拒绝空字符串 `""`（单凭 Jackson 会把它读作 null）和没有协议的文本 `"example.com"`。 |
| `byte[]` | `string`、`byte` | 带填充的 Base64，`"AQID"`、`"//79/A=="`；空数组，`""` | 拒绝数字数组 `[1,2,3]`、缺少填充 `"AQI"` 和 URL 安全字母表 `"_-8="`。 |
| `String` | `string` | 原样，按 JSON 的方式转义，`"\u0000"` | 拒绝数字 `1`、布尔值 `true` 和对象 `{}`。 |
| `char`、`Character` | `string` | 一个字符，`"c"` | 拒绝数字 `65`、空字符串 `""` 和多于一个字符 `"ab"`。 |
| `LocalDateTime` | `string` | 总是写出秒，`"2026-01-02T03:04:05"`；9999 之后的年份带符号，`"+12026-01-01T00:00:00"` | 读取 `[2026,1,2,3,4,5,123000000]`，读作 `"2026-01-02T03:04:05.123"`，即 Wow 1.x 到 6.x 写出的形式。拒绝末尾的 `Z` `"2026-01-02T03:04:05Z"`、偏移 `"2026-01-02T03:04:05+08:00"`、数字 `1767323045` 和用空格代替 `T` 的 `"2026-01-02 03:04:05"`。 |
| `YearMonth` | `string` | `"2026-01"`、`"0005-01"`；9999 之后的年份不带符号，`"12026-01"`；负年份，`"-0001-01"` | 读取位数较少的年份，`"5-01"` 读作 `"0005-01"`，以及 `[2026,1]`，读作 `"2026-01"`，即 Wow 1.x 到 6.x 写出的形式。拒绝数字 `202601`、加号 `"+12026-01"`、`"2026-1"` 和 13 月 `"2026-13"`。 |
| `MonthDay` | `string` | `"--01-02"`、`"--02-29"` | 拒绝数组 `[1,2]`（没有版本写出过它）、`"01-02"` 和不存在的日期 `"--02-30"`。 |
| `ZoneId` | `string` | `"Asia/Shanghai"`、`"UTC"`、`"Z"`、`"GMT+08:00"` | 读取偏移 `"+08:00"`。拒绝未知地区 `"Nowhere/City"` 和大小写不同的地区 `"asia/shanghai"`。 |
| `ZoneOffset` | `string` | `"+08:00"`、`"+05:30"`、`"-18:00"`；零写作 `"Z"`；秒按需，`"+01:02:03"` | 读取 `"+8"`，读作 `"+08:00"`，以及 `"+00:00"`，读作 `"Z"`。拒绝超出 ±18:00 的偏移 `"+18:30"` 和地区 `"UTC"`。 |
| `TimeZone` | `string` | 它的 ID，`"UTC"`、`"Asia/Shanghai"`、`"GMT+08:00"` | 读取偏移，`"+08:00"` 读作 `"GMT+08:00"`，以及 Java 认识的短 ID `"PST"`。拒绝未知 ID `"Nowhere/City"` 和数字 `1`。 |
| `Locale` | `string` | BCP 47 标签，`"zh-CN"`、`"zh-Hans-CN"`、`"en-US-POSIX"`；根语言环境写作 `""` | 读取 Java 的形式，`"zh_CN"` 读作 `"zh-CN"`，也读取任何其他文本：不是标签的文本，`"not a tag!"` 读作 `"und"`，即未确定的语言。 |
| `Currency` | `string` | ISO 4217 代码，`"CNY"` | 拒绝空字符串 `""`（单凭 Jackson 会把它读作 null）、未知代码 `"XYZ"` 和小写代码 `"cny"`。 |
