ライブラリの API を​消す前に、​使っている​所を​数える:​Netflix の​技術ブログを読む

原文の情報

この記事は Netflix の​技術ブログの​記事を​当サイトが​読んで​解説した​ものです。​Netflix の​公式の​翻訳・​要約ではなく、​Netflix とは関係が​ありません。

原題
Beyond API Compatibility: Building a Tool to Measure the Blast Radius of Library Changes
書いた人
Roberto Perez Alcolea, Java Platform Team
原文の​公開日
確かめた日

AI で​下書きし、​原文と​一次資料を​確かめてから​公開しています。​作り方と​決まり

共有ライブラリの​古い​メソッドを​消したい。​ライブラリの​テストは​通っている。​それでも、​その​メソッドを​まだ​呼んでいる​リポジトリが​どこに​あるかは、​手元の​画面からは​見えません。

Netflix の​技術ブログの​記事​「Beyond API Compatibility」は、ライブラリの​変更が​どの​リポジトリに​届くかを​見えるように​する​ために​作った​社内の​道具 Quasar の​話です。 この記事では、​原文の​要点を​短く​まとめたうえで、​仕組みの​土台に​ある​仕様を​たどり、​「消す前に​数える」を​ブラウザで​試せる​小さな​道具を​付けました。

3行で​言うと

  1. ライブラリの API を​変える​とき、​「互換を​壊すか」と​「どの​リポジトリに​届くか」は​別々の​問いだ、と​いうのが​原文の​芯です。
  2. Quasar は、​変えた​記号を​使うリポジトリの​数を​プルリクエストの​時点で​出し、​使っている​版と​場所も​問い合わせで​引けます。
  3. 「見つからない」が​「だれも​使っていない」の​証明と​取り違えられないように、​どの​コミットを​索引に​したか・​索引が​どれだけ新しいか・​根拠が​途中で​切れていないかも​一緒に​示す、としています。

この記事を​読む前に

  • 提供側と​利用側:ライブラリを​作って​配る​チームと、​それを​依存に​入れて​使う​チームです。​原文は​前者を producer、​利用側の​リポジトリを consumer repositories と呼んでいます。
  • 互換を​壊す変更:​作り直さずに​動いている​既存の​バイナリが、​そのままでは​つながらなくなる​変更を​指します。​Java 言語仕様の​バイナリ互換の​章は、​既存の​バイナリとの​互換と、​次に​コンパイルした​ときに​エラーに​なるかを​分けて​書いています (引数の​違う​版を​足すのは​前者を​壊さないが、​後者の​エラーには​なりうる)。​この記事の​道具と​図は、​既存の​バイナリとの​互換で​「壊す・​壊さない」を​分け、​作り直した​ときの​コンパイルは​別に​書きます。
  • 記号と索引:記号は、​クラスや​メソッドのように​名前で​指せる​ものです。​索引は、​その​記号が​「どこで​定義され、​どこで​使われているか」の​一覧です。
  • SCIP:​コードの​記号の​定義・​参照・​関係を、​言語ごとの​索引の​作り手が​同じ形で​書き出すための​公開の​形式です。
  • 届く範囲 (blast radius):変更が​影響を​及ぼしうる​範囲です。​原文は、​変えた​記号を​実際に​使っている​リポジトリを​数えた​結果を​「観測された blast radius」と​呼んでいます。

原文の要点

当サイトの要約

  • 背景:Netflix では共有の Java ライブラリが​多くの​リポジトリの​アプリを​支えていて、​変更は 1つの​リポジトリで​始まっても、​その​影響は​多くの​リポジトリに​響きうる​ものです。​提供側に API の​差分は​見えても、​変えた​記号を​まだだれが​使っているかは​見えにくい、と​いう​問題です。
  • 仕組み:登録した CI の​ビルドごとに、​言語ごとの​索引の​作り手が SCIP の​索引を Quasar に​送ります。​Quasar は API の​定義と​利用側の​参照を Amazon S3 に Parquet で​持ち、​プルリクエストの​見直しの​ときに Amazon Athena で直接の​参照を​数えます。
  • 比べ方:元と​変更後の​コミットの​定義を​比べて、​記号を​「足した・​消した・​形を​変えた」に​分けます。​どちらかの​コミットの​索引が​無ければ​「比べられない」と​返し、​既定の​ブランチの​索引で​代えません。
  • 判定は​人が:​Quasar は​観測した​影響を​報告するだけで、​リリースの​決まりを​強制しません。​どうするかは​提供側が​決めます。
  • これから:​ライブラリの​コードを​書く​エージェントが、​公開の​記号を​変えていると​気づき、​プルリクエストに​なる​前に Quasar に​問い合わせるように​したい、としています。​今は MCP を​通して、​頼まれた​ときに​問い合わせられる​段階です。

当サイトが​足した​もの:​一次資料を​たどる

一次資料を​たどる:​「同じ​メソッド」を​名前で​指す決まり

原文は、​別々に​索引を​取った​リポジトリどうしでも、​ある API の​変更と​ほかの​リポジトリの​使う​所を Quasar が​結び付けられるのは、​SCIP の​記号の​名前 (識別子) を​共有しているからだ、と​説明しています。では、その​名前は​どんな​形を​しているのでしょうか。

SCIP の​仕様 (scip.proto) は、記号の​名前を​「方式 (scheme)・​パッケージ・​記述子の​並び」と​決め、​パッケージは​「管理の​道具 (manager)・​パッケージ名・版 (version)」で​できています。​記述子は、​名前​空間なら​名前の​後に /、型なら #、メソッドなら (…). を付けて​書きます。​この文法に​沿って、​架空の​ライブラリ money-lib のメソッドを​書くと、​たとえば​次の 1行に​なります。

example maven money-lib 4.2.0 com/example/Money#format().
  • example は方式です。​実際の​値は、​索引を​作る​道具ごとに​決まります (ここは​例と​して​置いた​値です)
  • maven money-lib 4.2.0 はパッケージで、​版が​名前の​一部に​入っています
  • com/ と example/ は名前空間の​記述子 (2つ並ぶ)、Money# は型、format(). はメソッドの​記述子です
一方、原文に​載っている Amazon Athena の問い合わせの​抜粋は、​参照を symbol_canonical という​列で​突き合わせ、​版は dep_version という​別の​列で​返しています。​仕様の​名前には​版が​入るので、​版を​またいで​「同じ​メソッド」を​突き合わせるには、​版を​除いた​形に​そろえる​手順が​要るはずで、​canonical と​いう​語は​その​手順を​指していると​読めます​(当サイトの​見立て。​原文は​この​手順の​中身を​書いていません)。

実装と、​包んだ​ライブラリを​通した​呼び出し

メソッドを​直接呼ぶ所だけを​数えると、​インターフェースを​実装した​クラスや、​ライブラリを​包んだ別の​ライブラリを​通して​使う​所が​漏れます。​仕様の Relationship には is_reference と is_implementation の印が​あり、​型 Animal の​メソッド sound() で​「参照を​探す」と、​それを​実装した Dog の sound() への参照も​返すべきだ、と​いう​例が​書かれています。

原文も、​Quasar は​実装と、​その​実装を​通した​呼び出しも​たどり、​影響を​受ける​リポジトリを​重ねずに​数える、と​書いています。​さらに、​Protobuf の​定義から​生成された Java の​メンバーを​たどって、​.proto の​要素の​名前を​コードに​書いていない​利用側の​リポジトリまで​見つけられる、​としています。​下の道具の price-kit の​行 (包んだ​ライブラリを​通して​届く​所を 1段だけ​数える) は、​当サイトの​単純化です。

互換を​壊すかは、​言語の​決まりで​決まる

Java 言語仕様の​バイナリ互換の​章は、​クラスから​メソッドを​消すと、​その​メソッドを​参照していた​既存の​バイナリとの​互換を​壊しうる、としています。​上位の​クラスに​同じ​シグネチャと​戻り値の​型の​メソッドが​無ければ、​参照を​つなぐ​ときに NoSuchMethodError になりえます。​同じ章は、​既存の​メソッドと​同じ​名前で​引数の​違う​版 (オーバーロード) を​足しても、​既存の​バイナリとの​互換は​壊さないと​しています。​ただし、​次に​コンパイルする​ときに、​最も​合う​メソッドが​決まらずコンパイルの​エラーに​なる​ことは​ある、​とも​書いています。

原文が​学んだ​こととして​最初に​挙げるのも、​互換と​届く​範囲を​分ける​ことです。​消した​メソッドは、​Quasar が​呼ぶ所を​見つけられなくても API の​約束を​破りうる、としています。2つの​問いを、​図 1 のように​縦と​横の​軸に​分けて​考えると、​同じ​「互換を​壊す変更」でも​次の​一手が​変わります。

既存のバイナリとの互換を壊すかと、使う所が見つかるかの 2つの軸横の軸は既存のバイナリとの互換を壊さない変更と壊す変更、縦の軸は使う所が見つかったときと見つからないとき。壊さない・見つかった:互換は壊れない。消す日に数え直し、作り直すときのコンパイルも見る。壊す・見つかった:持ち主に知らせるか古い方を残して非推奨にし、移行を手伝う。壊さない・見つからない:互換は壊れない。古い方を使う所も見つからない。壊す・見つからない:索引を取り直すか、動的な呼び出しを確かめてから消す候補にする。既存のバイナリとの互換を壊さない既存のバイナリとの互換を壊す使う所が見つかった見つからない互換は壊れない。消す日に数え直し、作り直すときのコンパイルも見る持ち主に知らせるか古い方を残して非推奨にし、移行を手伝う互換は壊れない。古い方を使う所も見つからない索引を取り直すか、動的な呼び出しを確かめてから消す候補にする
図 1 既存の​バイナリとの​互換を​壊すか​どうかと、​使う​所が​見つかるかどうかは、​別々に​確かめる​(当サイトの​作図。​ます目の​文は​道具の​「次の​一手」を​まとめたもの)

当サイトが​足した​もの:​ブラウザで​動かせる道具

消す前に​数える道具

この道具は、​原文の Quasar の​コードや​判定を​写した​ものではありません。​互換を​壊すか・​どこに​届くか・​根拠が​どれだけ​確かか、の 3つを​別々に​出す​最小の​形と​して、​当サイトが​作りました。​架空の​ライブラリ money-lib の 3つの​メソッドと、​それを​包む​ライブラリ price-kit があり、​price-kit を​含めて 7つの​リポジトリが​それらを​使っています。

1. 変える API を選ぶ

結果

Money#format(long) を消す

互換を​壊す変更

5件のリポジトリに​届きます

直接使う​所 4件・​price-kit を通して​使う​所 1件

4.23件
4.11件
3.91件
  • price-kit​直接・4.2
  • checkout​直接・4.2
  • invoice​直接・4.2
  • admin-webprice-kit を​通して・​4.1
  • report-batch​直接・​3.9・​索引が古い

根拠の​弱い所

  • old-campaign:​索引が​ありません。​使っているか​分かりません。
  • report-batch:​索引が 45日前で、​30日より​古いです。

次の一手​(当サイトの目安)

使う所が 5件あります。​古い方を​残して​非推奨にし、​移行の​しかたを​出してから、​古い版の​所まで​追います。

数えたのは、​索引の​ある​リポジトリの​うち、​変える​記号を​直接使う​所と、​price-kit の Price#⁠label() を通して​使う​所です。​1つの​リポジトリは 1回だけ​数えます。​リフレクション・​設定ファイルからの​呼び出しは​数えません。

2. リポジトリを​変えてみる

使う記号の​チェック・​版・索引の​有無を​変えると、​結果の​箱が​すぐ​変わります。​行を​足したり外したりも​できます。​入れた​値は​この​画面の​中だけで​使い、​どこにも​保存しません。

  • リポジトリ price-kit

    price-kitmoney-lib を​包む​ライブラリ。Price#label() の中で、​チェックした​記号を​呼びます

    使う記号
  • リポジトリ checkout
    使う記号
  • リポジトリ invoice
    使う記号
  • リポジトリ admin-web
    使う記号
  • リポジトリ mobile-bff
    使う記号
  • リポジトリ report-batch
    使う記号
  • リポジトリ old-campaign
    使う記号

数え方

  • 互換:「消す」と​「引数を​変える」は​互換を​壊す変更、​「引数の​ある​版を​足す​(古い方は​残す)」は​既存の​バイナリの​互換は​壊さない​変更と​して​数えます。​上の Java 言語仕様の​決まりに​合わせています。
  • 届く範囲:​索引の​ある​リポジトリの​うち、​変える​記号を​直接使う​所と、​price-kit の Price#⁠label() を通して​使う​所を、​1つの​リポジトリに​つき 1回だけ​数えます。
  • 根拠の​弱い所:​索引の​無いリポジトリと、​索引を​取ってからの​日数が​「古いとみなす索引」​の日数を​超える​リポジトリ (30日なら 31日以上) を、​数とは​別に​並べます。
  • 次の一手:​既存の​バイナリとの​互換を​壊さない​変更なら​「既存の​バイナリの​互換は​壊れません。」と​出し、​古い方を​使う​所が​残っていれば​「作り直した​ときに​呼び出しが​あいまいに​なり、​コンパイルが​通らなくなる​ことは​あります。」と​添えます。​互換を​壊す変更で 0件の​ときは、​根拠の​弱い所が​あれば​「先に​索引を​取り直してから​決めます」、​無ければ​動的な​呼び出しを​確かめてから​「消す候補にします」​と出します。1〜2件なら​「持ち主に​直接知らせ」、​3件以上なら​「古い方を​残して​非推奨に」する​案を​出します。​この​区切り (2件と 3件の​間) は​当サイトが​決めた​目安です。

試してみる

  1. 初めの​状態の​ままだと、​Money#⁠format(long) を消す変更は 5件の​リポジトリに​届きます。​直接使う​所が 4件、​price-kit を​通して​使う admin-web が 1件で、​版は 4.2 が 3件、​4.1 と 3.9 が 1件ずつです。
  2. old-campaign は索引が​無く、​report-batch は索引が 45日前で 30日より​古いので、​どちらも​「根拠の​弱い所」に​出ます。
  3. 記号を Money#⁠round(long) に変えると 0件に​なりますが、​使っているか​分からない old-campaign が残るので、​次の​一手は​「先に​索引を​取り直してから​決めます」に​なります。​old-campaign の「索引が​ある」に​チェックを​入れると 1件に​なり、​「持ち主に​直接知らせ、​移行を​手伝ってから​変えます」に​変わります。
  4. price-kit の​行で Money#⁠format(long) のチェックを​外すと、​price-kit 自身と、​price-kit を​通して​使う admin-web が​数から​消えて 3件に​なります。​包んだ​ライブラリの​中身 1つで、​届く​範囲が​変わります。
  5. 変え方を​「引数の​ある​版を​足す​(古い方は​残す)」に​すると、​既存の​バイナリの​互換は​壊さない​変更と​出ますが、​古い方を​使う所は 5件の​ままです。​互換と​届く​範囲が​別の​問いだと​いうのは、​この​食い違いの​ことです。

0件は​「使っていない」​ではない

互換を​壊す変更で 0件に​なった​とき、​結果の​箱には​「0件は​「だれも​使っていない」の​証明では​ありません。」と​出ます。​これは​原文の​次の 1文に​合わせた​ものです。

“No references observed” means only that Quasar found none in the indexed population.

(当サイト訳)​「参照が​観測されなかった」が意味するのは、​索引の​ある​範囲の​中で Quasar が​見つけなかった、と​いう​ことだけです。

出典:Beyond API Compatibility: Building a Tool to Measure the Blast Radius of Library Changes(Netflix、​2026年10月23日)

原文は、​利用側を​隠しうる​ものとして、​リフレクション・​設定・​動的な​読み込み・​古い​ブランチ・​不完全な​索引を​挙げています。​この道具で​いえば、​索引の​無い old-campaign と、45日前の​索引しかない report-batch がそれに​当たります。​0件と​出た​変更でも、​その 2つを​確かめるまでは​「消して​よい」とは​言えません。

当サイトが​足した​もの:​小さな​チームで​試せること

小さな​チームで​試せること

0件と​一緒に​「どこまで​見たか」を残す

原文は、​件数だけでなく​呼ぶ​場所の​例と​版の​内訳を​添え、​どの​コミットを​索引に​したか・​利用側の​索引が​どれだけ新しいか・​根拠が​途中で​切れていないかも示すべきだ、​としています。

リポジトリが​数個の​チームなら、​検索した​結果に​「探した​リポジトリと​ブランチ、​探した​日」を​添えるだけでも、​0件の​重みが​変わります。​原文が​書く​とおり、​文字の​検索は​オーバーロード・​継承・​呼び出しの​裏に​ある​成果物の​版を​見落としうる​一方、​利用側の​ビルドで​確かめるのは​強い方法です。​ただし、​全部の​リポジトリで​回すと​高く​つきます。​文字の​検索は​候補を​出す道具に​して、​消す前には​利用側の​ビルドで​確かめる、と​いう​順番が​取りやすいはずです。

消すつもりなら、​先に​印を​付けた​版を出す

Java の @Deprecated には forRemoval という​要素が​あり、​true は​「将来の​版で​消すつもり」を​示します。​消す前に @Deprecated(forRemoval = true) を付けた​版を​出しておくと、​利用側が​作り直した​ときの​警告が、​呼ぶ所の​一覧の​代わりの 1つに​なります。​道具が 3件以上で​出す​「古い方を​残して​非推奨にし、​移行の​しかたを​出してから、​古い版の​所まで​追います。」は、​この​段階の​ことです。

AI に​「消して」と​頼む​ときも、​探した​範囲を​返させる

An agent should not turn “no observed usages in the available index” into “safe to remove.”

(当サイト訳)​エージェントは​「使える​索引の​中で​使用が​観測されなかった」を「消しても​安全」に​変えてはいけません。

出典:Beyond API Compatibility: Building a Tool to Measure the Blast Radius of Library Changes(Netflix、​2026年10月23日)

コードを​書く AI に​「この​関数は​使われていないので​消して」と​頼む​ときも、​同じことが​言えます。​消す前に​「どこを​探して 0件だったか」を​書き出させると、​次に​確かめる​所がはっきりします。​原文は、​Quasar が​根拠を​出し、​エージェントが​移行の​手間を​減らし、​API と​リリースの​判断は​ライブラリの​提供側が​持つ、と​いう​分担を​書いています。​小さな​チームでも、​消すか​どうかを​決める​人を 1人決めて​おくと、​この​分担を​そのまま​使えます。

真似しなくて​よいこと

原文も、​規模が​小さければ​近くの​チームに​聞くか、​少数の​リポジトリを​探せば​済む、と​書いています。​リポジトリが​数個の​チームなら、​全リポジトリの​記号の​索引を​集める​基盤 (CI ごとの​索引の​送信、​S3 と Athena での集計) を​先に​作る​必要は​薄いと​考えます​(当サイトの​見立て)。​まずは​ライブラリの​公開の​メソッドを​消すときだけ、​検索と​ビルドで​「呼ぶ所の​一覧」を​作る、から​始めれば​足ります。

原文を​読む順番

原文の​本文は​英語で​およそ 2,000語です。​時間が​無ければ、​終わりの​ほうの​「What We Learned」​にある 4つの​教訓から​読み、​次に​「Bringing the Analysis Before Release」の​説明用の​報告の​例 (JSON) を​見ると、​何を​出す道具なのかが​早く​つかめます。​その報告の​数 (137 の​リポジトリなど) は、​原文が​「1つの API の​文字どおりの​応答ではない」と​断ったうえでの​説明用の​例です。SCIP の​部分は、​この​記事の​「一次資料を​たどる」と​合わせて​読むと、​索引に​何が​入っているかが​追いやすくなります。

出典

確かめた​日は​どれも 2026年11月3日です。

この記事の​図と​道具は​当サイトが​作った​もので、​原文の​図・画像は​使っていません。