Как обеспечить идемпотентность метода в @RestController

# Идемпотентность REST API методов

Идемпотентность означает, что повторное выполнение операции с тем же параметром дает тот же результат, что и при первом выполнении. Это критично для надежного API, особенно при работе с платежами, заказами и другими критичными операциями.

1. Понимание идемпотентности

// ❌ НЕ идемпотентный метод
@PostMapping("/accounts/{id}/balance/add")
public void addBalance(@PathVariable Long id, @RequestParam BigDecimal amount) {
    Account account = accountService.getAccount(id);
    // Если клиент отправит запрос дважды, баланс увеличится дважды
    account.setBalance(account.getBalance().add(amount));
    accountService.save(account);
}

// ✅ Идемпотентный метод
@PostMapping("/accounts/{id}/balance")
public void setBalance(@PathVariable Long id, @RequestBody SetBalanceRequest request) {
    // Независимо от количества повторов, баланс будет установлен на одно значение
    Account account = accountService.getAccount(id);
    account.setBalance(request.getAmount());
    accountService.save(account);
}

2. Стратегия 1: Идемпотентный ключ (Idempotency Key)

Это самый надежный способ. Клиент генерирует уникальный ключ, сервер отслеживает обработанные запросы.

Реализация

// Сущность для хранения результатов идемпотентных операций
@Entity
@Table(name = "idempotent_requests")
public class IdempotentRequest {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    
    @Column(nullable = false, unique = true, length = 100)
    private String idempotencyKey;  // UUID от клиента
    
    @Column(nullable = false, columnDefinition = "TEXT")
    private String requestBody;  // JSON запроса
    
    @Column(nullable = false, columnDefinition = "TEXT")
    private String responseBody;  // JSON ответа
    
    @Column(nullable = false)
    private LocalDateTime createdAt;
    
    @Column(nullable = false)
    private Integer httpStatus;
    
    public IdempotentRequest(String idempotencyKey, String requestBody, 
                            String responseBody, Integer httpStatus) {
        this.idempotencyKey = idempotencyKey;
        this.requestBody = requestBody;
        this.responseBody = responseBody;
        this.httpStatus = httpStatus;
        this.createdAt = LocalDateTime.now(UTC);
    }
}

3. Стратегия 2: На основе уникального ресурса

Для операций, которые изменяют ресурс, используй PUT вместо POST.

// Вместо POST
@PostMapping("/accounts/{id}/balance/set")
public void addBalance(...) { }

// Используй PUT
@PutMapping("/accounts/{id}/balance")
public ResponseEntity<AccountResponse> updateBalance(
        @PathVariable Long id,
        @RequestBody SetBalanceRequest request) {
    
    // PUT идемпотентный по определению
    Account account = accountService.getAccount(id);
    account.setBalance(request.getAmount());
    accountService.save(account);
    
    return ResponseEntity.ok(AccountResponse.from(account));
}

4. Стратегия 3: Версионирование сущности (Optimistic Locking)

Используется для предотвращения race conditions и обеспечения идемпотентности.

@Entity
@Table(name = "accounts")
public class Account {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    
    private BigDecimal balance;
    
    // Версия для оптимистичной блокировки
    @Version
    private Long version;
}

@Service
public class AccountService {
    private final AccountRepository repository;
    
    @Transactional
    public void transferMoney(Long fromId, Long toId, BigDecimal amount) {
        Account from = repository.findById(fromId).orElseThrow();
        Account to = repository.findById(toId).orElseThrow();
        
        from.setBalance(from.getBalance().subtract(amount));
        to.setBalance(to.getBalance().add(amount));
        
        repository.save(from);
        repository.save(to);
    }
}

5. Сравнение подходов

6. Best Practices

// ✅ REST API Best Practices

// 1. POST (не идемпотентный) — создание нового ресурса
@PostMapping("/orders")  // Каждый вызов создает новый заказ
public void createOrder() { }

// 2. PUT (идемпотентный) — полное обновление
@PutMapping("/orders/{id}")  // Несколько вызовов = один результат
public void updateOrder(@PathVariable Long id) { }

// 3. DELETE (идемпотентный) — удаление
@DeleteMapping("/orders/{id}")  // Несколько удалений = удален
public void deleteOrder(@PathVariable Long id) { }

// 4. GET (идемпотентный, безопасный) — чтение
@GetMapping("/orders/{id}")  // Только читает, не изменяет
public void getOrder(@PathVariable Long id) { }

// ✅ Используй Idempotency-Key для критичных POST операций
@PostMapping("/transfers")
public void transfer(
        @RequestBody TransferRequest request,
        @RequestHeader("Idempotency-Key") String idempotencyKey) {
    // Обработка с сохранением идемпотентности
}

7. Выводы

1. Для POST запросов используй Idempotency-Key
2. Для обновлений используй PUT вместо POST
3. Для конкурентных операций используй @Version
4. Тестируй идемпотентность — отправляй запрос дважды
5. Документируй в OpenAPI/Swagger
6. Для платежей особенно важна надежная реализация идемпотентности