{"canonical_url":"https://engineer.company/uk/glossary/idempotent/","content_markdown":"# Ідемпотентний\n\n## Що це таке\n\nОперація ідемпотентна, коли кілька її виконань мають той самий ефект, що й одне,\n— так кажуть і про ідемпотентний запит чи ідемпотентне завдання, а саму\nвластивість називають ідемпотентністю, англійською idempotence або idempotency.\nСлово походить із математики, де функцію називають ідемпотентною, якщо\nзастосування до власного результату лишає його таким самим, тобто f(f(x))\nдорівнює f(x): округлення вниз числа, яке вже округлили вниз, дає те саме число.\n\nУ програмах корисна перевірка — ще один запуск. Присвоєння значення\nідемпотентне, бо другий запуск записує те значення, яке там уже є. Додавання до\nзначення таким не є, бо другий запуск додає знову:\n\n```sql\n-- ідемпотентно: другий запуск задає те саме значення\nUPDATE accounts SET plan = 'pro' WHERE id = 42;\n\n-- не ідемпотентно: другий запуск додає ще десять\nUPDATE accounts SET credits = credits + 10 WHERE id = 42;\n```\n\nHTTP дає цьому слову найточніше визначення. RFC 9110 називає метод запиту\nідемпотентним, якщо запланований ефект на сервері від кількох однакових запитів\nтакий самий, як від одного, і відносить до таких PUT, DELETE та безпечні методи\nGET, HEAD, OPTIONS і TRACE. У цьому визначенні важливі дві деталі. Властивість\nстосується ефекту, якого просив клієнт, тож сервер може записувати кожен запит у\nжурнал окремо. І відповідь може відрізнятися: другий DELETE того самого ресурсу\nможе отримати 404 там, де перший отримав 200, і метод однаково лишається\nідемпотентним, бо ресурс зник в обох випадках. PATCH стоїть поза цим переліком.\nRFC 5789 каже, що він не є ні безпечним, ні ідемпотентним, але клієнт може\nнадіслати конкретний PATCH ідемпотентно, зробивши його умовним за допомогою\nсильного ETag у заголовку If-Match, тож повторну копію буде відхилено, щойно\nперша змінить ресурс.\n\nБезпечність — суворіша з двох обіцянок. Безпечний метод у розумінні RFC 9110 по\nсуті лише читає, тож кожен безпечний метод ідемпотентний, тоді як DELETE\nідемпотентний, не будучи безпечним.\n\n## Чому це важливо\n\nМережі гублять відповіді. Коли клієнт надсилає запит, а з'єднання обривається до\nтого, як надійде відповідь, клієнт не може знати, чи сервер так і не побачив\nзапиту, чи побачив і зупинився, чи виконав його й загубив відповідь. Повторити\nзапит — очевидний вихід, і саме ідемпотентність робить повтор нешкідливим. RFC\n9110 будує на цьому свої правила повторних спроб. Ідемпотентний запит можна\nавтоматично повторити після збою зв'язку. Неідемпотентний запит клієнту слід\nповторювати автоматично лише тоді, коли він знає, що на практиці цей запит\nідемпотентний, або може встановити, що оригінал так і не було застосовано, а\nпроксі не має права повторювати такий запит сам.\n\nЧерги ставлять те саме питання в масштабі. Багато систем повідомлень обіцяють\nдоставку щонайменше один раз: споживач, який упав після того, як виконав роботу,\nале до того, як підтвердив повідомлення, отримає те саме повідомлення знову.\nДоставка рівно один раз через мережу — значно важча обіцянка, тож практична\nвідповідь — споживач, для якого повторна доставка нічого не змінює. Керування\nконфігурацією теж залежить від цієї властивості. Інструмент, що приводить\nсервери до задекларованого стану, запускається знову і знову, після кожної зміни\nй часто за розкладом, і кожен запуск має залишити правильний сервер точно таким,\nяким його застав.\n\nСправжнє рішення — як отримати ідемпотентність там, де операція за своєю\nприродою її не має, і поширених відповідей три. Перша — проєктування: описати\nзміну як цільовий стан, а не як крок, тобто «переконайся, що цей рядок є у\nфайлі» замість «додай цей рядок». Друга — ключ: клієнт додає до запиту\nунікальний ідентифікатор, сервер зберігає його під обмеженням унікальності, і\nповтор знаходить запис та отримує початковий результат замість другої дії. Третя\n— перевіряти, перш ніж діяти, як це роблять більшість модулів Ansible: вони\nпорівнюють поточний стан із бажаним і завершуються без дій, коли ці два стани\nвже збігаються. Кожна відповідь має ціну. Проєктування через цільовий стан\nпотребує чіткої моделі кінцевого стану, ключі потребують сховища й правила, як\nдовго їх тримати, а перевірка наперед потребує надійного способу прочитати\nпоточний стан.\n\n## Як це виглядає на практиці\n\nВласні сервери компанії налаштовано через Ansible, і в цьому проєкті\n[ідемпотентність є контрактом: хост у бажаному стані звітує про нуль змін](/uk/portfolio/servers-you-can-rebuild-from-scratch/).\nЗапуск автоматизації без жодних аргументів приводить кожен хост до його\nзадекларованого стану, а сценарій Ansible, який не може звітувати про нуль змін\nна хості, що вже налаштований правильно, вважають незавершеним. Так ідемпотентність стає тим, що\nвимірює кожен запуск, а не тим, на що сподіваються.\n\nТа сама ідея, застосована до даних, стоїть за\n[тестом, що двічі запускає дев'ятнадцятикроковий конвеєр збірки](/uk/portfolio/held-the-generator-to-981-tests-and-92-coverage/).\nСторінка називає різновид вади, заради якого він існує: генератор, що працює\nпершого разу й псує другого, через кроки, які вставляють без перевірки або\nзалежать від порядку виводу попереднього кроку. Тест збирає базу даних із\nпорожнього файлу, робить знімок, ще раз запускає весь конвеєр поверх результату\nй вимагає, щоб другий прохід нічого не змінив, аж до кількості рядків, вмісту та\nідентифікаторів. Тест дає свідчення про повторний запуск для тих вхідних даних і стану бази,\nякі він перевіряє.\n\nДля продажу обмеженого запасу нотатка про\n[продаж останнього квитка рівно один раз](/uk/notes/selling-limited-stock-without-overselling/)\nпоєднує ключ з умовними записами. Кожне оформлення замовлення несе ключ\nідемпотентності, а таблиця резервів має `UNIQUE (tenant_id, idempotency_key)`,\nтож повторне натискання отримує резерв, який уже має, а не ще одну одиницю.\nЗвільнення, що спрацювало двічі, наприклад від тайм-ауту і від кнопки\nскасування, повертає одиницю один раз, бо повертає запас лише тоді, коли його\nвласне оновлення змінило рівно один рядок. Далі кожен споживач повідомлень\nідемпотентний, з ідентифікатором замовлення як ключем: повідомлення приходять\nщонайменше один раз, а завдяки ідемпотентності кожне фактично обробляється один\nраз.\n\n## Де виникають проблеми\n\n**Повторна спроба списує гроші двічі.** POST, що створює платіж, замовлення чи\nлист, сам собою не ідемпотентний, і клієнт або проксі, що повторює його після\nтайм-ауту, створює ще один. Варто дати таким запитам ключ ідемпотентності, який\nсервер зберігає під обмеженням унікальності, і повертати збережений результат,\nколи той самий ключ надходить знову.\n\n**Порожній результат сприймають як помилку.** У PostgreSQL\n`INSERT ... ON CONFLICT DO NOTHING` пропускає рядок, який порушив би обмеження\nунікальності, а `RETURNING` повертає лише ті рядки, які справді було вставлено\nчи оновлено. Тому повторна вставка того самого рядка повертає порожній\nрезультат, і це правильний наслідок другого запуску. Код, що вважає такий\nрезультат збоєм, перетворює нешкідливу повторну спробу на сторінку з помилкою;\nнатомість він має знайти рядок, який уже існує.\n\n**Командне завдання змінює хост за кожного запуску.** Документація Ansible каже,\nщо більшість модулів перевіряють, чи бажаного стану вже досягнуто, а також що\nтак поводяться не всі playbook і не всі модулі. Завдання, що виконує команду, —\nтиповий виняток, бо команда довільна, і Ansible не може знати, що вона робить.\nПараметр `creates` модуля command пропускає крок, коли вказаний файл уже існує,\n`removes` виконує його лише доти, доки файл ще є, а `changed_when` визначає,\nякий результат вважати зміною. Командне завдання без жодного з них виконується\nзнову під час кожного застосування конфігурації, хоч би в якому стані був хост.\n\n**Лічильник рахує й повторну спробу.** За доставки щонайменше один раз споживач,\nщо збільшує лічильник чи надсилає сповіщення на кожне повідомлення, зробить це\nдвічі для повідомлення, доставленого двічі. Слід зберігати бізнес-ключ\nповідомлення разом з ефектом в одній транзакції й пропускати кожен ключ, який\nуже збережено.\n\n**Другий запуск псує те, що збудував перший.** Крок може бути правильним на\nпорожній базі й хибним на заповненій, бо вставляє дублікат, перенумеровує\nідентифікатори чи покладається на порядок, який залишив перший запуск. Тест, що\nпочинає з нуля й запускається один раз, однаково пройде. Варто запускати всю\nзадачу двічі й вимагати, щоб другий запуск нічого не змінив, як це робить тест\nконвеєра вище.\n\n## Що почитати далі\n\n- [RFC 9110, section 9.2.2: Idempotent Methods](https://www.rfc-editor.org/rfc/rfc9110#name-idempotent-methods)\n  — визначення HTTP, ідемпотентні методи й правила автоматичних повторних\n  спроб.\n- [RFC 5789: PATCH Method for HTTP](https://www.rfc-editor.org/rfc/rfc5789) —\n  чому PATCH не є ні безпечним, ні ідемпотентним і як умовний запит робить\n  його безпечним для повторення.\n- [Ansible: Introduction to playbooks](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_intro.html)\n  — бажаний стан, ідемпотентність і режим перевірки словами самого Ansible.\n- [Ansible: command module](https://docs.ansible.com/ansible/latest/collections/ansible/builtin/command_module.html)\n  — параметри `creates` і `removes`, що роблять команду безпечною для\n  повторного запуску.\n- [PostgreSQL: INSERT](https://www.postgresql.org/docs/current/sql-insert.html)\n  — `ON CONFLICT` і те, що повертає `RETURNING`, коли рядок уже існує.\n\n\u003chttps://engineer.company/uk/glossary/idempotent/\u003e\n","date_modified":"2026-11-12T05:34:23Z","description":"Що робить операцію ідемпотентною, коли її потребують повторна спроба, повторний запуск чи дубль повідомлення, і які лічильники та команди це ламають.","formats":{"gemtext":"https://engineer.company/uk/glossary/idempotent/index.gmi","gopher":"https://engineer.company/uk/glossary/idempotent/gophermap","html":"https://engineer.company/uk/glossary/idempotent/","json":"https://engineer.company/uk/glossary/idempotent/index.json","markdown":"https://engineer.company/uk/glossary/idempotent/index.md","pdf":"https://engineer.company/uk/glossary/idempotent/index.pdf"},"kind":"page","language":"uk","title":"Що означає ідемпотентний?","url":"https://engineer.company/uk/glossary/idempotent/","version":1}