超越 API 兼容性:量化库变更的影响范围

作者:Roberto Perez Alcolea,Java 平台团队
在 Netflix,共享 Java 库支撑着在一个庞大、各自独立演进的代码仓库生态系统中开发的各类应用。一次库的变更始于某一个仓库,但其影响可能波及许多其他仓库。生产者能看到摆在面前的 API diff,但他们往往看不到的是,还有谁仍然依赖那些发生变更的符号。
随着编码智能体承担起软件开发生命周期中越来越多的工作,这种可见性的需求也在不断增长。智能体可以加速一次局部修改,但如果没有跨仓库的上下文,它就无法判断下游风险,也无法帮助规划使用方的迁移。生产者用来评估某项变更的依据,同样可以指导正在处理该变更的智能体。
设想一个常见场景:移除一个已弃用的 API。已弃用的入口点会扩大生产者必须测试、记录和支持的范围,而且可能限制库的演进方式。
假设替代方案已经发布了几个版本,而旧方法无法表达新行为所需的选项。库的测试通过了,兼容性检查器也标记出了这次移除。但生产者仍然无法回答那些决定下一步该怎么做的关键问题:
在小规模下,生产者可以询问邻近的团队,或在少数几个仓库中搜索。但在众多仓库之间,要找到某个方法的每一个调用方以及各自使用的库版本就难得多。这些答案分散在使用方的代码库和构建之中。
缺乏这些依据,生产者可能发布一项破坏性变更,然后通过使用方的故障才发现其影响;也可能因为风险未知而无限期保留旧 API。库需要演进,而其生产者需要相应的依据,帮助他们有意识地推进这一演进。
我们构建了 Quasar,用于对 Netflix 各代码仓库中的符号定义与引用建立索引。对于库的生产者而言,这份共享索引有助于回答两个问题:
第一个问题用于识别可能存在不兼容的变更,第二个问题用于估算该变更实际观察到的影响范围。两者结合,可以把泛泛的兼容性警告转化为生产者在合并或发布之前可据以行动的证据。
现有技术各自只能看到问题的一部分。二进制与源代码兼容性工具能识别契约变更,却无法说明谁在使用被变更的 API。依赖图能展示声明的可达范围,却无法证明代码确实调用了某个特定方法。文本搜索可能遗漏重载、继承,或调用背后的构件版本。使用方构建能提供强有力的验证,但在整个仓库群上运行它们成本高昂。
Quasar 基于 SCIP 构建,SCIP 是一种面向语义代码智能的开放交换格式。各语言专用的索引器使用稳定的符号标识符来编码定义、引用和关系。Quasar 会保存库各版本与提交的 API 定义,以及来自使用方仓库的引用。这种共享身份让它能把一个仓库中的 API 变更与其他位置的确切用法关联起来,即便这些仓库是各自独立索引的。
在每次纳入的 CI 构建中,各语言专用索引器会把 SCIP 索引提交到 Quasar 的摄取服务。该服务将 API 定义和使用方引用以 Parquet 格式写入 Amazon S3,并保留排查变更所需的符号身份、依赖版本和源码位置。
在拉取请求(pull request)审查期间,Quasar 会比较已建立索引的 base 与 head 定义,并使用 Amazon Athena 统计直接使用方的引用数量。Quasar 通过其 REST 和 GraphQL API 以及 MCP 服务器对外暴露这些发现;后续的使用情况查询可提供依赖版本细分和源码位置。当生产方提供发生变更的 JVM 符号时,另一套单独的兼容性影响评估还能继续追踪其实现以及这些实现的调用方。
来看下面这个简化后的 API 变更:
public interface Client { - Result getLegacyValue(Request request); + Result getValue(Request request, Options options); }为了对这次方法移除做详细的兼容性影响评估,生产方一侧的工具会提供旧方法的描述符。Quasar 据此构建其规范化符号标识。下面这段摘自 Quasar 的 Amazon Athena 查询中“直接引用”部分的缩略节选,展示了核心的匹配逻辑:
SELECT c.change_id, 'DIRECT_REFERENCE' AS evidence_kind, r.scm_type, r.org, r.repo, r.dep_version, r.file_path FROM requested_changes c JOIN quasar.symbol_refs r ON r.symbol_canonical = c.target_canonicalrequested_changes 中包含生产方提交的 API 变更。这段 SQL 节选会找出调用被移除方法的代码仓库。Quasar 还会检查实现以及经由这些实现的调用,因此每个受影响的代码仓库只会被计数一次。它会返回示例依赖版本和文件位置,以帮助排查这一结果。
对于 Client 这次变更,这能告诉生产方哪些代码仓库仍在使用 getLegacyValue、它们使用的是哪些版本,以及其中部分调用出现在哪里。这有助于生产方决定是否要在移除该方法之前协调一次迁移。
在规划升级或编写迁移指南时,逐版本对比很有价值。如果反馈能在代码审查阶段就到达,对提供方的帮助会更大。
针对 pull request 分析,Quasar 以 commit 为键存储 API 定义快照。给定 base commit 和 head commit,它会把符号分类为新增、删除或签名修改。被删除和被修改的符号随后成为消费者影响分析的候选对象。
不兼容的变更并不自动等同于高风险变更。Quasar 报告实际观察到的影响,由提供方决定如何处理;它不强制执行发布策略。“未观察到引用”仅意味着 Quasar 在已索引的总体范围内没有找到引用。反射、配置、动态加载、过时分支或不完整的索引都可能隐藏消费者。结果需要显示所请求的 commit 是否已被索引、消费者索引的新鲜程度,以及证据是否被截断。
pull request 审查需要针对确切的 base commit 和 head commit 的已索引快照。如果其中任一不可用,Quasar 会报告无法对二者进行比较,而不会用默认分支的快照来替代。这样可以避免一次缺失的比较看起来像是一份干净的 API diff。
回到我们的 Client 变更。这份示例报告汇集了通过 Quasar 的 API 比较、消费者使用查询以及库级关键度所能获得的信号。它并不是来自某个 API 的真实响应:
{ "change": "REMOVED", "symbol": "Client#getLegacyValue(Request)", "affectedRepositories": 137, "versionDistribution": [ { "version": "4.2.1", "repositories": 86 }, { "version": "4.1.7", "repositories": 38 }, { "version": "3.9.4", "repositories": 13 } ], "sampleConsumerLocations": [ { "repository": "checkout-service", "filePath": "src/main/java/com/example/checkout/CheckoutClient.java", "lines": [84, 129] }, { "repository": "client-wrapper", "filePath": "src/main/java/com/example/client/ClientAdapter.java", "lines": [57] } ], "libraryCriticality": { "tier": 1, "basis": "highest-tier downstream application" }, "comparison": { "baseShaFound": true, "headShaFound": true } } 一份影响报告显示,有 137 个受影响的仓库分布在库版本 4.2.1、4.1.7 和 3.9.4 上。仓库计数是特定于符号的:在此示例中,137 个已索引仓库指向这个被移除的方法。版本分布显示,绝大多数集中在 4.2.1,另有较小的长尾仍停留在 3.9.4。生产者可以检查受影响的仓库,并获取已索引的文件路径,在索引提供行号的地方也会包含行号。为了让示例保持可读,JSON 只展示了两个示例位置。filePath 和 lines 的结构与 Quasar 的查询契约一致。tier 是关于该库的更广泛上下文,继承自其最高关键性的下游应用;这并不意味着全部 137 个调用方都是 Tier 1。
这些信号综合起来,会改变生产者的计划。生产者不必直接合并删除并等待故障出现,而是可以保留旧方法并将其标记为弃用、发布迁移路径、协调更广泛的迁移,并在移除前追踪长尾版本。文件路径和可用的行号把这一范围转化为工程师或编码智能体的具体工作清单。同样的 API 差异,若搭配薄弱或过时的证据,则会导向不同的行动:先刷新索引再做决定。其价值不仅在于检测到移除,而在于选择相称的下一步。
共享的 SCIP 格式还让 Quasar 能够索引多种语言生态。每种语言的索引器解析各自的代码,而 Quasar 可以利用由此得到的符号标识,跨仓库查找引用。
从概念上讲,client-lib 将 Client#getLegacyValue(Request) 索引为定义,而 checkout-service 索引的是对同一符号的引用。Quasar 随后便能跨仓库把库 API 与其使用方连接起来。
原文较长,译文为节选;译文由英文原文机器翻译,术语按行业惯例统一,可在文末展开原文核对。
查看英文原文(Beyond API Compatibility: Building a Tool to Measure the Blast Radius of Library Changes)
By Roberto Perez Alcolea, Java Platform Team

At Netflix, shared Java libraries support applications developed across a large, independently evolving repository ecosystem. A library change begins in one repository, but its impact can reach many others. Producers can see the API diff in front of them. What they often cannot see is who still depends on the symbols that changed.
The need for that visibility grows as coding agents take on more of the software development lifecycle. An agent can accelerate a local edit, but without cross-repository context it cannot judge downstream risk or help plan consumer migrations. The evidence a producer uses to assess a change can also guide the agent working on it.
Consider a common case: removing a deprecated API. Deprecated entry points expand the surface producers must test, document, and support, and they can constrain how a library evolves.
Suppose a replacement has been available for several releases and the old method cannot express options required by new behavior. The library’s tests pass, and a compatibility checker flags the removal. The producer still cannot answer the questions that determine what to do next:
- Does any consumer still call this method?
- Are consumers concentrated on one version or spread across several generations?
- Does another library implement or wrap the API, multiplying its impact?
- Is direct coordination sufficient, or does this require a deprecation and migration campaign?
At small scale, producers can ask nearby teams or search a handful of repositories. Across many repositories, it is harder to find every caller of a method and the library version each one uses. Those answers are scattered across consumer codebases and builds.
Without that evidence, a producer may release a breaking change and discover the impact through consumer failures, or preserve an old API indefinitely because the risk is unknown. Libraries need to evolve, and their producers need evidence that helps them do so intentionally.
We built Quasar to index symbol definitions and references across Netflix repositories. For library producers, that shared index helps answer two questions:
- What changed in the library’s public API?
- Which repositories use the exact symbols that changed?
The first identifies a potentially incompatible change. The second estimates its observed blast radius. Together, they turn a generic compatibility warning into evidence a producer can act on before merging or releasing.
From API Changes to Consumer Impact
Existing techniques each see a different part of the problem. Binary and source compatibility tools identify contract changes, but cannot tell who uses the changed API. Dependency graphs show declared reach, but cannot prove that code calls a particular method. Text search may miss overloads, inheritance, or the artifact version behind a call. Consumer builds provide strong validation, but running them across the fleet is expensive.
Quasar builds on SCIP, an open interchange format for semantic code intelligence. Language-specific indexers encode definitions, references, and relationships using stable symbol identifiers. Quasar retains API definitions for library versions and commits alongside references from consumer repositories. That shared identity lets it connect an API change in one repository to exact usages elsewhere, even when those repositories were indexed independently.

On each enrolled CI build, language-specific indexers submit SCIP indexes to Quasar’s ingestion service. It writes API definitions and consumer references as Parquet in Amazon S3, retaining the symbol identity, dependency version, and source location needed to investigate a change.
During pull-request review, Quasar compares indexed base and head definitions and counts direct consumer references with Amazon Athena. Quasar exposes those findings through its REST and GraphQL APIs and MCP server; follow-up usage queries provide dependency-version breakdowns and source locations. A separate compatibility-impact assessment can also follow implementations and their callers when a producer supplies a changed JVM symbol.
Consider this simplified API change:
public interface Client {
- Result getLegacyValue(Request request);
+ Result getValue(Request request, Options options);
}For a detailed compatibility-impact assessment of this removal, a producer-side tool supplies the old method descriptor. Quasar constructs its canonical symbol identity. This abridged excerpt from the direct-reference portion of Quasar’s Amazon Athena query shows the essential match:
SELECT c.change_id, 'DIRECT_REFERENCE' AS evidence_kind,
r.scm_type, r.org, r.repo, r.dep_version, r.file_path
FROM requested_changes c
JOIN quasar.symbol_refs r
ON r.symbol_canonical = c.target_canonical
requested_changes contains the API changes submitted by the producer. The SQL excerpt finds repositories that call the removed method. Quasar also checks implementations and calls through them, so it can count each affected repository once. It returns sample dependency versions and file locations to help investigate the result.
For the Client change, this tells the producer which repositories still use getLegacyValue, which versions they use, and where some of those calls occur. That helps the producer decide whether to coordinate a migration before removing the method.
Bringing the Analysis Before Release
Version-to-version comparison is valuable when planning an upgrade or writing a migration guide. Producers benefit even more when feedback arrives during code review.
For pull-request analysis, Quasar stores API definition snapshots keyed by commit. Given a base and head commit, it classifies symbols as added, removed, or signature-modified. Removals and modifications then become candidates for consumer-impact analysis.
An incompatible change is not automatically a high-risk change. Quasar reports the observed impact so the producer can decide what to do; it does not enforce a release policy. “No references observed” means only that Quasar found none in the indexed population. Reflection, configuration, dynamic loading, stale branches, or incomplete indexing can hide consumers. The result needs to show whether the requested commits were indexed, how fresh the consumer indexes are, and whether evidence was truncated.
Pull-request review requires indexed snapshots for the exact base and head commits. If either is unavailable, Quasar reports that it cannot compare them; it does not substitute a default-branch snapshot. This keeps a missing comparison from looking like a clean API diff.
Return to our Client change. This illustrative report brings together signals available through Quasar's API comparison, consumer-usage queries, and library-level criticality. It is not a literal response from one API:
{
"change": "REMOVED",
"symbol": "Client#getLegacyValue(Request)",
"affectedRepositories": 137,
"versionDistribution": [
{ "version": "4.2.1", "repositories": 86 },
{ "version": "4.1.7", "repositories": 38 },
{ "version": "3.9.4", "repositories": 13 }
],
"sampleConsumerLocations": [
{
"repository": "checkout-service",
"filePath": "src/main/java/com/example/checkout/CheckoutClient.java",
"lines": [84, 129]
},
{
"repository": "client-wrapper",
"filePath": "src/main/java/com/example/client/ClientAdapter.java",
"lines": [57]
}
],
"libraryCriticality": {
"tier": 1,
"basis": "highest-tier downstream application"
},
"comparison": {
"baseShaFound": true,
"headShaFound": true
}
}
The repository count is symbol-specific: in this example, 137 indexed repositories refer to the removed method. The version distribution reveals a dominant cohort on 4.2.1 and a smaller long tail still on 3.9.4. A producer can inspect affected repositories and retrieve indexed file paths, with line numbers where the index provides them. The JSON shows only two sample locations to keep the example readable. The filePath and lines shape mirrors Quasar's query contract. The tier is broader context about the library, inherited from its highest-criticality downstream application; it does not imply that all 137 callers are Tier 1.
Together, those signals change the producer’s plan. Instead of merging the removal and waiting for failures, the producer can retain and deprecate the old method, publish a migration path, coordinate a broader migration, and track the long-tail versions before removal. File paths and available line numbers turn that scope into a concrete work list for engineers or coding agents. The same API diff paired with weak or stale evidence would lead to a different action: refresh the indexes before deciding. The value is not merely detecting the removal; it is choosing a proportionate next step.

A Polyglot Foundation with SCIP
The shared SCIP format also lets Quasar index several language ecosystems. Each language indexer resolves its own code, while Quasar can use the resulting symbol identities to find references across repositories.
Conceptually, client-lib indexes Client#getLegacyValue(Request) as a definition, while checkout-service indexes a reference to the same symbol. Quasar can then connect the library API to its consumer across repositories.

Relationships are especially useful when generated code separates the API a producer owns from the symbols consumers invoke. For example, Quasar can trace a Protobuf definition through its generated Java members to the repositories that use them, even when consumer code never names the .proto element.
SCIP records symbols and their references; it does not determine whether an API change violates an ecosystem’s compatibility rules. Today, Quasar compares indexed JVM and Protobuf API definitions and traces Protobuf changes through generated Java to find affected repositories. A separate JVM compatibility-impact path uses breaks identified by a producer-side tool to query affected repositories. Go, Python, JavaScript/TypeScript, and Rust support usage queries, but Quasar does not yet assess their breaking API changes.
Moving Risk Assessment Earlier
Today, Quasar surfaces API-change findings on pull requests, including observed consumer counts and confidence. Producers can use its other queries to inspect dependency versions and source locations, with library criticality as broader context. Together, those signals support a decision before merge.
We want to move that context earlier. An agent writing library code should recognize when it is changing a public symbol and consult Quasar before the change becomes a pull request. Quasar’s APIs and Model Context Protocol (MCP) integration provide an access path, but access alone does not create awareness. The coding workflow must also recognize public API edits so the agent knows when to query impact and when to involve the producer.

Earlier guidance will not replace pull-request analysis. The PR assessment will still verify the concrete diff and catch changes that were not recognized during coding. Coverage, freshness, ambiguity, unsupported platforms, and truncation must travel through both checks in machine-readable form. An agent should not turn “no observed usages in the available index” into “safe to remove.”
Today, agents can query Quasar through MCP when prompted. We are working toward making that context part of the coding workflow, then using identified call sites to prepare migration changes. Quasar supplies semantic evidence, an agent reduces migration toil, and the library producer remains responsible for API and release decisions.
What We Learned
Building this workflow led us to four practical lessons.
- Separate compatibility from reach. A removed method can break the API contract even when Quasar finds no callers. A list of affected repositories and their library versions shows the migration work ahead. Producers need both signals to choose a release path.
- Make the evidence inspectable. A repository count is more useful with sample call sites and a version breakdown. The result also needs to show which commits were indexed, how fresh the consumer indexes are, and whether evidence was truncated. Otherwise, “no usage found” can be mistaken for proof that nobody is affected.
- Keep usage and compatibility separate across languages. SCIP lets Quasar find symbol references in several ecosystems. Deciding whether an API change is breaking requires compatibility rules or a trusted producer-side signal for that ecosystem.
- Bring evidence to the producer while choices are open. Pull-request findings can prompt a producer to retain an API, publish a migration path, or coordinate consumers before merge. Moving the same evidence into the coding workflow could shape the edit earlier. After release, it still helps locate consumers that need to migrate.
Today, Quasar indexes JVM, Go, Python, JavaScript/TypeScript, and Rust code for cross-repository usage analysis. It compares JVM APIs and traces Protobuf changes through generated Java. Producers can review change findings through Quasar’s REST and GraphQL APIs or its MCP server, then investigate affected repositories and call sites. We are extending this foundation toward more ecosystem-specific compatibility checks, deeper code-review integration, and agent-assisted consumer migrations that keep release approval with the producer.
Quasar is internal to Netflix, but the pattern is portable: index code semantically, retain API definitions, compare them at the point of change, query affected consumers, and report the quality of the evidence. Library producers need more than a compatibility verdict. They need to know who may be affected and have enough time to act before release.
A huge thank you to the Java Platform team at Netflix. Their expertise, collaboration, and support made this work possible
Related Talks
- From Lag to Lightning: Transforming Dependency Update Timelines explores how Netflix shortened dependency-update timelines.
- Netflix’s Journey to Confident Automated Code Changes discusses building confidence in automated changes at scale.
Beyond API Compatibility: Building a Tool to Measure the Blast Radius of Library Changes was originally published in Netflix TechBlog on Medium, where people are continuing the conversation by highlighting and responding to this story.
正文保留英文原文,标题与摘要由机器翻译。
原文发布于 Netflix Tech(Beyond API Compatibility: Building a Tool to Measure the Blast Radius of Library Changes),标题、摘要与正文由机器翻译,术语按行业惯例统一,未经人工逐句校订。