ENRU

Большие числа в JSON: BigInt, точность и JSON.parse

Обновлено

JSON.parse('{"id":12345678901234567890}') возвращает 12345678901234567000. Ни ошибки, ни предупреждения — просто другие цифры. Ниже: откуда берётся граница 2^53, почему 1.10 возвращается как 1.1, что значит «Do not know how to serialize a BigInt» и как читать и писать большие числа без потерь в JavaScript, Python, Go и Java.

Почему JSON.parse меняет большие числа

Сам JSON предела не ставит: в RFC 8259 число — это цифры, необязательная дробная часть и необязательный порядок. Предел — у того, кто читает. В JavaScript один числовой тип: 64-битное двоичное число с плавающей точкой двойной точности, и на цифры в нём отведено 53 бита. Любое целое до 2^53 = 9 007 199 254 740 992 помещается точно. Выше представимо только каждое второе целое, потом каждое четвёртое и так далее; JSON.parse берёт ближайшее и молчит.

JSON.parse('9007199254740993');            // 9007199254740992
JSON.parse('{"id":12345678901234567890}'); // { id: 12345678901234567000 }

Number.MAX_SAFE_INTEGER;                   // 9007199254740991, то есть 2 ** 53 - 1
Number.isSafeInteger(2 ** 53);             // false

RFC 8259, раздел 6 разрешает парсерам ограничивать диапазон и точность чисел и обещает согласие только для целых от −2^53 + 1 до 2^53 − 1: в этом диапазоне все реализации сходятся в значении точно. Число больше — по-прежнему валидный JSON, но два читателя могут увидеть в нём два разных значения.

Чаще всего страдают 64-битные ID из баз данных, ID в духе snowflake из распределённых систем, метки времени в наносекундах и суммы в копейках. API Twitter по этой причине отдавал каждый ID дважды: числом id и строкой id_str.

Почему 1.10 становится 1.1

Цифры — не единственная потеря. Разобранное число — это значение, а не текст: 1.10 и 1.1 — один и тот же double, поэтому после JSON.parse и JSON.stringify остаётся самая короткая запись. 2.50 превращается в 2.5, 1e3 — в 1000, -0 — в 0.

Для большинства данных это безвредно. Вредно там, где важен сам текст: перестаёт сходиться подпись или хеш тела, цена теряет нуль на конце, которого ждёт шаблон счёта, а сравнение двух выгрузок показывает изменения, которых никто не вносил. Арифметика — отдельная история: 0.1 + 0.2 даёт 0.30000000000000004 в любом языке с double, поэтому деньгам место в десятичном типе или в целых копейках.

Как популярные парсеры печатают одни и те же числа

Это легко проверить самому. В документе большое целое, две дроби с нулями на конце и число с порядком:

doc='{"id":12345678901234567890,"price":1.10,"total":2.50,"exp":1e3}'

node -e 'console.log(JSON.stringify(JSON.parse(process.argv[1])))' "$doc"
# {"id":12345678901234567000,"price":1.1,"total":2.5,"exp":1000}

python3 -c 'import json, sys; print(json.dumps(json.loads(sys.argv[1])))' "$doc"
# {"id": 12345678901234567890, "price": 1.1, "total": 2.5, "exp": 1000.0}

echo "$doc" | jq -c .
# {"id":12345678901234567890,"price":1.10,"total":2.50,"exp":1E+3}

Тот же документ в распространённых парсерах с настройками по умолчанию:

Парсер123456789012345678901.101e3
JavaScript JSON.parse (Node.js 25)123456789012345670001.11000
Python json (3.9)123456789012345678901.11000.0
Go encoding/json в any (1.25)123456789012345670001.11000
Go с Decoder.UseNumber()123456789012345678901.101e3
Jackson readTree (2.15)123456789012345678901.11000.0
jq (1.7.1)123456789012345678901.101E+3
Форматирование JSON Statham123456789012345678901.101e3

jq 1.7 хранит текст числа, пока его никто не трогает; арифметика превращает его в double, и .id + 1 печатает 12345678901234567000 (руководство jq).

TypeError: Do not know how to serialize a BigInt

BigInt хранит целые любой длины, но JSON.stringify его не принимает. Текст ошибки зависит от движка:

  • Chrome, Edge и Node.js (V8): TypeError: Do not know how to serialize a BigInt. Перевод: «не знаю, как сериализовать BigInt».
  • Firefox: TypeError: BigInt value can’t be serialized in JSON. Перевод: «значение BigInt нельзя сериализовать в JSON».
  • Safari: TypeError: JSON.stringify cannot serialize BigInt. Перевод: «JSON.stringify не умеет сериализовать BigInt».

Отказ намеренный (справка по этой ошибке): BigInt, записанный обычным числом, вернулся бы из JSON.parse уже округлённым, поэтому язык заставляет выбрать формат явно. Для этого нужен replacer:

const order = { id: 12345678901234567890n, qty: 3 };

// Точные цифры, настоящим числом JSON
JSON.stringify(order, (key, value) =>
  typeof value === 'bigint' ? JSON.rawJSON(value.toString()) : value);
// '{"id":12345678901234567890,"qty":3}'

// Строкой: работает в любой среде
JSON.stringify(order, (key, value) =>
  typeof value === 'bigint' ? value.toString() : value);
// '{"id":"12345678901234567890","qty":3}'

JSON.rawJSON пишет цифры настоящим числом JSON; он есть в Chrome 114+, Firefox 135+, Safari 18.4+ и Node.js 21+. Строка работает везде, а читатель знает, что её нужно разобрать. BigInt.prototype.toJSON делает то же глобально, для каждой библиотеки в процессе; replacer оставляет решение там, где оно принято.

Как разобрать большие числа точно в JavaScript

Те же движки передают в reviver у JSON.parse третий аргумент — context.source, исходный текст каждого примитивного значения. Он пришёл из предложения о доступе к исходному тексту в JSON.parse и теперь вместе с JSON.rawJSON входит в спецификацию ECMAScript. Безопасные целые остаются числами, остальные превращаются в BigInt:

const text = '{"id":12345678901234567890,"price":1.10,"qty":3}';

const data = JSON.parse(text, (key, value, context) => {
  if (typeof value === 'number' && /^-?\d+$/.test(context.source)) {
    return Number.isSafeInteger(value) ? value : BigInt(context.source);
  }
  return value;
});

data.id;    // 12345678901234567890n
data.price; // 1.1 (в тексте было 1.10; если это важно, нужен context.source)
data.qty;   // 3

Для дробей, где важны нули на конце, можно вернуть сам context.source, то есть строку, или передать его в библиотеку десятичных чисел. В старых средах выручает пакет json-bigint: большие целые он отдаёт как BigInt и пишет обратно числами, но запись не сохраняет, так что 1.10 всё равно станет 1.1 (json-bigint 1.0.0).

import JSONbig from 'json-bigint';

const parser = JSONbig({ useNativeBigInt: true });
const data = parser.parse('{"id":12345678901234567890,"price":1.10}');

data.id;                // 12345678901234567890n
parser.stringify(data); // '{"id":12345678901234567890,"price":1.1}'

Python, Go и Java

Python

int в Python не ограничен по длине, поэтому json.loads хранит большие целые точно. Дроби становятся float: 1.10 превращается в 1.1, а 1e3 — в 1000.0. Параметр parse_float=Decimal сохраняет все цифры. Записать Decimal обратно числом стандартная библиотека не умеет, а simplejson умеет:

import json
from decimal import Decimal

text = '{"id": 12345678901234567890, "price": 1.10}'
data = json.loads(text, parse_float=Decimal)
data["id"]     # 12345678901234567890, точный int
data["price"]  # Decimal('1.10')

json.dumps(data)
# TypeError: Object of type Decimal is not JSON serializable

import simplejson
simplejson.dumps(data)  # '{"id": 12345678901234567890, "price": 1.10}'

Ещё одна ловушка: json.loads("1e400") даёт inf, а json.dumps пишет его как Infinity — это уже не JSON. С allow_nan=False вместо этого будет ValueError; подробнее — в разборе недопустимых литералов.

Go

При разборе в any каждое число становится float64. Decoder.UseNumber сохраняет текст как json.Number, и json.Marshal пишет его обратно без изменений. В структурах подходят *big.Int, uint64 или json.Number; поле int64 такое значение не примет: json: cannot unmarshal number 12345678901234567890 into Go struct field Order.id of type int64.

dec := json.NewDecoder(strings.NewReader(`{"id":12345678901234567890,"price":1.10}`))
dec.UseNumber()
var data map[string]any
if err := dec.Decode(&data); err != nil {
	log.Fatal(err)
}

fmt.Println(data["id"], data["price"]) // 12345678901234567890 1.10
out, _ := json.Marshal(data)
fmt.Println(string(out)) // {"id":12345678901234567890,"price":1.10}

type Order struct {
	ID    *big.Int    `json:"id"`
	Price json.Number `json:"price"`
}

Java (Jackson)

Jackson читает целые, которые не помещаются в long, как BigInteger — точно. Дроби становятся double, если тип не говорит иначе: с полем BigDecimal значение 1.10 остаётся 1.10, в том числе при записи. Для нетипизированных Map нужно включить DeserializationFeature.USE_BIG_DECIMAL_FOR_FLOATS (настройки десериализации). Дерево JsonNode в Jackson 2.15 и тогда отбрасывает нули на конце и превращает 1.10 в 1.1, если не выключить ещё и JsonNodeFeature.STRIP_TRAILING_BIGDECIMAL_ZEROES; типизированные поля проще.

public record Order(BigInteger id, BigDecimal price) {}

Order order = new ObjectMapper().readValue(
    "{\"id\":12345678901234567890,\"price\":1.10}", Order.class);

order.id();    // 12345678901234567890
order.price(); // 1.10

Что JSON Statham делает с числами

Инструменты сайта никогда не превращают документ в числа JavaScript. API читает текст и переносит каждое число так, как оно записано, поэтому ничего из описанного выше от настроек не зависит:

  • Форматирование и минификация меняют только пробелы: 12345678901234567890, 1.10 и 1e3 выходят такими же, какими вошли.
  • Валидатор считает большие целые в отчёте, в поле big_ints: это целые больше 2^53 − 1, которые JSON.parse округлил бы.
  • Сравнение сравнивает числа по точному десятичному значению: 1.10 равно 1.1, 1e3 равно 1000, а 9007199254740993 и 9007199254740992 — разные.
  • JSON в YAML пишет каждое число теми же цифрами.
  • JSON в query-строку переносит числа как записано; в обратную сторону, с типами, переключёнными на числа, 2.50 остаётся 2.50.

После форматирования, минификации и перевода в YAML строка состояния на широком экране ещё и сообщает, сколько больших целых прошло без округления. Чтобы увидеть это, достаточно вставить документ из примера выше в форматирование или выбрать там «Пример», затем «Тест точности».

Как передавать большие числа безопасно

  • ID: 64-битные ID лучше передавать строками. Это метки, а не количества, и строку прочитает любой клиент.
  • Деньги: десятичная строка вроде "19.90" или целые копейки, которые не выходят за 2^53 − 1; какой вариант выбран, стоит написать в документации API.
  • Подписанные и хешированные тела: подписывать ровно те байты, что уходят, и не разбирать и не пересобирать их по дороге.
  • Цепочки сервисов: проверить, что каждое звено делает с числами. Одного JSON.parse в прокси или логгере хватит, чтобы значение изменилось.

Большие числа в JSON: частые вопросы

Валиден ли 12345678901234567890 как JSON?

Да. RFC 8259 не ограничивает размер числа и оставляет предел на усмотрение парсера. Валидатор примет такое число и посчитает его в big_ints.

Какое самое большое целое JSON.parse сохраняет точно?

9007199254740991, то есть Number.MAX_SAFE_INTEGER или 2^53 − 1. Некоторые целые побольше уцелеют случайно, например степени двойки, но Number.isSafeInteger возвращает true только до этого значения.

Стоит ли API отдавать 64-битные ID строками?

Если среди клиентов есть JavaScript, то да. Число больше 2^53 − 1 — валидный JSON, но браузер прочитает другое значение и ничего не скажет.

Почему JSON.stringify падает на BigInt, но не на больших числах?

Большое значение типа Number округлено ещё до JSON.stringify, терять уже нечего. В BigInt все цифры целы, а обычное число JSON потеряло бы их при следующем JSON.parse, поэтому движок заставляет выбрать: JSON.rawJSON или строка.