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
- Idempotentne metody HTTP, IETF.
- Transakcje, SQLite.
- Ograniczenia tabel, SQLite.
- Obsługa SQLite, Python Documentation.
- Przykład kontraktu kluczy idempotencji, Stripe.
- Transactional outbox, AWS.
Data publikacji: 20.11.2026.

Dyskusja