{"canonical_url":"https://engineer.company/ja/glossary/idempotent/","content_markdown":"# 冪等\n\n## どのようなものか\n\nある操作を何度実行しても、一度実行したのと効果が同じなら、冪等であるといいます。この性質を冪等性（idempotence、idempotency）と呼びます。数学に由来する言葉で、関数をその結果へ再び適用しても変わらず、f(f(x))がf(x)と等しくなる場合を指します。すでに切り下げた数を、もう一度切り下げても、同じ数になります。\n\nソフトウェアでは、二回目を試すと分かりやすくなります。値を設定する操作は、二回目も、すでにある値を書くため冪等です。値へ加える操作は、再び加えるため、そうではありません。\n\n```sql\n-- 冪等：2回目も同じ値を設定する\nUPDATE accounts SET plan = 'pro' WHERE id = 42;\n\n-- 非冪等：2回目にさらに10を加える\nUPDATE accounts SET credits = credits + 10 WHERE id = 42;\n```\n\nHTTPが、この言葉を最も厳密に定義します。RFC 9110は、複数の同一要求を送ったときの、意図されたサーバーへの効果が、一回だけ送ったときと同じなら、そのメソッドを冪等とし、PUT、DELETE、安全なメソッドGET、HEAD、OPTIONS、TRACEを挙げます。定義には、重要な細部が二つあります。対象は、クライアントが求めた効果なので、サーバーは、各要求を別々に記録しても構いません。また、応答は変わっても構いません。同じリソースへの二回目のDELETEが、最初の200に対し404を返しても、どちらもリソースがなくなるため、冪等です。PATCHは一覧の外です。RFC 5789は、安全でも冪等でもないとしますが、クライアントは、If-Matchヘッダーへ強いETagを付けて条件付きにすることで、特定のPATCHを冪等に送れます。一回目がリソースを変えた後では、繰り返したコピーを拒否するためです。\n\n二つの約束のうち、安全のほうが厳しいものです。RFC 9110でいう安全なメソッドは、本質的に読み取り専用です。そのため、すべての安全なメソッドは冪等ですが、DELETEは、安全でなくても冪等です。\n\n## なぜ重要なのか\n\nネットワークは、応答を失います。クライアントが要求を送り、応答前に接続が切れると、サーバーが要求を一度も見ていないのか、見て止まったのか、実行して返答を失ったのか、区別できません。自然な復旧は再送であり、それを無害にするのが冪等性です。RFC 9110は、まさにそこへ再試行規則を置きます。通信障害後、冪等な要求は自動で繰り返せます。クライアントは、冪等でない要求を自動で再試行するべきではありません。ただし、実際には冪等と分かっているか、元の要求が一度も適用されていないと判断できる場合は除きます。プロキシーは、自らそのような再試行をしてはなりません。\n\nキューでは、同じ問いが大規模に起きます。多くのメッセージシステムが約束するのは、少なくとも一回の配信です。処理を済ませ、受領確認を返す前に処理側がクラッシュすると、同じメッセージを再び渡されます。ネットワーク越しに厳密に一回だけ配信するのは、はるかに難しい約束なので、実用上の答えは、二回目の配信でも変化しない処理側を作ることです。構成管理も、この性質に依存します。サーバーを宣言した状態へ整えるツールは、変更のたびに、しばしば定期的にも、繰り返し動きます。各回は、すでに正しいサーバーを、見つけたとおりの状態に保つ必要があります。\n\n本当に決めるべきなのは、本来冪等でない操作へ、この性質をどう与えるかです。一般的な答えは三つあります。第一は設計です。「この行を追記する」ではなく、「ファイルにこの行があることを保証する」のように、手順ではなく目標状態で変更を表します。第二はキーです。クライアントが一意な識別子を要求へ付け、サーバーは一意制約の下で記録し、繰り返しには、もう一度実行せず、記録を見つけて元の結果を返します。第三は、動く前に確認する方法です。Ansibleの大半のモジュールは、現在の状態と望む状態を比較し、一致すれば何もせず終了します。どれにも費用があります。目標状態の設計には、最終状態の明確なモデル、キーには保存領域と保管期間の規則、事前確認には、現在の状態を確実に読む方法が必要です。\n\n## 実際の活用例\n\n会社自身のサーバーはAnsibleで設定し、そのプロジェクトでは、[冪等性を契約とし、収束したホストは変更ゼロを報告します](/ja/portfolio/servers-you-can-rebuild-from-scratch/)。引数なしのプロビジョニングで、すべてのホストを宣言した状態へ収束させます。すでに正しいホストで、変更ゼロを報告できないプレイは、未完成と扱います。そのため、冪等性は、期待するものではなく、毎回測るものになります。\n\n同じ考えをデータへ適用したものが、[十九段階のビルドパイプラインを二回動かすテスト](/ja/portfolio/held-the-generator-to-981-tests-and-92-coverage/)です。事例は、対象とする不具合を挙げます。確認せずに挿入する段階や、先行する段階の出力順へ依存する段階によって、初回は動き、二回目で壊す生成ツールです。テストは、空のファイルからデータベースを構築し、スナップショットを取り、その結果に対してパイプライン全体を再実行します。行数、内容、識別子まで、二回目で何も変わらないことを求めます。このテストは、対象とする入力とデータベースの状態について、繰り返し実行した結果の証拠を示します。\n\n限られた在庫の販売では、[最後のチケットを一回だけ売る](/ja/notes/selling-limited-stock-without-overselling/)という記事が、キーと条件付き書き込みを組み合わせます。各購入手続きに冪等性キーを持たせ、取り置きテーブルに`UNIQUE (tenant_id, idempotency_key)`を置くため、再クリックでは、もう一つ確保せず、すでにある取り置きを返します。タイムアウトと取り消しボタンなどで、解放処理が二回動いても、自身の更新でちょうど一行を変えた場合だけ在庫を戻すので、一個しか戻りません。さらに後の各メッセージ処理側も、注文をキーとして冪等にします。メッセージは少なくとも一回届き、冪等性によって、効果を実質一回にします。\n\n## 問題が起きるところ\n\n**再試行した要求が、二回課金します。** 支払い、注文、メールを作るPOSTは、既定では冪等でなく、クライアントやプロキシーが時間切れ後に再試行すると、二つ目を作ります。サーバーが一意制約の下で保存する冪等性キーを付け、同じキーが戻れば、保存した結果を返します。\n\n**空の結果を、エラーと読みます。** PostgreSQLでは、`INSERT ... ON CONFLICT DO NOTHING`が、一意制約へ違反する行を省き、`RETURNING`は、実際に挿入、更新した行だけを返します。同じ行の挿入を繰り返せば、何も返らず、それが二回目の正しい結果です。空を失敗と扱うコードは、無害な再試行をエラーページへ変えてしまいます。すでにある行を検索するべきです。\n\n**コマンドタスクが、毎回ホストを変えます。** Ansibleの文書は、大半のモジュールが、すでに望む状態かどうかを確かめる一方、「すべてのプレイブックがこのように動くわけではなく、すべてのモジュールがそう動くわけでもない」と説明します。コマンドは任意で、何をするかAnsibleには分からないため、コマンドを動かすタスクが、よくある例外です。commandモジュールの`creates`は、指定ファイルがすでにあれば省き、`removes`は、ファイルがまだある間だけ動かし、`changed_when`は、どの結果を変更と数えるかを定めます。どれもないタスクは、ホストがどんな状態でも、収束処理のたびに再び動きます。\n\n**カウンターが、再試行も数えます。** 少なくとも一回の配信で、メッセージごとにカウンターを増やす、または通知を送る処理側は、二回届いた一件に対して、その処理を二回行います。効果とともに、同じトランザクションで、メッセージの業務上のキーを保存し、すでに保存したキーは省きます。\n\n**二回目が、初回の結果を壊します。** 空のデータベースなら正しくても、データがあると、重複挿入、識別子の振り直し、初回が残した順序への依存で、段階が誤動作する場合があります。何もないところから一度だけ動くテストは、それでも通ります。前述のパイプラインテストのように、ジョブ全体を二回動かし、二回目で何も変わらないことを必須条件にします。\n\n## 参考資料\n\n- [RFC 9110、第9.2.2節：冪等なメソッド](https://www.rfc-editor.org/rfc/rfc9110#name-idempotent-methods)\n  — HTTPの定義、冪等なメソッド、自動再試行の規則です。\n- [RFC 5789：HTTPのPATCHメソッド](https://www.rfc-editor.org/rfc/rfc5789) — PATCHが安全でも冪等でもない理由と、条件付き要求で安全に繰り返せるものにする方法です。\n- [Ansible：プレイブックの紹介](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_intro.html)\n  — Ansible自身の言葉による、望む状態、冪等性、チェックモードです。\n- [Ansible：commandモジュール](https://docs.ansible.com/ansible/latest/collections/ansible/builtin/command_module.html)\n  — コマンドを安全に再実行できるものにする`creates`と`removes`です。\n- [PostgreSQL：INSERT](https://www.postgresql.org/docs/current/sql-insert.html)\n  — `ON CONFLICT`と、行がすでにある場合に`RETURNING`が返すものです。\n\n\u003chttps://engineer.company/ja/glossary/idempotent/\u003e\n","date_modified":"2026-11-12T05:34:23Z","description":"何度実行しても一度と効果が変わらない冪等性を解説します。再試行、再実行、重複メッセージで必要になる理由、安全なHTTPメソッドとの違い、カウンターや挿入、コマンドで崩れる場面も説明します。","formats":{"gemtext":"https://engineer.company/ja/glossary/idempotent/index.gmi","gopher":"https://engineer.company/ja/glossary/idempotent/gophermap","html":"https://engineer.company/ja/glossary/idempotent/","json":"https://engineer.company/ja/glossary/idempotent/index.json","markdown":"https://engineer.company/ja/glossary/idempotent/index.md","pdf":"https://engineer.company/ja/glossary/idempotent/index.pdf"},"kind":"page","language":"ja","title":"冪等とは？","url":"https://engineer.company/ja/glossary/idempotent/","version":1}