# ページング API で「全件取れているつもり」で大半を取りこぼす事故と、その検出方法 ## 1. 何が起きたか 認証必須の社内 `` から全ページを取得するツールを書きました。総件数は `<一覧エンドポイント>` が `totalCount` として返しており、**6,902 件**です。 実装は「1 回のリクエストで 500 件ずつ取得し、`offset` を 500 ずつ進める」という素直なループでした。単体テストは全て緑、CI も緑、ローカル実行も緑。 ところが本番で実行したところ、**実際に取れていたのは 280 件だけ**でした。取得率にして **約 4%**。エラーは一切出ておらず、ツールは正常終了していました。 ## 2. 原因 `<一覧エンドポイント>` は **`limit` パラメータを完全に無視し、常に 20 件だけ返す**仕様でした。実測値は次のとおりです。 | 要求 | 実際の返却件数 | |---|---| | `limit=100&offset=0` | 20 | | `limit=500&offset=0` | 20 | | `limit=100&offset=1000` | 20 | 一方、実装側は `offset += limit`（＝500）で進めていました。つまり **1 回のリクエストごとに 480 件を読み飛ばしていた**ことになります。 計算すると `6902 / 500 ≒ 14 反復 × 20 件 = 280 件` となり、実測値と完全に一致します。取得漏れは「たまたま」ではなく、この構造から必然的に生じていました。 ## 3. なぜテストで捕まらなかったのか ここが本題です。テスト用のモック HTTP サーバが、**「要求された `limit` の件数をきちんと返す」お行儀のよい実装**になっていました。 そのため、テストは「実装が正しいか」ではなく **「モックが想定どおり振る舞うか」を検証していただけ**でした。本番の意地悪な挙動（`limit` を無視する）を再現できていなかったので、壊れているのに全部緑、という状態が成立していました。 モックが行儀よすぎると、テストは実装を検証せず**自分の前提を検証しているだけ**になります。 ## 4. 修正 1. **`offset += 実際に返ってきた件数`** にする。要求した `limit` は信用しない 2. **返却 0 件で終了**する。加えて**進捗が止まったら中断**するガードを入れる（同じ結果を返し続けるサーバで無限ループになるため） 3. 取得済み ID の Set で**重複排除**する（一覧が更新順などの可変順序だと、同じ項目が別のページで再登場する） 4. **取得後に必ず `totalCount` と突き合わせ、一致しなければ警告を出す**。今回これで気づけました。数を数えない実装は、静かに壊れたまま動き続けます 擬似コードにすると次のようになります。 ``` seen = Set() offset = 0 while true: batch = fetch(offset, limit=500) # limit は「お願い」にすぎない if batch.length == 0: break new_items = batch.filter(x => not seen.has(x.id)) if new_items.length == 0: break # 進捗が止まった → 中断 for x in new_items: seen.add(x.id) offset += batch.length # 要求値ではなく実返却件数で進める if seen.size != totalCount: warn("取得件数が総数と一致しません: {seen.size} / {totalCount}") ``` ## 5. 再発防止のモック設計 - モックは**本番の意地悪さを再現する**。「`limit` を無視して常に N 件返す」モックを 1 本用意する - 総数は `20` で割り切れない数（例: 130）にして、**端数の扱い**も検証する - 検証項目は次の 3 つ - 収集件数 == `totalCount` - 重複 0 件 - 期待する ID の全集合と一致 - **修正前の実装でそのテストが落ちること**まで必ず確認する（落ちないテストは意味がない） - 「並び順が動くサーバ」のモックも用意し、複数パスで収束することを確認する ## 6. チェックリスト - [ ] `offset` は**実際に返ってきた件数**で進めている（要求した `limit` で進めていない） - [ ] 返却 0 件で終了し、**進捗が止まったら中断**するガードがある - [ ] 取得済み ID の Set で**重複排除**している - [ ] 取得後に **`totalCount` と突き合わせ**、不一致なら警告を出している - [ ] モックに「**`limit` を無視して常に N 件返す**」意地悪なケースがある - [ ] 総数が割り切れない値（端数あり）でテストしている - [ ] **修正前の実装でそのテストが落ちる**ことを確認済み ## 7. 一般化した教訓 - ページング実装は「サーバが仕様どおり振る舞う」前提で書くと静かに壊れる - **総数と突き合わせない取得処理は、壊れても気づけない** - モックが行儀よすぎると、テストは実装を検証せず**自分の前提を検証しているだけ**になる ---