ライブラリの 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
- 原文の公開日
- 確かめた日
- 原文
- Beyond API Compatibility: Building a Tool to Measure the Blast Radius of Library Changes(netflixtechblog.com)
AI で下書きし、原文と一次資料を確かめてから公開しています。作り方と決まり
共有ライブラリの古いメソッドを消したい。ライブラリのテストは通っている。それでも、そのメソッドをまだ呼んでいるリポジトリがどこにあるかは、手元の画面からは見えません。
Netflix の技術ブログの記事「Beyond API Compatibility」は、ライブラリの変更がどのリポジトリに届くかを見えるようにするために作った社内の道具 Quasar の話です。 この記事では、原文の要点を短くまとめたうえで、仕組みの土台にある仕様をたどり、「消す前に数える」をブラウザで試せる小さな道具を付けました。3行で言うと
- ライブラリの API を変えるとき、「互換を壊すか」と「どのリポジトリに届くか」は別々の問いだ、というのが原文の芯です。
- Quasar は、変えた記号を使うリポジトリの数をプルリクエストの時点で出し、使っている版と場所も問い合わせで引けます。
- 「見つからない」が「だれも使っていない」の証明と取り違えられないように、どのコミットを索引にしたか・索引がどれだけ新しいか・根拠が途中で切れていないかも一緒に示す、としています。
この記事を読む前に
- 提供側と利用側:ライブラリを作って配るチームと、それを依存に入れて使うチームです。原文は前者を 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().はメソッドの記述子です
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 のように縦と横の軸に分けて考えると、同じ「互換を壊す変更」でも次の一手が変わります。
当サイトが足したもの:ブラウザで動かせる道具
消す前に数える道具
この道具は、原文の Quasar のコードや判定を写したものではありません。互換を壊すか・どこに届くか・根拠がどれだけ確かか、の 3つを別々に出す最小の形として、当サイトが作りました。架空のライブラリ money-lib の 3つのメソッドと、それを包むライブラリ price-kit があり、price-kit を含めて 7つのリポジトリがそれらを使っています。
1. 変える API を選ぶ
日数は 0 以上の整数で入れてください。直すまで前の値で数えます
結果
Money#format(long) を消す
互換を壊す変更
5件のリポジトリに届きます
直接使う所 4件・price-kit を通して使う所 1件
- 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. リポジトリを変えてみる
使う記号のチェック・版・索引の有無を変えると、結果の箱がすぐ変わります。行を足したり外したりもできます。入れた値はこの画面の中だけで使い、どこにも保存しません。
数え方
- 互換:「消す」と「引数を変える」は互換を壊す変更、「引数のある版を足す(古い方は残す)」は既存のバイナリの互換は壊さない変更として数えます。上の Java 言語仕様の決まりに合わせています。
- 届く範囲:索引のあるリポジトリのうち、変える記号を直接使う所と、price-kit の Price#label() を通して使う所を、1つのリポジトリにつき 1回だけ数えます。
- 根拠の弱い所:索引の無いリポジトリと、索引を取ってからの日数が「古いとみなす索引」の日数を超えるリポジトリ (30日なら 31日以上) を、数とは別に並べます。
- 次の一手:既存のバイナリとの互換を壊さない変更なら「既存のバイナリの互換は壊れません。」と出し、古い方を使う所が残っていれば「作り直したときに呼び出しがあいまいになり、コンパイルが通らなくなることはあります。」と添えます。互換を壊す変更で 0件のときは、根拠の弱い所があれば「先に索引を取り直してから決めます」、無ければ動的な呼び出しを確かめてから「消す候補にします」と出します。1〜2件なら「持ち主に直接知らせ」、3件以上なら「古い方を残して非推奨に」する案を出します。この区切り (2件と 3件の間) は当サイトが決めた目安です。
試してみる
- 初めの状態のままだと、Money#format(long) を消す変更は 5件のリポジトリに届きます。直接使う所が 4件、price-kit を通して使う admin-web が 1件で、版は 4.2 が 3件、4.1 と 3.9 が 1件ずつです。
- old-campaign は索引が無く、report-batch は索引が 45日前で 30日より古いので、どちらも「根拠の弱い所」に出ます。
- 記号を Money#round(long) に変えると 0件になりますが、使っているか分からない old-campaign が残るので、次の一手は「先に索引を取り直してから決めます」になります。old-campaign の「索引がある」にチェックを入れると 1件になり、「持ち主に直接知らせ、移行を手伝ってから変えます」に変わります。
- price-kit の行で Money#format(long) のチェックを外すと、price-kit 自身と、price-kit を通して使う admin-web が数から消えて 3件になります。包んだライブラリの中身 1つで、届く範囲が変わります。
- 変え方を「引数のある版を足す(古い方は残す)」にすると、既存のバイナリの互換は壊さない変更と出ますが、古い方を使う所は 5件のままです。互換と届く範囲が別の問いだというのは、この食い違いのことです。
0件は「使っていない」ではない
互換を壊す変更で 0件になったとき、結果の箱には「0件は「だれも使っていない」の証明ではありません。」と出ます。これは原文の次の 1文に合わせたものです。“No references observed” means only that Quasar found none in the indexed population.
(当サイト訳)「参照が観測されなかった」が意味するのは、索引のある範囲の中で Quasar が見つけなかった、ということだけです。
原文は、利用側を隠しうるものとして、リフレクション・設定・動的な読み込み・古いブランチ・不完全な索引を挙げています。この道具でいえば、索引の無い 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.”
(当サイト訳)エージェントは「使える索引の中で使用が観測されなかった」を「消しても安全」に変えてはいけません。
コードを書く AI に「この関数は使われていないので消して」と頼むときも、同じことが言えます。消す前に「どこを探して 0件だったか」を書き出させると、次に確かめる所がはっきりします。原文は、Quasar が根拠を出し、エージェントが移行の手間を減らし、API とリリースの判断はライブラリの提供側が持つ、という分担を書いています。小さなチームでも、消すかどうかを決める人を 1人決めておくと、この分担をそのまま使えます。
真似しなくてよいこと
原文も、規模が小さければ近くのチームに聞くか、少数のリポジトリを探せば済む、と書いています。リポジトリが数個のチームなら、全リポジトリの記号の索引を集める基盤 (CI ごとの索引の送信、S3 と Athena での集計) を先に作る必要は薄いと考えます(当サイトの見立て)。まずはライブラリの公開のメソッドを消すときだけ、検索とビルドで「呼ぶ所の一覧」を作る、から始めれば足ります。
原文を読む順番
出典
確かめた日はどれも 2026年11月3日です。
- Beyond API Compatibility: Building a Tool to Measure the Blast Radius of Library Changes(Netflix TechBlog、2026年10月23日。原文。RSS の全文で読みました)
- SCIP の仕様 scip.proto(scip-code/scip、コミット bbec5345。記号の文法・Relationship・SymbolRole)
- The Java Language Specification, Java SE 21 Edition, Chapter 13. Binary Compatibility(13.4.12 と 13.4.23)
- Java SE 21 API の java.lang.Deprecated(forRemoval の要素)
この記事の図と道具は当サイトが作ったもので、原文の図・画像は使っていません。