カーソルベース API のデータを結合するページネーション設計

こんにちは。メルコインのフロントエンド（FE）エンジニアとしてインターンをしている@nanacomです。この記事は「Merpay & Mercoin Tech Openness Month 2026」の7日目の記事です。

はじめに

インターンでは FE に限らず、要件定義からバックエンド（BE）開発まで、1 つのプロジェクトに幅広く取り組みました。その中で、メルコインの社内ツールを開発する際に、2 つの API の結果を日時降順にマージして返すエンドポイントを実装するケースに直面しました。

結果を結合して並べ替えるだけならシンプルですが、マージした一覧にもページネーションを提供しようとすると、各ソースのカーソルをどこまで進めるべきかが複雑になります。本記事では、「マージ結果として採用された件数」と「各データソース側で進めるべきカーソル」のズレにどう対処したかを紹介します。具体的には、データ取得とカーソル確定を分離する「2 フェーズ取得パターン」と、各ソースのカーソルを 1 つのトークンに束ねる「複合ページネーション トークン」の 2 つの設計を取り上げます。

前提：対象とするユースケース

マイクロサービスアーキテクチャでは、BFF（Backend For Frontend）で複数のサービスからデータを集約して一覧表示することがよくあります。今回対象としたのは、2 つの独立したデータソース（A, B）のデータをマージするケースです。いずれも日時降順にソートされたデータを返し、それぞれがカーソルベースのページネーション API を提供しています。カーソルベースのページネーションとは、前回の取得結果の末尾を示すトークン（カーソル）を次のリクエストに渡すことで、続きのデータを取得する方式です。

この 2 つのソースの結果を日時降順にマージした一覧をクライアントに返しつつ、その一覧自体にもページネーションを提供する必要がありました。つまり、各ソースが独立して管理するカーソルを、BFF 側でどう扱うかが設計上の焦点でした。

image売買と入出金をマージした一覧表示（※表示データはすべてダミーです）

素朴なアプローチとその限界

この設計上の焦点に対して、私たちはまず 2 つの素朴なアプローチを検討しました。いずれも限界があり、最終的な設計への動機となりました。

アプローチ 1：全件取得してソート

最も単純な方法は、両ソースから全件を取得し、アプリケーション側でソートしてからページごとに切り出す方法です。しかし、データ数が増えるとメモリ使用量とレイテンシーが線形に増加するため、スケールしません。

アプローチ 2：各ソースから pageSize 件取得してマージ

各ソースからそれぞれ pageSize 件を取得し、マージして上位 pageSize 件を選択する方法です。データ取得量を抑えられるため現実的ですが、ここで 1 つの問題が発生します。

例として、pageSize=5 のとき、A から [A1..A5]、B から [B1..B5] が返ってきたとします（いずれも日時降順）。これらをマージして上位 5 件を作ると、マージ結果に含まれるのが A から 3 件（A1,A2,A3）、B から 2 件（B1,B2）になるとします。

次のページでは本来、A は A4 から、B は B3 から取得を再開する必要があります。しかし各ソース API が返すカーソルは「返却リスト末尾の次」を指すため、手元のカーソルは A6（= A を 5 件進めた次）や B6（= B を 5 件進めた次）を指してしまいます。マージ結果に必要な再開位置（A4/B3）と、手元のカーソル（A6/B6）が一致しません。

（図 1）各ソースから取得 (pageSize=5)

Source A: [A1][A2][A3][A4][A5] -> cursorA = A6

Source B: [B1][B2][B3][B4][B5] -> cursorB = B6

マージして上位 5 件を採用すると、実際に消費したのは A が 3 件 / B が 2 件 になります（採用：A1 A2 A3 / B1 B2）。

このとき次ページで「本当に再開したい位置」と「手元のカーソル」がズレます。

ソース

次ページで本当は

手元のカーソル

A

A4 から再開

A6 を指す

B

B3 から再開

B6 を指す

これが、本記事で解決する核心的な課題です。次のセクションでは、この課題に対して理想的にはどう解決すべきかを考え、そのうえで私たちが採った設計方針を説明します。

理想の解決策と現実の制約

カーソルベース API では、返却件数とカーソルの進行量が常に一致します。pageSize=5 でリクエストすれば 5 件返り、カーソルも 5 件分進みます。しかし今回のように複数ソースのデータをマージするケースでは、5 件取得しても実際に採用するのは一部だけです。この「取得件数」と「消費件数」のズレが根本原因です。

仮に各ソースの API がカーソルではなくタイムスタンプによる範囲指定をサポートしており、かつソース内のタイムスタンプが一意であれば、この問題は発生しません。例えば、以下のように、マージ結果で最後に消費したアイテムの日時を基準に次ページを取得できます。

GET /orders?before=2025-01-01T10:00:00Z&limit=5

GET /transfers?before=2025-01-01T10:00:00Z&limit=5

この方式であれば、各ソースの消費済み最終タイムスタンプを 1 つのトークンに含めるだけで、BFF 側に状態を持たずに 1 回のリクエストでページネーションを実現できます。また before で過去方向に切るため、新しいデータが追加されてもページ跨ぎの重複が起きません。

しかし、各マイクロサービスの API 仕様を変更するのは現実的ではないため、既存仕様のまま BFF 層で解決する方法を検討しました。

設計方針の決定

BFF 層での解決策として、トークンへの情報埋め込み、サーバー側キャッシュ、データ取得とカーソル確定の分離という 3 つの方法を検討しました。設計のシンプルさとステートレス性を重視した結果、3 つ目の「2 フェーズ取得」方式を採用しました。

方法 1：トークンに情報を詰め込む（拡張複合トークン）

各ソースのカーソルを1つのトークンに束ねて返す際に、カーソルだけでなく、次ページを再開するために必要な情報をまるごとトークン内に埋め込む設計です。例えば「Aから何件/Bから何件消費したか」のようなメタ情報も含め、JSON にまとめて Base64 エンコードして返します。

{

"cursorA": "abc123",

"cursorB": "def456",

"consumedA": 3,

"consumedB": 2

}

この方式だと、クライアントが次のリクエストでトークンをそのまま返すことで、サーバーはトークンをデコードするだけで「次ページの再開位置（A4/B3 など）」を復元できます。

しかし、既存のソース API がカーソルベースの仕組みを提供している中で独自にオフセット等も管理すると、「カーソルの意味」が二重になり設計が複雑化するため、採用しませんでした。

方法2：Redis などで「使わなかったデータ」を保持する（サーバー側キャッシュ）

各ソースから pageSize 件ずつ取得してマージした結果、採用されなかった"余り"のデータ（例：A4, A5 / B3, B4, B5）をサーバー側で保持しておく設計です。例えばユーザー（またはリクエスト）単位のセッションキーで Redis に格納します。

session:user123 → {

unusedA: [A4, A5],

unusedB: [B3, B4, B5]

}

次のページのリクエストが来たら、

• まず Redis に残っているデータを先に使ってマージし

• 足りない分だけ各ソース API から追加取得する

という流れにすれば、カーソルのズレ問題を回避できます。

しかし、サーバー側に状態を持つことになり、社内ツールの規模に対してインフラの運用コストが見合わないため、採用しませんでした。

方法3（採用）：データ取得とカーソル確定を分離する（2 フェーズ取得）

上記2つの方法では、1回の API 呼び出しでデータ取得とカーソル確定を同時に済ませようとしています。発想を変え、データを取得してマージするフェーズと、消費件数に基づいてカーソルを確定するフェーズを分けることで、この問題を解決します。サーバーはステートレスのまま、既存 API の仕組みをそのまま活かせます。API 呼び出し回数は増えますが、最もシンプルな設計です。

許容するトレードオフ

ただし、この方式では2回の API 呼び出しの間に多少の時間差が生じます。そのわずかな間に対象データが追加された場合、次ページに重複したデータが現れる可能性があります。

私たちはこの問題を、以下の理由から許容可能なトレードオフと判断しました。

• 影響は「ページを跨ぐ際の重複表示」に限定される

• 対象がリアルタイムに頻繁に更新されるデータではないため、発生頻度は低い

• 完全な整合性を保証するには、各ソースの API 仕様変更が必要になり、コストに見合わない

この判断のもと、以降のセクションで方法3の具体的な実装を説明します。

2 フェーズ取得パターン

前のセクションで述べた方法3を、具体的にどう実装したかを説明します。データを取得してマージするフェーズと、消費件数に対応するカーソルを確定するフェーズに分けて設計しました。

フェーズ1：取得とマージ

• ソースA、ソースBからそれぞれ pageSize 件を並行して取得する

• 日時降順でマージし、合計 pageSize 件を取り出す
• ソース A とソース B それぞれで、実際に消費した件数を記録する

この処理は、Go の container/heap を使ったストリーミングマージとして実装できます。各ソースの先頭要素をヒープに入れ、日時が最も新しいものを 1 つずつ取り出しながら pageSize 件を集めます。以下のコードのとおり、各ソースのインデックス（indexA, indexB）がそのまま消費件数を表します。

func Merge(pageSize int32, itemsA, itemsB []*Item) ([]*Item, int32, int32) {

indexA, indexB := 0, 0

result := []*Item{}

h := &timeHeap{}

heap.Init(h)

if len(itemsA) > 0 {

heap.Push(h, &record{source: SourceA, time: itemsA[0].Timestamp})

}

if len(itemsB) > 0 {

heap.Push(h, &record{source: SourceB, time: itemsB[0].Timestamp})

}

for h.Len() > 0 && len(result) < int(pageSize) {

item := heap.Pop(h).(*record)

result = append(result, item.item)

if item.source == SourceA {

indexA++

} else {

indexB++

}

}

return result, indexA, indexB

}

戻り値の indexA と indexB が、フェーズ 2 でカーソルを正確に進めるための入力になります。

フェーズ 2：カーソルの確定

• ソース A、ソース B それぞれにおいて、フェーズ 1 と同じ開始位置から消費件数分だけ再取得し、進んだ位置のページネーショントークンを取得する（cursorA, cursorB）
• pageToken を cursorA:cursorB（参照：次のセクション）とすることで、次ページの取得時に正しい位置からデータを取得できる

なお、一方のソースのデータがもう一方より古い場合など、フェーズ 1 でデータが返ってきたにもかかわらずマージで 1 件も採用されないケースがあります。この場合は、そのソースのカーソルを前回の位置のまま保持し、次ページのリクエストで再び同じデータを取得してマージの対象にします。また、フェーズ 1 でデータが 0 件だった場合は、そのソースを枯渇と判定し、ターミナルトークン _ を設定します。

（図 2）フェーズ 1：取得とマージ（消費件数を記録）

Source A ──(pageSize 件)──┐

├→ Merge → Top N

Source B ──(pageSize 件)──┘

│

消費件数を記録

(A=3 件，B=2 件)

（図 3）フェーズ 2：カーソルの確定（消費件数分だけ進める）

Source A ──(消費 3 件)──→ cursorA

Source B ──(消費 2 件)──→ cursorB

→ 複合トークン: "cursorA:cursorB"

複合ページネーショントークン設計

2 フェーズ取得パターンにより、各ソースで消費件数分だけ進んだカーソルを取得できるようになりました。次に、これらのカーソルをクライアントにどのように渡すかを設計します。今回の一覧取得 API では、pageToken を各ソースのカーソルを結合した複合トークンとして設計します。

"cursorA:cursorB"

片方のソースが完全に尽きた場合は、ターミナルトークン _ で表現します。トークンがターミナルトークン _ だった場合、API 呼び出しをスキップできます。これにより、初回リクエストから片方のソースが枯渇した状態まで、以下のようにページネーショントークンで表現することができます。

トークン 意味

"" (空文字) 初回リクエスト

"cursorA:cursorB" 両ソースとも継続あり

"_:cursorB" ソース A は枯渇、B のみ継続

"cursorA:_" ソース B は枯渇、A のみ継続

"_:__" → "" に変換 全データ取得済み（次ページなし）

この複合トークンと 2 フェーズ取得パターンを組み合わせることで、サーバー側に状態を持たずに、マージした一覧のページネーションを実現できます。

まとめ

本記事では、カーソルベース API を持つ複数データソースから一覧を構築する際に直面した「マージで実際に消費した件数」と「API が返すカーソル位置」のズレという課題と、その解決策を紹介しました。

最初は 1 回の API 呼び出しで全てを済ませようとしていましたが行き詰まり、「データを取得するフェーズ」と「カーソルを確定するフェーズ」に分離することで解決できました。1 つの処理が複数の責務を担って複雑になったとき、フェーズを分けて各ステップの役割を単純化するアプローチは、ページネーションに限らず設計全般で有効な考え方だと感じています。

このような設計上のトレードオフを実際に手を動かしながら考えられたのは、インターン期間中の貴重な経験でした。FE に限らず幅広く関わらせていただいたことに感謝しています。本当にありがとうございました！

次の記事は＠mikupo さんです。引き続きお楽しみください。