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

> Узнать, почему JSON.parse округляет целые больше 2^53, как исправить «Do not know how to serialize a BigInt» и сохранить большие числа в JSON точно.

- Адрес: https://jsonstatham.dev/ru/guides/json-big-numbers/
- Язык: Русский (ru)
- Английская версия: https://jsonstatham.dev/guides/json-big-numbers.md
- Обновлено: 2026-11-08

`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` берёт ближайшее и молчит.

```js
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](https://www.rfc-editor.org/rfc/rfc8259#section-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, поэтому деньгам место в десятичном типе или в целых копейках.

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

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

```shell
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](https://jqlang.org/manual/)).

## 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».

Отказ намеренный ([справка по этой ошибке](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Errors/BigInt_not_serializable)): BigInt, записанный обычным числом, вернулся бы из `JSON.parse` уже округлённым, поэтому язык заставляет выбрать формат явно. Для этого нужен replacer:

```js
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`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/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](https://github.com/tc39/proposal-json-parse-with-source) и теперь вместе с `JSON.rawJSON` входит в [спецификацию ECMAScript](https://tc39.es/ecma262/#sec-json.parse). Безопасные целые остаются числами, остальные превращаются в BigInt:

```js
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](https://github.com/sidorares/json-bigint): большие целые он отдаёт как BigInt и пишет обратно числами, но запись не сохраняет, так что `1.10` всё равно станет `1.1` (json-bigint 1.0.0).

```js
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`](https://docs.python.org/3/library/json.html#json.loads) сохраняет все цифры. Записать `Decimal` обратно числом стандартная библиотека не умеет, а [simplejson](https://github.com/simplejson/simplejson) умеет:

```python
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`; подробнее — в разборе [недопустимых литералов](https://jsonstatham.dev/ru/errors/invalid-literal/).

### Go

При разборе в `any` каждое число становится `float64`. [`Decoder.UseNumber`](https://pkg.go.dev/encoding/json#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`.

```go
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` ([настройки десериализации](https://github.com/FasterXML/jackson-databind/wiki/Deserialization-Features)). Дерево `JsonNode` в Jackson 2.15 и тогда отбрасывает нули на конце и превращает `1.10` в `1.1`, если не выключить ещё и `JsonNodeFeature.STRIP_TRAILING_BIGDECIMAL_ZEROES`; типизированные поля проще.

```java
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 читает текст и переносит каждое число так, как оно записано, поэтому ничего из описанного выше от настроек не зависит:

- [Форматирование](https://jsonstatham.dev/ru/) и [минификация](https://jsonstatham.dev/ru/minifier/) меняют только пробелы: `12345678901234567890`, `1.10` и `1e3` выходят такими же, какими вошли.
- [Валидатор](https://jsonstatham.dev/ru/validator/) считает большие целые в отчёте, в поле `big_ints`: это целые больше 2^53 − 1, которые `JSON.parse` округлил бы.
- [Сравнение](https://jsonstatham.dev/ru/diff/) сравнивает числа по точному десятичному значению: `1.10` равно `1.1`, `1e3` равно `1000`, а `9007199254740993` и `9007199254740992` — разные.
- [JSON в YAML](https://jsonstatham.dev/ru/json-to-yaml/) пишет каждое число теми же цифрами.
- [JSON в query-строку](https://jsonstatham.dev/ru/json-to-query/) переносит числа как записано; в обратную сторону, с типами, переключёнными на числа, `2.50` остаётся `2.50`.

После форматирования, минификации и перевода в YAML строка состояния на широком экране ещё и сообщает, сколько больших целых прошло без округления. Чтобы увидеть это, достаточно вставить документ из примера выше в [форматирование](https://jsonstatham.dev/ru/) или выбрать там «Пример», затем «Тест точности».

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

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

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

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

Да. RFC 8259 не ограничивает размер числа и оставляет предел на усмотрение парсера. [Валидатор](https://jsonstatham.dev/ru/validator/) примет такое число и посчитает его в `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` или строка.
