0.1 + 0.2 ≠ 0.3: деньги в коде — Decimal, тийины, округление и потерянный тийин
Деньги во float в конце месяца расходятся на тийины. Как устроены Decimal и minor units, чем HALF_UP отличается от банковского округления и как не потерять тийин в комиссии — с моделью Django.
Представьте: платёжный сервис берёт 1,5% комиссии с каждой транзакции. Клиент платит 12 335 сумов, код считает комиссию, остаток уходит мерчанту. В конце месяца бухгалтерия сверяет отчёт с банковской выпиской, и всплывает расхождение в несколько тийинов. Сумма смешная, но теперь придётся перепроверять каждую транзакцию, потому что никто не знает, откуда взялась разница.
Почти все такие расхождения рождаются в трёх местах: деньги хранят во float, округляют где попало и как попало, а при делении суммы на части теряют остаточный тийин. Разберём все три и в конце придём к готовому решению с моделью Django.
Почему 0.1 + 0.2 не равно 0.3
Откройте консоль Python:
>>> 0.1 + 0.2
0.30000000000000004
>>> sum([0.1] * 10)
0.9999999999999999
>>> round(2.675, 2)
2.67
Это не баг Python. float — 64-битное двоичное число по стандарту IEEE 754, оно хранится как мантисса × 2^порядок. Как 1/3 нельзя точно записать десятичной дробью (0.3333...), так и 0.1 нельзя точно записать двоичной: это бесконечная периодическая дробь. Поэтому в памяти лежит не 0.1, а ближайшее к нему двоичное число:
>>> from decimal import Decimal
>>> Decimal(0.1)
Decimal('0.1000000000000000055511151231257827021181583404541015625')
По той же причине round(2.675, 2) возвращает 2.67: реальное значение в памяти — 2.67499999..., то есть вовсе не «ровно посередине».
В физике или графике эта погрешность не важна. С деньгами — проблема: ошибки накапливаются, сравнение через == ведёт себя неожиданно, а округление уходит не в ту сторону. В PostgreSQL то же самое:
SELECT 0.1::float8 + 0.2::float8; -- 0.30000000000000004
SELECT 0.1::numeric + 0.2::numeric; -- 0.3
Деньги — это не измерение, а счёт. Float создан для измерений, а деньги нужно считать точно.
Два правильных пути: Decimal и minor units
Есть два распространённых способа хранить деньги точно.
1. Десятичное число (Decimal / NUMERIC). decimal.Decimal в Python хранит число как десятичные цифры и десятичный порядок, поэтому Decimal('0.1') равно ровно 0.1. Тип numeric в PostgreSQL тоже десятичный и точный. В Django это DecimalField.
2. Minor units — целое число в минимальных единицах. Сумму храните не в сумах, а в тийинах: 12 335.00 сума → 1233500 тийинов. Сложение и вычитание целых всегда точны. В Django это BigIntegerField (bigint в PostgreSQL). Многие платёжные API, например Stripe, принимают суммы именно так — в минимальной единице валюты.
Сколько знаков у «мелкой единицы», определяет ISO 4217: у UZS и USD — 2 (тийин, цент), у JPY — 0, у KWD — 3. То есть «умножить на 100» подходит не для всех валют, порядок надо брать по валюте.
float |
Decimal / numeric |
Minor units (bigint) |
|
|---|---|---|---|
| Точность | Приближённая | Точная | Точная |
| Дробная часть | Есть, но двоичная | Любая десятичная | Нет, целое число |
| Точность валюты | — | Фиксируется decimal_places |
Порядок валюты хранится отдельно |
| Проценты, курсы | Опасно | Удобно | Для расчёта нужен временный Decimal |
| Передача в JSON | Как число (опасно) | Обычно строкой | Как целое число |
Выбор зависит от проекта. Для внутренней системы с одной валютой хватит DecimalField(max_digits=18, decimal_places=2). Для мультивалютной системы с внешними платёжными шлюзами я предпочитаю minor units: сумма всегда целая, а валюта лежит рядом. В обоих случаях вычисления (проценты, курсы) делаются в Decimal.
Как работает Decimal: контекст и точность
Самая забываемая часть Decimal — контекст. Каждая арифметическая операция выполняется по правилам текущего контекста:
>>> from decimal import getcontext
>>> getcontext()
Context(prec=28, rounding=ROUND_HALF_EVEN, Emin=-999999, Emax=999999, capitals=1, clamp=0, flags=[], traps=[InvalidOperation, DivisionByZero, Overflow])
Здесь важны две вещи:
prec=28— это не число знаков после запятой, а общее число значащих цифр.Decimal(1) / 3даст 28 цифр. Для денег этого хватает, но это не «два знака».rounding=ROUND_HALF_EVEN— режим по умолчанию, «банковское округление». К нему вернёмся ниже.
Чтобы округлить сумму до нужного числа знаков, используют quantize и всегда явно указывают режим:
from decimal import Decimal, ROUND_HALF_UP
amount = Decimal("185.025")
amount.quantize(Decimal("0.01"), rounding=ROUND_HALF_UP) # Decimal('185.03')
Менять контекст глобально (getcontext().prec = 10) — плохая идея: это влияет на весь код текущего потока или asyncio-задачи. Если нужно временно, используйте localcontext(). Заодно можно включить полезную защиту — ошибку при попадании float:
from decimal import Decimal, FloatOperation, localcontext
with localcontext() as ctx:
ctx.traps[FloatOperation] = True
Decimal("0.1") # работает
Decimal(0.1) # decimal.FloatOperation
А сложение Decimal и float даёт TypeError при любом контексте — и это хорошо, ошибка не прячется:
>>> Decimal("0.1") + 0.2
TypeError: unsupported operand type(s) for +: 'decimal.Decimal' and 'float'
Режимы округления: HALF_UP и банковское
Основных режимов два, и различаются они только на значениях ровно «посередине»:
| Значение | ROUND_HALF_UP |
ROUND_HALF_EVEN (банковское) |
PostgreSQL round(numeric) |
|---|---|---|---|
| 0.5 | 1 | 0 | 1 |
| 1.5 | 2 | 2 | 2 |
| 2.5 | 3 | 2 | 3 |
| -2.5 | -3 | -2 | -3 |
- HALF_UP — школьное округление: .5 уходит от нуля. В Python
ROUND_HALF_UPи для отрицательных чисел округляет от нуля. - HALF_EVEN (банковское) — .5 уходит к ближайшему чётному. Если округлять и суммировать много значений, HALF_UP систематически сдвигает результат вверх, а HALF_EVEN в среднем этот сдвиг гасит.
Обратите внимание: встроенный round() в Python тоже банковский (round(2.5) == 2), а round(numeric) в PostgreSQL округляет от нуля (round(2.5) = 3). Если один и тот же расчёт делается то в Python, то в SQL, результаты могут разойтись.
Режим округления — не вопрос вкуса разработчика. Обычно его задаёт спецификация платёжного провайдера, договор или финансовый отдел. Ваша задача — записать правило в одном месте и использовать его везде.
Комиссия: не потерять тийин
Вернёмся к примеру из начала. Платёж 12 335.00 сума = 1 233 500 тийинов, комиссия 1,5%:
>>> Decimal(1233500) * Decimal("0.015")
Decimal('18502.500')
Ровно посередине. С HALF_UP — 18 503 тийина, с HALF_EVEN — 18 502. Один тийин, но на тысячах транзакций это превращается в заметное расхождение между двумя системами.
Ещё более частая ошибка — округлять и комиссию, и выплату мерчанту по отдельности:
# НЕПРАВИЛЬНО: обе части округляются независимо
fee = round(amount * 0.015, 2)
payout = round(amount * 0.985, 2)
# fee + payout не всегда равно amount
Тут и float, и двойное округление. Правильно: посчитать и округлить одну часть, а вторую получить вычитанием. Тогда сумма всегда сходится:
from decimal import Decimal, ROUND_HALF_UP
def split_fee(amount_minor: int, rate: Decimal) -> tuple[int, int]:
"""Возвращает комиссию и долю мерчанта в тийинах; сумма всегда amount_minor."""
if not isinstance(rate, Decimal):
raise TypeError("rate должен быть Decimal")
raw = Decimal(amount_minor) * rate
fee = int(raw.quantize(Decimal("1"), rounding=ROUND_HALF_UP))
return fee, amount_minor - fee
fee, payout = split_fee(1_233_500, Decimal("0.015"))
assert fee + payout == 1_233_500 # 18503 + 1214997
Деление суммы на несколько частей (например, 100 сумов на трёх партнёров) — ещё одна классическая ловушка: 33.33 × 3 = 99.99, тийин пропал. Решение — распределить остаток (метод наибольшего остатка):
def allocate(total_minor: int, weights: list[int]) -> list[int]:
"""Делит total_minor пропорционально weights; сумма всегда total_minor."""
if total_minor < 0 or not weights or any(w < 0 for w in weights) or sum(weights) == 0:
raise ValueError("некорректные аргументы")
wsum = sum(weights)
shares = [total_minor * w // wsum for w in weights]
remainders = [total_minor * w % wsum for w in weights]
leftover = total_minor - sum(shares)
# остаточные тийины отдаём долям с наибольшим остатком
order = sorted(range(len(weights)), key=lambda i: remainders[i], reverse=True)
for i in order[:leftover]:
shares[i] += 1
return shares
assert allocate(10_000, [1, 1, 1]) == [3334, 3333, 3333]
assert sum(allocate(1_233_500, [70, 20, 10])) == 1_233_500
// и % на целых точны, а sorted стабилен, поэтому результат детерминирован: на одинаковом входе всегда одинаковое распределение.
Модель Django: сумма и валюта вместе
Сумма без валюты — просто число. «1000» — это сумы или доллары? Поэтому сумма и валюта всегда хранятся рядом и ходят по коду как одно значение.
from decimal import Decimal
from django.db import models
from django.db.models import F, Q
MINOR_EXPONENT = {"UZS": 2, "USD": 2, "EUR": 2, "JPY": 0, "KWD": 3}
class Currency(models.TextChoices):
UZS = "UZS", "Узбекский сум"
USD = "USD", "Доллар США"
EUR = "EUR", "Евро"
class Payment(models.Model):
amount_minor = models.BigIntegerField(help_text="В минимальных единицах: тийины, центы")
fee_minor = models.BigIntegerField(default=0)
currency = models.CharField(max_length=3, choices=Currency.choices)
created_at = models.DateTimeField(auto_now_add=True)
class Meta:
constraints = [
models.CheckConstraint(
condition=Q(amount_minor__gt=0),
name="payment_amount_positive",
),
models.CheckConstraint(
condition=Q(fee_minor__gte=0) & Q(fee_minor__lte=F("amount_minor")),
name="payment_fee_within_amount",
),
]
@property
def amount(self) -> Decimal:
return Decimal(self.amount_minor).scaleb(-MINOR_EXPONENT[self.currency])
CheckConstraint(condition=...) работает начиная с Django 5.1 (прежний аргумент check= устарел). Ограничения живут на уровне базы: откуда бы ни писал код — админка, management command или голый SQL — отрицательная сумма или комиссия больше суммы не сохранится.
Небольшой хелпер для перевода внешней суммы в тийины. Он отвергает float и не округляет молча сумму, у которой знаков больше, чем допускает валюта:
def to_minor(amount: Decimal | str, currency: str) -> int:
if isinstance(amount, float):
raise TypeError("float не принимается, передайте Decimal или str")
scaled = Decimal(amount).scaleb(MINOR_EXPONENT[currency])
if scaled != scaled.to_integral_value():
raise ValueError(f"у {amount} слишком много знаков для {currency}")
return int(scaled)
assert to_minor("12335.00", "UZS") == 1_233_500
assert to_minor("1500", "JPY") == 1500
Если выбираете путь DecimalField, модель будет такой, а в PostgreSQL появится колонка numeric(18, 2):
class Invoice(models.Model):
amount = models.DecimalField(max_digits=18, decimal_places=2)
currency = models.CharField(max_length=3, choices=Currency.choices)
Ловушки в продакшене
Скрытое округление при сохранении. Если записать Decimal("10.005") в DecimalField(decimal_places=2), full_clean() его отклонит, но обычный save() валидацию не вызывает. В PostgreSQL значение округлится до масштаба колонки, причём от нуля: 10.005 → 10.01. На другом бэкенде результат может отличаться. Вывод: делайте quantize сами до сохранения.
SELECT 10.005::numeric(12, 2); -- 10.01
SELECT 12345678901.00::numeric(12, 2); -- ERROR: numeric field overflow
Float в ORM-выражениях. F("amount") * 0.015 в Django даёт FieldError: смешаны DecimalField и FloatField, тип результата не определить. Правильно — F("amount") * Value(Decimal("0.015")).
JSON. json.dumps не умеет сериализовать Decimal (TypeError), и иногда «быстрым» решением становится float(amount) — именно здесь точность и теряется. DjangoJSONEncoder в Django и DecimalField в DRF отдают Decimal строкой. При чтении входящего JSON используйте json.loads(body, parse_float=Decimal) или принимайте сумму целым числом тийинов.
Округление на каждом шаге. Округляя промежуточные результаты, вы накапливаете ошибку. Внутренние расчёты ведите с полной точностью и округляйте один раз на «границе» денег — при сохранении, платеже, в чеке.
Курсы валют. Курс — не деньги, ему нужно больше знаков. Не храните курс в колонке с decimal_places=2; заведите для него отдельное поле повышенной точности (например, max_digits=20, decimal_places=10) и сохраняйте момент, когда курс был получен.
Сложение разных валют. Складывать amount_minor без проверки валюты — тихая ошибка. Агрегируйте всегда с группировкой по валюте: Payment.objects.values("currency").annotate(total=Sum("amount_minor")).
Тип money в PostgreSQL. Он привязывает формат вывода к настройке lc_monetary и не хранит валюту. Для мультивалютной системы numeric или bigint + код валюты гораздо предсказуемее.
Практический чеклист
- Деньги никогда не бывают
float: ни в модели, ни в расчётах, ни в JSON. - Один формат хранения:
BigIntegerField(minor units) илиDecimalField— не смешивайте по проекту. - Рядом с суммой всегда код валюты (ISO 4217); порядок валюты берётся из таблицы, а не захардкоженной
100. Decimalсоздаётся только изstrилиint; в тестах включите trapFloatOperation.- Режим округления указан явно (
quantize(..., rounding=...)) и живёт в одной функции. - Комиссия: одна часть округляется, вторая — разность; при делении распределяется остаток.
- В базе
CheckConstraint: сумма положительна, комиссия не больше суммы. - В тестах проверяйте инварианты вроде
fee + payout == amount.
Итог
Float не создан для денег: он приближённый, а деньги считают точно. Храните сумму целым числом в минимальных единицах или как Decimal/numeric, держите валюту рядом и описывайте правило округления в одном месте с явным режимом. Главный инвариант простой: сумма частей всегда равна целому — гарантируйте это в коде, в тестах и в базе.
// комментарии
Загружаем комментарии...