How to Discuss Idempotency in English

« Просто спробуйте ще раз » — це небезпечна порада, якщо операція, яку ви намагаєтеся повторити, не є idempotent — цей посібник містить словник для пояснення цієї концепції точно, чи ви пишете документацію API для іншої команди, чи обґрунтовуєте рішення про дизайн для рецензента.

Ключовий словник

** Ідемотентна операція ** — операція, яка дає той самий кінцевий результат, незалежно від того, виконується вона один раз або декілька разів з тими ж вхідними даними, що робить повторення спроби після невдачі безпечним, оскільки не виникає ризику повторення побічних ефектів. ” PUT /users/123 є ідемпотентним — надіслання його п’ ять разів встановлює ім’ я користувача на те саме значення п’ ять разів, не відрізняючись від надіслання його один раз. Саме тому безпечно автоматично повторювати спробу після закінчення тайм-аута.»

** Не- імпотентна операція ** — операція, повторення якої змінює результат кожного разу, наприклад, операція, яка збільшує значення або створює новий ресурс за кожним викликом, що робить повторення сліпо небезпечним. ” POST /orders не є ідемпотентним за замовчуванням — якщо час відповіді закінчився і ми сліпо повторимо спробу, ми можемо створити два замовлення для того, що клієнт мав на увазі як одну покупку.”

** Ключ ідемотентності ** — унікальний ідентифікатор, створений клієнтом і приєднаний до запиту, який використовується сервером для виявлення і безпечного ігнорування дублікатів, що надсилаються для виконання однієї і тієї ж логічної операції, що робить безпечним повторення спроби виконання операції на кінцевій точці, яка не є ідемотентною.

• “Ми додали підтримку ключів із одним ключем до кінцевої точки оплати, щоб клієнти могли безпечно повторити спробу після закінчення часу очікування — сервер розпізнає повторений ключ і повертає початковий результат замість двічі обкладати карту.” *

** Принаймні- один раз- доставка** — гарантія (поширена у чергах повідомлень і розподілених системах), що повідомлення буде доставлено один або більше разів, але ніколи не нуль разів, що робить ідемпотентну обробку на приймальному кінці вимогою, а не додатковою цінністю. “Наша черга повідомлень гарантує принаймні одну доставку, а не точно одну — це означає, що наш споживач має бути ідемпотентним, тому що подвійні доставки одного і того ж повідомлення є очікуваним, нормальним явищем, а не крайнім випадком.”

Звичайні фрази

• Чи є ця операція дійсно ідемпотентною, або ж її можна викликати тільки один раз?»
• Чи потрібно нам ключ ідемпотентності, щоб зробити повторні спроби безпечними?»
• «Даючи принаймні одну доставку, чи наш споживач дійсно ідемпотентний, чи може подвійне повідомлення викликати проблему?»
• Що робити, якщо один і той же запит прийде двічі?
• «Чи є повторення тут безпечним за замовчуванням, або чи потрібно явне відновлення логіки?»

Приклади висловлювань

Пояснення рішення про проектування в PR:

• “Додано підтримку ключів ідемпотентності до цієї кінцевої точки, оскільки вона не є ідемпотентною — вона створює ресурс при кожному виклику. Клієнти тепер передають ключ з кожним запитом, і якщо ми бачимо повторний ключ протягом 24 годин, ми повертаємо оригінальну відповідь замість створення дублікату. ”*

Позначення ризику у перегляді коду: “Ця логіка повторення припускає, що операція є ідемпотентною, але вона викликає кінцеву точку, яка збільшує лічильник на кожному запиті — якщо повторення викликається після невірного тайм- аута (оригінальний запит насправді був успішним), ми подвоїмо збільшення. Нам потрібен або ключ ідемпотентності, або інша стратегія повторних спроб тут.”

Пояснення схеми черги співробітнику команди: “Оскільки наша черга гарантує лише принаймні одну доставку, ми не можемо припустити, що це повідомлення буде доставлено точнісінько один раз — користувачеві потрібно перевірити, чи він вже обробив цей ідентифікатор повідомлення перед тим, як діяти з ним, інакше дублікат доставки може призвести до дублікатного платежу.”

Професійні поради

• Переконайтеся, що операція є справді ** неможливою ** перед додаванням до неї логіки автоматичних повторних спроб — повторна спроба операції, яка не є неможливою, є однією з найпоширеніших причин подій з дублікатом або дублікатом запису.
• Запропонувати ** ключ недосконалості ** явно як виправлення, коли операція має бути безпечною від повторних спроб, але, природно, не є — це стандартний, добре зрозумілий шаблон, і його назва сигналізує про розумний дизайн, а не про ad hoc обхід.
• Посилання ** принаймні-один раз доставка ** при обґрунтуванні того, чому споживач повідомлення повинен бути ідемпотентним — це пояснює, що вимога не є параноїкою, це прямий наслідок гарантії доставки, яку насправді надає черга.
• Запитайте «що станеться, якщо цей запит прийде двічі» явно під час будь-якого перегляду дизайну API — це швидкий, конкретний спосіб виявити, чи потребує кінцева точка обробки імпотентності перед тим, як вона буде відправлена.

Практичні вправи

1. Напишіть речення, у якому буде пояснено різницю між іменемпотентною і неіменемпотентною операцією.
2. Поясніть, що робить ключ ідемпотентності і чому він потрібен.
3. Описати, чому at- at- least- once delivery робить обробку повідомлень з іменем обов’ язковою, а не необмеженою.

Наприклад, слово «ідеалізм» вживається в значенні «ідеалізм у практиці»

Погляньмо правді в очі - “імпотентність” може здатися складним словом, коли ви намагаєтеся пояснити це колегам. Не відразу очевидно, як це пов’язано з повсякденною розробкою програмного забезпечення, і технічне визначення — «функція або операція може бути застосована кілька разів без зміни результату за межами початкового застосування» — може звучати абстрактно. Ключ не просто в тому, щоб знати що це, але в тому, щоб бути в змозі сформулювати чому це важливо і коли це актуально у вашому спілкуванні під час перегляду коду, обговорення Slack або написання описів запитів на витяг.

Одним з найпоширеніших камінням спотикання є переклад цієї концепції на мову, яку інші легко розуміють. Розглянемо сценарій: ви переглядаєте PR колеги для нової кінцевої точки API, призначеної для оновлення профілів користувачів. У описі просто сказано: « Ця кінцева точка оновлює профіль користувача ». Це технічно правильно, але це не передає важливості ідемпотентності. Кращий підхід буде: “Чи можемо ми додати документацію, яка пояснює, що ця кінцева точка є ідемпотентною? Зокрема, якщо користувач спробує оновити свій профіль декілька разів (можливо, через механізм повторних спроб), кінцевий результат повинен бути ідентичним до того, що відбудеться після одного успішного оновлення. Це допомагає нам уникнути потенційних невідповідностей даних. » Зауважте, як формулювання цього як занепокоєння щодо « потенційних невідповідностей даних » негайно резонує з розробниками, зосередженими на надійності і коректності.

Інша ситуація може виникнути під час розмови Slack, коли хтось запитає: « Чому ми маємо хвилюватися про те, що ця кінцева точка зазнає невдачі і повторює спробу?» Корисною відповіддю буде: « Тому що, якщо оновлення не є ідемпотентним, кожна повторна спроба може * додавати * до змін, що призведе до несподіваного і неправильного кінцевого стану. Ідемпотентність забезпечує, що навіть після декількох спроб після невдачі система залишається у тому ж послідовному стані. Ви також можете використовувати такі фрази, як « це стосується будівництва для стійкості » або « ми хочемо мінімізувати вплив перехідних помилок ».

Нарешті, коли ви пишете опис запитів на захоплення для вашої власної роботи, не просто скажіть, що ви реалізували ідемпотентність. Поясни, чому ти це зробив. Наприклад: «Впроваджено логіку оновлення idempotent для профілів користувачів, щоб запобігти пошкодженню даних під час повторних спроб. Цей дизайн забезпечує, що декілька спроб оновити той же профіль призведе до того ж кінцевого стану, що відповідає нашому зобов’язанню до надійної і передбачуваної поведінки API. “Сфокусування на * результаті * - запобігання проблемам - часто є більш ефективним, ніж просто зазначити технічні деталі.