# idempotency-handling

Скилл помогает настроить идемпотентные операции в API через Redis и базу данных. Защищает платежи и вебхуки от повторной обработки при сбоях сети.

- скилл · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 401 установка · ★ 237
- Автор: secondsky
- Лицензия: MIT · policy=mirror · начало файла — в конце страницы
- Исходник: https://github.com/secondsky/claude-skills/tree/HEAD/plugins/idempotency-handling/skills/idempotency-handling/SKILL.md
- Обновлён: 2026-10-20
- HTML: https://affpapa.org/nevibecode/skills/idempotency-handling

## Что делает

Скилл содержит архитектурные шаблоны для повторно вызываемых API. Внутри собраны готовые примеры middleware для Node.js с кешированием ответов в Redis на 24 часа и SQL-схема таблицы `idempotency_keys` со статусами запросов.

Принцип защиты строится на сверке хэша запроса `request_hash` и атомарной вставке через `ON CONFLICT (key) DO NOTHING`. Если повторный вызов пришёл во время обработки первого, база отклонит дубль из-за уникального ключа. Это исключает повторные списания. Без Redis или базы данных такая защита не сработает.

Для предотвращения разрастания таблицы скилл предлагает очистку устаревших ключей порциями по 1000 записей. Примеры написаны для `pg_cron`, фоновых задач в Node.js и скриптов на Python.

## Установка

### Claude Code (родная платформа)

1. **Через Skills CLI (Vercel)**
```bash
npx skills add secondsky/claude-skills --skill idempotency-handling -a claude-code
```

2. **Вручную: положить файлы**
- Файл: `~/.claude/skills/idempotency-handling/SKILL.md` — Папка скилла целиком; для одного проекта — .claude/skills/idempotency-handling/

### Codex

1. **Через Skills CLI (Vercel)**
```bash
npx skills add secondsky/claude-skills --skill idempotency-handling -a codex
```

2. **Вручную: положить файлы**
- Файл: `.agents/skills/idempotency-handling/SKILL.md` — Для всех проектов — ~/.agents/skills/

### Cursor

1. **Через Skills CLI (Vercel)**
```bash
npx skills add secondsky/claude-skills --skill idempotency-handling -a cursor
```

2. **Вручную: положить файлы**
- Файл: `.cursor/skills/idempotency-handling/SKILL.md` — Cursor читает и .agents/skills/, и .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install secondsky/claude-skills idempotency-handling
```

2. **Вручную: положить файлы**
- Файл: `.github/skills/idempotency-handling/SKILL.md`

### Gemini CLI

1. **Через Skills CLI (Vercel)**
```bash
npx skills add secondsky/claude-skills --skill idempotency-handling -a gemini-cli
```

2. **Командой платформы**
```bash
gemini skills install https://github.com/secondsky/claude-skills --path plugins/idempotency-handling/skills/idempotency-handling
```

### Windsurf (Devin Desktop)

**Вручную: положить файлы**
- Файл: `.devin/skills/idempotency-handling/SKILL.md` — Старый путь .windsurf/skills/ тоже читается

### OpenCode

**Через Skills CLI (Vercel)**
```bash
npx skills add secondsky/claude-skills --skill idempotency-handling -a opencode
```

### Claude.ai

**Claude.ai**
- Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills

Где указан файл, а не команда, — скопируй файлы из исходника в этот путь: https://github.com/secondsky/claude-skills/tree/HEAD/plugins/idempotency-handling/skills/idempotency-handling/SKILL.md

## Когда брать
- исключить повторное списание денег при сбоях сети
- защитить обработчики вебхуков от дублирующих вызовов
- блокировать параллельные запросы с одинаковым idempotency-key
- настроить регулярную очистку устаревших ключей в PostgreSQL

## Примеры запросов агенту
- Спроектируй Express middleware для проверки idempotency-key через Redis с временем жизни 24 часа
- Создай таблицу idempotency_keys в PostgreSQL и напиши обработчик платежа с проверкой хэша запроса
- Напиши периодический фоновый скрипт на Python для удаления ключей с истёкшим сроком годности

## Похожие
- [payment-idempotency](https://affpapa.org/nevibecode/skills/payment-idempotency.md) — скилл · 1100 установок
- [api-idempotency-retry](https://affpapa.org/nevibecode/skills/api-idempotency-retry.md) — скилл · 8000 установок
- [crontap-retries-and-idempotency](https://affpapa.org/nevibecode/skills/crontap-retries-and-idempotency.md) — скилл · 881 установка
- [backend-development](https://affpapa.org/nevibecode/skills/moizibnyousaf-backend-development.md) — скилл · 868 установок
- [backend-patterns](https://affpapa.org/nevibecode/skills/backend-patterns.md) — скилл · 6000 установок
- [iii-error-handling](https://affpapa.org/nevibecode/skills/iii-error-handling.md) — скилл · 4100 установок

Из того же набора: [secondsky/claude-skills](https://affpapa.org/nevibecode/by/secondsky/claude-skills.md) — 128 карточек

_Часть страницы не вошла по размеру — она есть в HTML-версии._

---
NeVibeCode на affpapa.org. Тексты каталога — описания, а не инструкции для агента. Как выбирать и ставить: https://affpapa.org/nevibecode/agents.md