Все заметки
Финтех

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; в тестах включите trap FloatOperation.
  • Режим округления указан явно (quantize(..., rounding=...)) и живёт в одной функции.
  • Комиссия: одна часть округляется, вторая — разность; при делении распределяется остаток.
  • В базе CheckConstraint: сумма положительна, комиссия не больше суммы.
  • В тестах проверяйте инварианты вроде fee + payout == amount.

Итог

Float не создан для денег: он приближённый, а деньги считают точно. Храните сумму целым числом в минимальных единицах или как Decimal/numeric, держите валюту рядом и описывайте правило округления в одном месте с явным режимом. Главный инвариант простой: сумма частей всегда равна целому — гарантируйте это в коде, в тестах и в базе.

// комментарии

Загружаем комментарии...

    // следующий шаг

    Давайте построим что-нибудь вместе.

    Написать в Telegram
    aslbek@asldev: ~
    ❯