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)。 - 有一个测试让每一行与代码一致:它的类、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"。 |