海勒姆定律
当 API 用户足够多时，系统的每一种可观察行为都可能被人依赖。
显示原始英文内容
Hyrum's Law
With a sufficient number of API users, all observable behaviors of your system will be depended on by somebody.
Takeaways
- As the user count grows, everything your system does becomes a dependency point. Even unintended side effects or bugs can become 'features' that someone's workflow depends on.
- Hyrum's Law warns maintainers that any change can break something for someone. Consumers may have integrated your API in ways you didn't expect, including relying on timing, error messages, formatting, etc.
- The actual contract of your software isn't just the official API/spec; it's the exact behavior as observed in the wild. The contract can even be something informal, such as the UI that your users are used to.
Overview
Hyrum's Law describes a phenomenon where the boundary between a software's documented interface and its implementation details gets blurred in practice. No matter what you promise in an API contract, if people use your system enough, they will depend on behaviors you never officially supported.
Over time, the implementation becomes the interface. Every observable trait, performance characteristic, or error code might be assumed by someone. This drastically limits freedom to change the system, as even internal changes can break users who wrote code around the old behavior.
Examples
Microsoft Windows had undocumented behaviors and bugs that many third-party applications relied on. When Microsoft fixed or changed those behaviors in new versions, those applications broke. Microsoft often had to revert or maintain quirky behavior to ensure compatibility.
A library might state in the docs that a function returns an unordered list, but it currently returns a sorted list. Some users start depending on it being sorted. If the library later changes to truly unordered, those users' code will break. The law is especially relevant in API versioning: even minor changes can be breaking changes from someone's perspective.
Origins
The law is named after Hyrum Wright, a software engineer who articulated this observation while at Google around 2011-2012. Hyrum noticed that even changes to core Google libraries that should have been invisible would often break some project somewhere, because that project relied on an undocumented behavior.
His colleague, Titus Winters, coined the term "Hyrum's Law" in recognition of it (in Software Engineering at Google).
核心含义
文档里承诺的接口只是契约的一部分。用户还可能依赖返回顺序、错误信息、响应延迟、格式细节，甚至某个 bug 的行为。使用者越多，越难区分“公开接口”和“碰巧可见的实现细节”。
因此，系统的真实契约是生产环境中被观察和使用的全部行为。变更前需要识别依赖者、提供迁移路径，并尽可能用遥测和兼容层降低风险。
实践例子
一个库文档声明返回无序列表，但长期以来实际返回的是排序列表。用户据此编写代码后，库改为真正的无序返回就会造成破坏性变化。
来源与边界
海勒姆定律由 Hyrum Wright 总结，常用于解释大型 API 和基础库的演化困难。它提醒我们保守管理接口，但不代表系统永远不能改变；版本化、弃用周期和兼容测试仍然可以创造变更空间。