Большие числа в 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); // falseRFC 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}Тот же документ в распространённых парсерах с настройками по умолчанию:
| Парсер | 12345678901234567890 | 1.10 | 1e3 |
|---|---|---|---|
JavaScript JSON.parse (Node.js 25) | 12345678901234567000 | 1.1 | 1000 |
Python json (3.9) | 12345678901234567890 | 1.1 | 1000.0 |
Go encoding/json в any (1.25) | 12345678901234567000 | 1.1 | 1000 |
Go с Decoder.UseNumber() | 12345678901234567890 | 1.10 | 1e3 |
Jackson readTree (2.15) | 12345678901234567890 | 1.1 | 1000.0 |
| jq (1.7.1) | 12345678901234567890 | 1.10 | 1E+3 |
| Форматирование JSON Statham | 12345678901234567890 | 1.10 | 1e3 |
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 или строка.