最近在整理一套 Fiori Elements List Report 项目升级规范时，我反复碰到一个很现实的问题，业务团队希望 SAPUI5 版本越新越好，基础平台团队又希望补丁越稳越好，而前端开发同事最关心的是，升级以后我们的扩展代码会不会突然失效。这个问题看起来像版本管理，实际落点却在 API Evolution。因为 SAPUI5 真正承诺稳定的东西，并不是浏览器里看到的 HTML 结构，也不是运行时日志里打印出的某个内部方法名，而是 SAPUI5 Demo Kit 里的 API Reference 所声明的 public API。官方文档也把这个边界说得很清楚，SAPUI5 语境里的 API 默认指 public API，包括函数、类、命名空间、控件，以及控件声明出来的 properties、aggregations 等内容，未出现在 API Reference 里的能力，不属于公开 API 契约。(GitHub)
API Evolution 不是升级说明，而是契约说明
在 SAP Fiori 开发里，API Evolution 最容易被误读成一个版本发布规则，其实它更像一份契约边界说明。我们平时写 UI5 代码，经常会用到sap.