JavaScript 对象表示法 (JSON)¶ ↑

JSON 是一种轻量级的数据交换格式。

一个 JSON 值是以下之一

• 双引号文本："foo"。

• 数字：1，1.0，2.0e2。

• 布尔值：true，false。

• 空值：null。

• 数组：值的有序列表，用方括号括起来

  ["foo", 1, 1.0, 2.0e2, true, false, null]
  

• 对象：名称/值对的集合，用大括号括起来；每个名称都是双引号文本；值可以是任何 JSON 值

  {"a": "foo", "b": 1, "c": 1.0, "d": 2.0e2, "e": true, "f": false, "g": null}
  

JSON 数组或对象可以包含嵌套的数组、对象和标量到任何深度

{"foo": {"bar": 1, "baz": 2}, "bat": [0, 1, 2]}
[{"foo": 0, "bar": 1}, ["baz", 2]]

使用模块 JSON¶ ↑

要在您的代码中使用模块 JSON，请首先

require 'json'

此处的所有示例都假设已完成此操作。

解析 JSON¶ ↑

您可以使用以下两种方法之一解析包含 JSON 数据的字符串

• JSON.parse(source, opts)

• JSON.parse!(source, opts)

其中

• source 是一个 Ruby 对象。

• opts 是一个哈希对象，其中包含控制允许的输入和输出格式的选项。

这两种方法的区别在于 JSON.parse! 省略了一些检查，对于某些 source 数据可能不安全；仅将其用于来自可信任来源的数据。对于不太可信任的来源，请使用更安全的方法 JSON.parse。

解析 JSON 数组¶ ↑

当 source 是 JSON 数组时，JSON.parse 默认返回一个 Ruby 数组

json = '["foo", 1, 1.0, 2.0e2, true, false, null]'
ruby = JSON.parse(json)
ruby # => ["foo", 1, 1.0, 200.0, true, false, nil]
ruby.class # => Array

JSON 数组可能包含嵌套的数组、对象和标量到任何深度

json = '[{"foo": 0, "bar": 1}, ["baz", 2]]'
JSON.parse(json) # => [{"foo"=>0, "bar"=>1}, ["baz", 2]]

解析 JSON 对象¶ ↑

当 source 是 JSON 对象时，JSON.parse 默认返回一个 Ruby 哈希

json = '{"a": "foo", "b": 1, "c": 1.0, "d": 2.0e2, "e": true, "f": false, "g": null}'
ruby = JSON.parse(json)
ruby # => {"a"=>"foo", "b"=>1, "c"=>1.0, "d"=>200.0, "e"=>true, "f"=>false, "g"=>nil}
ruby.class # => Hash

JSON 对象可能包含嵌套的数组、对象和标量到任何深度

json = '{"foo": {"bar": 1, "baz": 2}, "bat": [0, 1, 2]}'
JSON.parse(json) # => {"foo"=>{"bar"=>1, "baz"=>2}, "bat"=>[0, 1, 2]}

解析 JSON 标量¶ ↑

当 source 是 JSON 标量（不是数组或对象）时，JSON.parse 返回一个 Ruby 标量。

字符串

ruby = JSON.parse('"foo"')
ruby # => 'foo'
ruby.class # => String

整数

ruby = JSON.parse('1')
ruby # => 1
ruby.class # => Integer

浮点数

ruby = JSON.parse('1.0')
ruby # => 1.0
ruby.class # => Float
ruby = JSON.parse('2.0e2')
ruby # => 200
ruby.class # => Float

布尔值

ruby = JSON.parse('true')
ruby # => true
ruby.class # => TrueClass
ruby = JSON.parse('false')
ruby # => false
ruby.class # => FalseClass

空值

ruby = JSON.parse('null')
ruby # => nil
ruby.class # => NilClass

解析选项¶ ↑

输入选项¶ ↑

选项 max_nesting (整数) 指定允许的最大嵌套深度；默认为 100；指定 false 以禁用深度检查。

使用默认值，false

source = '[0, [1, [2, [3]]]]'
ruby = JSON.parse(source)
ruby # => [0, [1, [2, [3]]]]

太深

# Raises JSON::NestingError (nesting of 2 is too deep):
JSON.parse(source, {max_nesting: 1})

错误值

# Raises TypeError (wrong argument type Symbol (expected Fixnum)):
JSON.parse(source, {max_nesting: :foo})

选项 allow_nan (布尔值) 指定是否允许 source 中出现 NaN，Infinity 和 MinusInfinity；默认为 false。

使用默认值，false

# Raises JSON::ParserError (225: unexpected token at '[NaN]'):
JSON.parse('[NaN]')
# Raises JSON::ParserError (232: unexpected token at '[Infinity]'):
JSON.parse('[Infinity]')
# Raises JSON::ParserError (248: unexpected token at '[-Infinity]'):
JSON.parse('[-Infinity]')

允许

source = '[NaN, Infinity, -Infinity]'
ruby = JSON.parse(source, {allow_nan: true})
ruby # => [NaN, Infinity, -Infinity]

输出选项¶ ↑

选项 symbolize_names (布尔值) 指定返回的哈希键是否应为符号；默认为 false （使用字符串）。

使用默认值，false

source = '{"a": "foo", "b": 1.0, "c": true, "d": false, "e": null}'
ruby = JSON.parse(source)
ruby # => {"a"=>"foo", "b"=>1.0, "c"=>true, "d"=>false, "e"=>nil}

使用符号

ruby = JSON.parse(source, {symbolize_names: true})
ruby # => {:a=>"foo", :b=>1.0, :c=>true, :d=>false, :e=>nil}

选项 object_class (类) 指定要用于每个 JSON 对象的 Ruby 类；默认为哈希。

使用默认值，哈希

source = '{"a": "foo", "b": 1.0, "c": true, "d": false, "e": null}'
ruby = JSON.parse(source)
ruby.class # => Hash

使用类 OpenStruct

ruby = JSON.parse(source, {object_class: OpenStruct})
ruby # => #<OpenStruct a="foo", b=1.0, c=true, d=false, e=nil>

选项 array_class (类) 指定要用于每个 JSON 数组的 Ruby 类；默认为数组。

使用默认值，数组

source = '["foo", 1.0, true, false, null]'
ruby = JSON.parse(source)
ruby.class # => Array

使用类 Set

ruby = JSON.parse(source, {array_class: Set})
ruby # => #<Set: {"foo", 1.0, true, false, nil}>

选项 create_additions (布尔值) 指定是否在解析中使用 JSON 扩展。 请参阅 JSON 扩展。

生成 JSON¶ ↑

要生成包含 JSON 数据的 Ruby 字符串，请使用方法 JSON.generate(source, opts)，其中

• source 是一个 Ruby 对象。

• opts 是一个哈希对象，其中包含控制允许的输入和输出格式的选项。

从数组生成 JSON¶ ↑

当 source 是 Ruby 数组时，JSON.generate 返回一个包含 JSON 数组的字符串

ruby = [0, 's', :foo]
json = JSON.generate(ruby)
json # => '[0,"s","foo"]'

Ruby 数组可以包含嵌套的数组、哈希和标量到任何深度

ruby = [0, [1, 2], {foo: 3, bar: 4}]
json = JSON.generate(ruby)
json # => '[0,[1,2],{"foo":3,"bar":4}]'

从哈希生成 JSON¶ ↑

当 source 是 Ruby 哈希时，JSON.generate 返回一个包含 JSON 对象的字符串

ruby = {foo: 0, bar: 's', baz: :bat}
json = JSON.generate(ruby)
json # => '{"foo":0,"bar":"s","baz":"bat"}'

Ruby 哈希可以包含嵌套的数组、哈希和标量到任何深度

ruby = {foo: [0, 1], bar: {baz: 2, bat: 3}, bam: :bad}
json = JSON.generate(ruby)
json # => '{"foo":[0,1],"bar":{"baz":2,"bat":3},"bam":"bad"}'

从其他对象生成 JSON¶ ↑

当 source 既不是数组也不是哈希时，生成的 JSON 数据取决于 source 的类。

当 source 是 Ruby 整数或浮点数时，JSON.generate 返回一个包含 JSON 数字的字符串

JSON.generate(42) # => '42'
JSON.generate(0.42) # => '0.42'

当 source 是 Ruby 字符串时，JSON.generate 返回一个包含 JSON 字符串（带有双引号）的字符串

JSON.generate('A string') # => '"A string"'

当 source 是 true，false 或 nil 时，JSON.generate 返回一个包含相应 JSON 令牌的字符串

JSON.generate(true) # => 'true'
JSON.generate(false) # => 'false'
JSON.generate(nil) # => 'null'

当 source 不是上述任何一种时，JSON.generate 返回一个包含 source 的 JSON 字符串表示形式的字符串

JSON.generate(:foo) # => '"foo"'
JSON.generate(Complex(0, 0)) # => '"0+0i"'
JSON.generate(Dir.new('.')) # => '"#<Dir>"'

生成选项¶ ↑

输入选项¶ ↑

选项 allow_nan (布尔值) 指定是否可以生成 NaN，Infinity 和 -Infinity；默认为 false。

使用默认值，false

# Raises JSON::GeneratorError (920: NaN not allowed in JSON):
JSON.generate(JSON::NaN)
# Raises JSON::GeneratorError (917: Infinity not allowed in JSON):
JSON.generate(JSON::Infinity)
# Raises JSON::GeneratorError (917: -Infinity not allowed in JSON):
JSON.generate(JSON::MinusInfinity)

允许

ruby = [Float::NaN, Float::Infinity, Float::MinusInfinity]
JSON.generate(ruby, allow_nan: true) # => '[NaN,Infinity,-Infinity]'

选项 max_nesting (整数) 指定 obj 中的最大嵌套深度；默认为 100。

使用默认值，100

obj = [[[[[[0]]]]]]
JSON.generate(obj) # => '[[[[[[0]]]]]]'

太深

# Raises JSON::NestingError (nesting of 2 is too deep):
JSON.generate(obj, max_nesting: 2)

转义选项¶ ↑

选项 script_safe (布尔值) 指定是否应转义 '\u2028'，'\u2029' 和 '/'，以使 JSON 对象在脚本标记中安全地插入。

选项 ascii_only (布尔值) 指定是否应转义 ASCII 范围之外的所有字符。

输出选项¶ ↑

默认格式化选项生成最紧凑的 JSON 数据，全部在一行上，没有空格。

您可以使用这些格式化选项来生成更开放格式的 JSON 数据，使用空格。 另请参阅 JSON.pretty_generate。

• 选项 array_nl (字符串) 指定要在每个 JSON 数组后插入的字符串（通常是换行符）；默认为空字符串，''。

• 选项 object_nl (字符串) 指定要在每个 JSON 对象后插入的字符串（通常是换行符）；默认为空字符串，''。

• 选项 indent (字符串) 指定要用于缩进的字符串（通常是空格）；默认为空字符串，''；默认为空字符串，''；除非选项 array_nl 或 object_nl 指定换行符，否则不起作用。

• 选项 space (字符串) 指定要在每个 JSON 对象对中的冒号后插入的字符串（通常是空格）；默认为空字符串，''。

• 选项 space_before (字符串) 指定要在每个 JSON 对象对中的冒号前插入的字符串（通常是空格）；默认为空字符串，''。

在此示例中，obj 首先用于生成最短的 JSON 数据（无空格），然后再次使用指定的所有格式化选项

obj = {foo: [:bar, :baz], bat: {bam: 0, bad: 1}}
json = JSON.generate(obj)
puts 'Compact:', json
opts = {
  array_nl: "\n",
  object_nl: "\n",
  indent: '  ',
  space_before: ' ',
  space: ' '
}
puts 'Open:', JSON.generate(obj, opts)

输出

Compact:
{"foo":["bar","baz"],"bat":{"bam":0,"bad":1}}
Open:
{
  "foo" : [
    "bar",
    "baz"
],
  "bat" : {
    "bam" : 0,
    "bad" : 1
  }
}

JSON 扩展¶ ↑

当您将非字符串对象从 Ruby “往返”到 JSON 并返回时，您将获得一个新的字符串，而不是您开始时的对象

ruby0 = Range.new(0, 2)
json = JSON.generate(ruby0)
json # => '0..2"'
ruby1 = JSON.parse(json)
ruby1 # => '0..2'
ruby1.class # => String

您可以使用 JSON _扩展_ 来保留原始对象。 扩展是 ruby 类的扩展，因此

• JSON.generate 在 JSON 字符串中存储更多信息。

• JSON.parse，使用选项 create_additions 调用，使用该信息来创建正确的 Ruby 对象。

此示例显示了将 Range 生成到 JSON 中并解析回 Ruby，无论是否使用 Range 的扩展

ruby = Range.new(0, 2)
# This passage does not use the addition for Range.
json0 = JSON.generate(ruby)
ruby0 = JSON.parse(json0)
# This passage uses the addition for Range.
require 'json/add/range'
json1 = JSON.generate(ruby)
ruby1 = JSON.parse(json1, create_additions: true)
# Make a nice display.
display = <<~EOT
  Generated JSON:
    Without addition:  #{json0} (#{json0.class})
    With addition:     #{json1} (#{json1.class})
  Parsed JSON:
    Without addition:  #{ruby0.inspect} (#{ruby0.class})
    With addition:     #{ruby1.inspect} (#{ruby1.class})
EOT
puts display

此输出显示了不同的结果

Generated JSON:
  Without addition:  "0..2" (String)
  With addition:     {"json_class":"Range","a":[0,2,false]} (String)
Parsed JSON:
  Without addition:  "0..2" (String)
  With addition:     0..2 (Range)

JSON 模块包含某些类的扩展。 您还可以制作自定义扩展。 请参阅 自定义 JSON 扩展。

内置扩展¶ ↑

JSON 模块包含某些类的扩展。 要使用扩展，请 require 其源

• BigDecimal：require 'json/add/bigdecimal'

• Complex：require 'json/add/complex'

• Date：require 'json/add/date'

• DateTime：require 'json/add/date_time'

• Exception：require 'json/add/exception'

• OpenStruct：require 'json/add/ostruct'

• Range：require 'json/add/range'

• Rational：require 'json/add/rational'

• Regexp：require 'json/add/regexp'

• Set：require 'json/add/set'

• Struct：require 'json/add/struct'

• Symbol：require 'json/add/symbol'

• Time：require 'json/add/time'

为了减少标点符号的混乱，以下示例通过 puts 而不是通常的 inspect 显示生成的 JSON，

BigDecimal

require 'json/add/bigdecimal'
ruby0 = BigDecimal(0) # 0.0
json = JSON.generate(ruby0) # {"json_class":"BigDecimal","b":"27:0.0"}
ruby1 = JSON.parse(json, create_additions: true) # 0.0
ruby1.class # => BigDecimal

Complex

require 'json/add/complex'
ruby0 = Complex(1+0i) # 1+0i
json = JSON.generate(ruby0) # {"json_class":"Complex","r":1,"i":0}
ruby1 = JSON.parse(json, create_additions: true) # 1+0i
ruby1.class # Complex

Date

require 'json/add/date'
ruby0 = Date.today # 2020-05-02
json = JSON.generate(ruby0) # {"json_class":"Date","y":2020,"m":5,"d":2,"sg":2299161.0}
ruby1 = JSON.parse(json, create_additions: true) # 2020-05-02
ruby1.class # Date

DateTime

require 'json/add/date_time'
ruby0 = DateTime.now # 2020-05-02T10:38:13-05:00
json = JSON.generate(ruby0) # {"json_class":"DateTime","y":2020,"m":5,"d":2,"H":10,"M":38,"S":13,"of":"-5/24","sg":2299161.0}
ruby1 = JSON.parse(json, create_additions: true) # 2020-05-02T10:38:13-05:00
ruby1.class # DateTime

Exception（及其子类，包括 RuntimeError）

require 'json/add/exception'
ruby0 = Exception.new('A message') # A message
json = JSON.generate(ruby0) # {"json_class":"Exception","m":"A message","b":null}
ruby1 = JSON.parse(json, create_additions: true) # A message
ruby1.class # Exception
ruby0 = RuntimeError.new('Another message') # Another message
json = JSON.generate(ruby0) # {"json_class":"RuntimeError","m":"Another message","b":null}
ruby1 = JSON.parse(json, create_additions: true) # Another message
ruby1.class # RuntimeError

OpenStruct

require 'json/add/ostruct'
ruby0 = OpenStruct.new(name: 'Matz', language: 'Ruby') # #<OpenStruct name="Matz", language="Ruby">
json = JSON.generate(ruby0) # {"json_class":"OpenStruct","t":{"name":"Matz","language":"Ruby"}}
ruby1 = JSON.parse(json, create_additions: true) # #<OpenStruct name="Matz", language="Ruby">
ruby1.class # OpenStruct

Range

require 'json/add/range'
ruby0 = Range.new(0, 2) # 0..2
json = JSON.generate(ruby0) # {"json_class":"Range","a":[0,2,false]}
ruby1 = JSON.parse(json, create_additions: true) # 0..2
ruby1.class # Range

Rational

require 'json/add/rational'
ruby0 = Rational(1, 3) # 1/3
json = JSON.generate(ruby0) # {"json_class":"Rational","n":1,"d":3}
ruby1 = JSON.parse(json, create_additions: true) # 1/3
ruby1.class # Rational

Regexp

require 'json/add/regexp'
ruby0 = Regexp.new('foo') # (?-mix:foo)
json = JSON.generate(ruby0) # {"json_class":"Regexp","o":0,"s":"foo"}
ruby1 = JSON.parse(json, create_additions: true) # (?-mix:foo)
ruby1.class # Regexp

Set

require 'json/add/set'
ruby0 = Set.new([0, 1, 2]) # #<Set: {0, 1, 2}>
json = JSON.generate(ruby0) # {"json_class":"Set","a":[0,1,2]}
ruby1 = JSON.parse(json, create_additions: true) # #<Set: {0, 1, 2}>
ruby1.class # Set

Struct

require 'json/add/struct'
Customer = Struct.new(:name, :address) # Customer
ruby0 = Customer.new("Dave", "123 Main") # #<struct Customer name="Dave", address="123 Main">
json = JSON.generate(ruby0) # {"json_class":"Customer","v":["Dave","123 Main"]}
ruby1 = JSON.parse(json, create_additions: true) # #<struct Customer name="Dave", address="123 Main">
ruby1.class # Customer

Symbol

require 'json/add/symbol'
ruby0 = :foo # foo
json = JSON.generate(ruby0) # {"json_class":"Symbol","s":"foo"}
ruby1 = JSON.parse(json, create_additions: true) # foo
ruby1.class # Symbol

Time

require 'json/add/time'
ruby0 = Time.now # 2020-05-02 11:28:26 -0500
json = JSON.generate(ruby0) # {"json_class":"Time","s":1588436906,"n":840560000}
ruby1 = JSON.parse(json, create_additions: true) # 2020-05-02 11:28:26 -0500
ruby1.class # Time

自定义 JSON 扩展¶ ↑

除了提供的 JSON 扩展之外，您还可以为 Ruby 内置类或用户定义的类制作自己的 JSON 扩展。

这是一个用户定义的类 Foo

class Foo
  attr_accessor :bar, :baz
  def initialize(bar, baz)
    self.bar = bar
    self.baz = baz
  end
end

这是它的 JSON 扩展

# Extend class Foo with JSON addition.
class Foo
  # Serialize Foo object with its class name and arguments
  def to_json(*args)
    {
      JSON.create_id  => self.class.name,
      'a'             => [ bar, baz ]
    }.to_json(*args)
  end
  # Deserialize JSON string by constructing new Foo object with arguments.
  def self.json_create(object)
    new(*object['a'])
  end
end

演示

require 'json'
# This Foo object has no custom addition.
foo0 = Foo.new(0, 1)
json0 = JSON.generate(foo0)
obj0 = JSON.parse(json0)
# Lood the custom addition.
require_relative 'foo_addition'
# This foo has the custom addition.
foo1 = Foo.new(0, 1)
json1 = JSON.generate(foo1)
obj1 = JSON.parse(json1, create_additions: true)
#   Make a nice display.
display = <<~EOT
  Generated JSON:
    Without custom addition:  #{json0} (#{json0.class})
    With custom addition:     #{json1} (#{json1.class})
  Parsed JSON:
    Without custom addition:  #{obj0.inspect} (#{obj0.class})
    With custom addition:     #{obj1.inspect} (#{obj1.class})
EOT
puts display

输出

Generated JSON:
  Without custom addition:  "#<Foo:0x0000000006534e80>" (String)
  With custom addition:     {"json_class":"Foo","a":[0,1]} (String)
Parsed JSON:
  Without custom addition:  "#<Foo:0x0000000006534e80>" (String)
  With custom addition:     #<Foo:0x0000000006473bb8 @bar=0, @baz=1> (Foo)