Czego szukasz?

Wpisz temat, narzędzie lub problem do rozwiązania.

← Wszystkie artykuły

Idempotencja: dlaczego ta sama automatyzacja nie powinna wykonać operacji dwa razy

Powtórzone kontury pieczątki nad jednym zielonym odciskiem

Serwer zapisał zamówienie, ale klient nie otrzymał odpowiedzi. Ponowienie żądania może utworzyć drugie zamówienie, choć użytkownik kliknął tylko raz. Idempotencja pozwala powtórzyć tę samą operację bez ponownego wykonania jej zamierzonego skutku.

Nie oznacza to, że program uruchomi się dokładnie raz. Próby mogą być wielokrotne. Chodzi o to, żeby system rozpoznawał jedno zlecenie i konsekwentnie obsługiwał jego wynik.

Zdefiniuj operację, zanim dodasz klucz

Zapis „ustaw wartość na 10” ma inną naturę niż „dodaj 10”. Powtórzenie pierwszego może pozostawić ten sam stan, a drugiego zwiększy wynik ponownie.

W HTTP część metod ma semantykę idempotentną, ale nie wynika z tego, że dowolny endpoint używający POST automatycznie wykryje duplikat. Kontrakt aplikacji musi jasno określać znaczenie ponowienia.

Rozdziel identyfikator próby od identyfikatora operacji. Nowy request_id może oznaczać nową transmisję, natomiast klucz idempotencji powinien pozostać wspólny dla wszystkich prób tego samego zlecenia. Podstawy żądań opisuje REST API.

Co zapisać razem z kluczem

Przydatny rekord zawiera klucz, zakres użytkownika lub organizacji, odcisk istotnych danych, stan i wynik. Ta sama nazwa klucza nie powinna pozwalać jednemu klientowi odczytać rezultatu innego.

Jeśli klient ponawia klucz z innymi danymi, odrzuć konflikt. Nie zwracaj po cichu wyniku poprzedniej operacji, gdy żądanie dotyczy już innej kwoty lub odbiorcy.

Sytuacja Oczekiwane zachowanie
Nowy klucz wykonaj i zapisz rezultat
Ten sam klucz i dane zwróć zapisany rezultat
Ten sam klucz, inne dane zgłoś konflikt
Operacja w trakcie zastosuj jawnie ustaloną politykę oczekiwania lub ponowienia

Określ czas przechowywania kluczy. Po jego upływie klient nie może zakładać, że bardzo stare ponowienie zostanie rozpoznane. Retencja jest częścią kontraktu, nie tylko optymalizacją tabeli.

Mały przykład z SQLite

Poniższy moduł zmienia jeden licznik i zapisuje wynik operacji w tej samej bazie. To demonstracja dla zaufanego lokalnego wywołującego, bez warstwy użytkowników i HTTP.

import sqlite3

def setup(db):
    db.executescript('''
        CREATE TABLE IF NOT EXISTS counter(id INTEGER PRIMARY KEY, value INTEGER NOT NULL);
        INSERT OR IGNORE INTO counter VALUES (1, 0);
        CREATE TABLE IF NOT EXISTS operations(
            key TEXT PRIMARY KEY, delta INTEGER NOT NULL, result INTEGER NOT NULL);
    ''')

def apply_once(db, key, delta):
    if not isinstance(key, str) or not 1 <= len(key) <= 100 or type(delta) is not int:
        raise ValueError('Invalid operation')
    db.execute('BEGIN IMMEDIATE')
    try:
        old = db.execute('SELECT delta, result FROM operations WHERE key=?', (key,)).fetchone()
        if old:
            if old[0] != delta:
                raise ValueError('Key reused with a different payload')
            result = old[1]
        else:
            db.execute('UPDATE counter SET value=value+? WHERE id=1', (delta,))
            result = db.execute('SELECT value FROM counter WHERE id=1').fetchone()[0]
            db.execute('INSERT INTO operations VALUES (?, ?, ?)', (key, delta, result))
        db.commit()
        return result
    except Exception:
        db.rollback()
        raise

Zapisz jako ledger.py. Użycie:

import sqlite3
from ledger import setup, apply_once

db = sqlite3.connect('demo.db')
setup(db)
print(apply_once(db, 'job-001', 10))
print(apply_once(db, 'job-001', 10))
db.close()

W świeżej bazie oba wywołania zwrócą 10, a licznik wzrośnie tylko raz. Klucz wskazuje ten sam rezultat również wtedy, gdy inne późniejsze zadanie zmieniło już bieżącą wartość licznika.

BEGIN IMMEDIATE rozpoczyna transakcję z zamiarem zapisu. Może napotkać zajętą bazę, co trzeba obsłużyć w aplikacji. Nie jest mechanizmem nieograniczonej równoległości ani zamiennikiem kolejki.

Dlaczego wszystko musi być atomowe

Gdy najpierw zmienisz licznik, a dopiero potem zapiszesz klucz w osobnym zatwierdzeniu, awaria między tymi krokami pozostawi zmianę bez dowodu wykonania. Ponowienie doda wartość drugi raz.

W przykładzie zmiana i rejestr operacji należą do jednej transakcji. Wyjątek wycofuje jej niezakończony zapis. Nie wywołuj funkcji wewnątrz innej aktywnej transakcji bez przeprojektowania zarządzania połączeniem.

Test objął pierwszą zmianę, ponowienie, konflikt danych oraz kolejny klucz. Potwierdzono, że konflikt nie zwiększa licznika. To test lokalnego mechanizmu, a nie gwarancja dla dowolnego rozproszonego systemu płatności.

Przy większej bazie możesz użyć podobnego wzorca z unikalnym ograniczeniem i właściwymi blokadami. Przykładowe środowisko omawia PostgreSQL w Dockerze.

Zewnętrzny skutek komplikuje transakcję

Lokalna transakcja SQLite nie obejmuje wysyłki maila ani żądania do innej usługi. Jeśli zapiszesz sukces przed wysyłką, możesz zgubić wiadomość. Jeśli wyślesz przed zapisem, możesz ją powtórzyć.

Wzorzec outbox zapisuje zlecenie wysyłki razem ze zmianą danych. Osobny proces obsługuje oczekujące pozycje. Nadal potrzebna jest strategia dla niejednoznacznego wyniku po stronie odbiorcy, najlepiej jego własna deduplikacja lub klucz idempotencji.

Nie opisuj outboxa jako automatycznej gwarancji dokładnie jednego skutku w całym internecie. Pozwala uporządkować lokalny zapis i ponawianie, ale nie usuwa granic między systemami.

Przykład rozdzielenia zapisu publikacji od dalszego dostarczenia znajdziesz w agregowaniu RSS.

Jak testować przypadki awarii

Przygotuj ponowienie tych samych danych, zmianę danych pod jednym kluczem i równoczesne żądania. Dodaj przerwanie przed zatwierdzeniem oraz utratę odpowiedzi po zatwierdzeniu.

Sprawdź również restart procesu. Klucze trzymane wyłącznie w pamięci znikną, więc ochrona zakończy się wraz z aplikacją. Repozytorium testów powinno zawierać oczekiwany stan danych, a nie tylko kod odpowiedzi HTTP.

Zapisuj identyfikator operacji w logach, ale nie pełne poufne dane. Dzięki temu połączysz kilka prób. Pomaga w tym monitorowanie automatyzacji.

Idempotencja nie zastępuje kontroli dostępu

Poprawny klucz nie uprawnia do wykonania operacji. Najpierw ustal tożsamość, zakres danych i dozwoloną zmianę. Dopiero w tym kontekście sprawdzaj rejestr ponowień.

Timeout oraz HTTP 429 również wymagają własnej obsługi. Idempotencja ułatwia bezpieczniejsze ponawianie zadań, a rate limit określa tempo kolejnych prób.

Najczęstsze pytania

Jak długo przechowywać klucz idempotencji?

Co najmniej przez uzgodnione okno ponowień. Termin powinien wynikać z kontraktu i ryzyka starej operacji.

Dlaczego wyłączenie przycisku nie wystarcza?

Duplikat może pochodzić z timeoutu, kolejki lub ponowienia procesu. Ochrona musi działać po stronie wykonującej zapis.

Co zrobić z tym samym kluczem i inną treścią?

Odrzucić konflikt zgodnie z kontraktem. Nie wykonywać nowej operacji pod starym identyfikatorem.

Czy przykład zabezpiecza wysyłkę maila?

Nie. Obejmuje wyłącznie dane w jednej transakcji SQLite. Zewnętrzny skutek wymaga osobnego projektu.

Źródła

Data publikacji: 20.11.2026.

KP
O AUTORZE

Krystian Proć

Tworzę narzędzia do pracy z danymi, systemy backendowe i automatyzacje. Pracuję z SQL, PHP, TypeScriptem i Dockerem; rozwijam m.in. dragon-island.com. AI pomaga mi przyspieszać pracę, a architekturę, weryfikację i decyzje techniczne biorę na siebie. Na Trybie Technicznym dzielę się doświadczeniami z budowania i utrzymywania własnych projektów.

Dyskusja

Dodaj komentarz

Twój adres email nie zostanie opublikowany. Wymagane pola są oznaczone *