共计 5937 个字符，预计需要花费 15 分钟才能阅读完成。
凋谢银行尽管有多种对外连贯形式，但 API 以其易用性成为了接受度最好的抉择，也是很多综合性银行推广凋谢银行必然须要对外提供的外围能力。
简略的 API 之下，蕴藏着简单的 API 支撑体系，不论是设计时的命名和路由标准，还是运行时的平安和容错解决，深刻细节都让人生畏。
快慰的是，随着技术的继续演进，越来越多的教训被逐渐提炼成了规范和工具，让整个 API 的治理继续简化。特地是在英国和新加坡政府被动推动凋谢银行（Open Banking）之后，金融服务畛域在 API 方面有了越来越多的资产能够为各家银行所采纳。
如果想体验一下凋谢 API 为金融行业倒退带来的便当，能够参考《开发者体验 – 凋谢银行的奠基石》文中对行业领先者 —— 德意志银行的剖析。
（2021 年，英国凋谢银行组织庆贺成立 3 周年，https://www.openbanking.org.u…
然而 API 版本（Versioning）设计始终是开放平台设计上的老大难问题。
就像过来几十年反对了咱们几大行高速倒退的主机零碎，想要迁徙到开放平台，都是一次宏大的再造工程。而凋谢银行自身的商业模式，又决定了 API 一旦公布，围绕其生态的干系方是齐全不禁银行管制的。很多银行人都经验过零碎报文格式的切换，切换过程中细枝末节的问题常常造成大家挑灯夜战。但报文自身毕竟还是同业圈子内的降级，可控性较好，凋谢银行却是波及到多元化异业的分布式合作，没有任何一方有相对的控制力。
API 版本策略也很难要求各大银行都完全一致，必然受制于各家凋谢业务想法的不同，和外部零碎架构的架构差别。所以具体采纳什么策略实际上是一个业务和技术的综合决策，而业务和技术在 API 版本策略上的对齐往往被大家疏忽，后果就是业务认为加个接口字段很简略，开发却埋怨毁坏了版本一致性，造成微小的内部兼容性问题。
上面就让咱们从一个绝对综合的视角来研究一下凋谢 API 的版本模式，促成银行业在凋谢 API 平台建设方面更多碰撞和思考。
软件版本 VS API 版本
古代社会每个人都是软件用户，特地是在智能手机遍及的明天，各种各样的软件曾经融入到了咱们日常生活中。对于软件的“降级”是一件司空见惯的事件，很多时候咱们都会被提醒软件版本过低，须要降级能力应用某性能。
挪动 APP 时代对于软件版本治理本质上是做了大量的简化，不论是苹果的 iOS 平台，还是安卓 Android 平台，APP 软件的版本都是始终向前降级的。如果忽然关上一款久不应用的 APP，提醒版本太低不能应用，或者因为手机操作系统太老旧而无奈应用新版本，咱们都会感觉是常理之中的事件，不会有啥针对软件开发者自身的埋怨。
甚至如果一款 APP 超过两周都没有任何扭转，咱们会狐疑其沉闷水平，是不是背地老板曾经跑路了。APP 软件版本升级成了和服务一起演进的事件，服务越来越好、性能越来越多，天然要求公布新的软件版本，比方双十一前，各大电商必定是要更新几次自家 APP 的。
当然智能手机之外咱们其实还有很多的大型商业软件，比方每家企业当初都须要的财务管理软件，这些软件在市面上存在着多个版本，因为行业、规模、经营各家企业都不尽相同，所以这样的商业软件用不同的版本适配不同的企业是很常见的。
这之上也有企业几年前买了一个软件版本，因为各种起因，始终应用没有降级，也或者的确满足了企业的需要，没有必要驳回新版本。版本自身在这样的商业软件交易时就是其中一个要害属性，并且个别都有针对后续公布新版本是否驳回方面的合同条款。
凋谢 API 版本兼具了以上两种软件的特点，但又提出了更高的要求。因为商业单干和生态的继续丰盛，凋谢 API 显然会继续降级，而且新的版本应该比旧的版本更加高效（不排除性能上有减少，比方拜访鉴权），常见的需要是过来 1 分钟 100 笔交易，当初要求 1 万笔。作为 API 的使用者，期待和更新手机 APP 一样，新版本应该更弱小。
不同于手机 APP 的是，凋谢 API 降级后不可能强行要求“用户”降级，内部应用 API 的零碎更新或扭转都不是 API 发布者能掌控的，并且也不可能通过相似 iOS 这样的平台去对立应用要求，比方平安合规方面的对立降级。
凋谢 API 同时也是被多方应用的，和商业软件一样，最开始连贯时采纳的是过后的 API 版本，后续有的连贯心愿始终用上来，有的可能提出新的述求。当新的述求被新的 API 版本满足后，作为之前的 API 使用者，咱们会默认新版本不会毁坏之前的服务，即便新性能对于局部使用者来说没有采纳。
商业软件的世界里，咱们常常会听到版本 5.0 是一个大降级，必须重新安装，不反对从 4.0 降级。这时咱们个别有些小烦恼，但卸载 4.0，装置 5.0 也不是太大的艰难。然而如果某 API 的 5.0 版本不兼容 4.0 版本，也就意味着 4.0 的使用者们须要从新批改本人的零碎，当咱们有成千盈百的内部利用应用该 API 时，这就是一个微小的挑战，很多时候甚至不得不面临用户的投诉。
API 版本致胜准则
迎接这样的挑战，咱们首先须要明确凋谢 API 版本升级的是什么？
首先 API 是用来传递信息的，信息显然必须遵循肯定的格局。银行从业者立马就能想到报文，比方寰球通行的 SWIFT 报，每种报文必然须要有相干的字段设计和格局要求，信息的提供者和消费者都必须依据格局标准来，要不然就没法交换了。当然这样的格局调整最好少做，每次都带来了微小的工作量，收益却无限。
（SWIFT 报文示例，报文格式自身是信息传递的一部分。任何格局的扭转都要求收发方必须同步，这对于面向凋谢的互联网来说是不事实的）
报文的应用源自于电报时代的点对点信息沟通，却不是咱们这个互联网时代所说的 API。API 提供的信息某种意义上是针对业务实体的操作，比方增删查改（CRUD），API 的命名其实就是要形容这样的操作。这里咱们不纠结于 API 采纳的实现架构（RESTful 和 RPC），专一于 API 版本背地的本质，就会发现其实须要被治理的是业务实体的变动。
类比一下汽车制造商罕用的版本控制形式，飞驰宝马这样的汽车制造商通常每 4、5 年推出新一代的风行车型，比方宝马的 X 系列。接下来每年都会有降级版本，比方 2019 年的 X1 和 2018 年的 X1 性能不同，而且形状上也有稍许不同。每个客户购买的汽车是特定型号的特定版本汽车，如果制造商召回汽车来修复故障，也须要明确型号和版本，当然后续培修是无奈使您 2018 版本汽车的外观及行为和 2019 年版本一样的。
回到金融畛域，咱们的业务实体很多，比方某个客户的某种账户、某种类型交易、债券衍生品等等。凋谢 API 提供了让咱们的合作伙伴可能操作这些实体，比方客户想通过第三方领取利用调转本人账户里的贷款。显然咱们不会把客户账户的信息以报文的模式传递给第三方，API 提供的是第三方在客户提供受权信息的状况下，可能告知咱们将客户的资金转往哪个指定账户。
所以 API 版本的背地是咱们业务实体的变动，比方因为监管合规的要求，客户账户须要进行更进一步的实名验证，更多的信息须要采集和存储，这就扩大了客户账户这个实体的设计。
很显然这样的业务实体变动，在接下来金融服务凋谢普惠的主旋律下是不可避免的，这也是凋谢 API 平台版本策略为什么是必须思考的一个外围治理问题，好的凋谢 API 版本策略必然须要满足以下两大准则。
准则一：平台独立性
无论外部如何实现 API，任何客户端都应该可能依照公布的规定调用 API。这就要求 API 应用凋谢的标准协议，并具备一种机制，让客户端和 Web 服务端能够就要替换的数据格式达成统一。在整个连贯过程中，API 提供方不关注客户端应用方来自于什么平台，即不因为侦测到 iOS 零碎发来的申请，就提供不同于 Android 零碎的解决和反馈。
互联网几十年的高速拓展实际上给咱们提供了一整套基于 HTTP 协定的运作机制，而这套机制是咱们举荐凋谢 API 设计者们去拥抱的。如果将浏览器比作基于 HTTP 协定的 Web 操作系统，那任何的浏览器都须要实现相干的协定规范，从而可能进行 Web 信息的申请和出现。
准则二：服务兼容性
凋谢 API 应该可能独立于客户端应用程序进行演变和增加性能。随着 API 的倒退，现有的客户端应用程序应持续运行而无需批改。而且所有性能，比方新的平安认证形式，都应该是可被发现的，以便客户端应用程序能够充沛应用它。
基于 HTTP 的 RESTful 架构也给咱们提供了很多解决兼容性的伎俩，超媒体（Hypermedia）的提出某种意义上就是为了解决网络上凋谢接口申请兼容性问题而设计的。当然超媒体的引入会带来整个接口设计、开发到运维老本的较大增长，所以在 API 设计上，针对不同的上下文（复杂度）也会有很多的解决形式。
一言以蔽之，凋谢 API 版本的致胜之道就是让应用方感觉“没有版本”，客户端从设计、开发，到公布、经营都不会因为某个 API 的降级而呈现服务中断。
支流 API 版本模式
咱们谈凋谢 API 的根底环境是互联网，所以 HTTP 毫无疑问是必须采纳的协定。如前文提到，在版本策略设计上，心愿尽量不要耦合于特定的实现模式，尽管 RESTful 是咱们举荐的实现形式，但也了解在一些场景下设计者会偏向于形容更为间接的 WebSocket 模式。
（有能力的银行也能够效仿亚马逊 AWS 提供两套实现架构，便于使用者依据本身场景灵便选用。https://aws.amazon.com/cn/api…
基于凋谢 API 的致胜准则，在解决版本升级挑战上，咱们认为有以下四种常见模式供大家参考。每种模式并非是齐全独立的，很多时候咱们看到不少凋谢 API 平台也动静采纳着多种模式。
模式一：头文件定制版本字段
因为 HTTP 协定头文件里容许定制字段的扩大，咱们能够采纳“X-MyAPIVersionRequest-Header: 2.0”这样的形式来表白申请的 myapi 是版本 2.0。
假如针对客户账户领取的一个凋谢 API，1.0 版本次要是针对同业的银行合作伙伴，心愿在 2.0 反对持牌的金融科技公司。针对金融科技公司咱们须要做额定的风控和限额，那么就能够要求金融科技企业的客户端在 API 申请中必须蕴含这样一个扩大的版本头文件字段。将来也能够针对更多的客群，比方小微商户，公布 3.0、4.0，通过版本来明确针对同一业务实体，同一操作的不同步骤。
因为是定制字段，应用方在设计本身的客户端调用时，是须要了解游戏规则的。对于 API 提供方来说做到了较好的兼容性，但扩展性却受到了肯定的制约，毕竟定制化常识的流传老本是远高于通用型规范的。
模式二：媒体类型扩大版本信息
同样是利用 HTTP 协定头文件中的承受申请媒体类型进行拓展，咱们能够要求“Accept: application/x.myapi+json;version=2.0”这样的形式来指定申请 myapi 的第二个版本。
比照第一种定制化字段的形式，这种模式利用了已有的 HTTP 头文件字段。比拟好的实用于领有默认版本抉择的 API，比方客户账户领取操作如果在不指定版本的状况下就走最严格的查看步骤（对应的版本），而一些特定机构能够走其它版本来简化步骤，以进步清理效率。
这种扩大已有字段的模式也存在比拟显著的问题，这些字段的解析有可能曾经被现有的客户端依照规范形式进行了解析和利用。比方针对媒体类型，很可能客户端进行了不同的缓存策略来晋升用户体验，这样的扭转将会让基于规范字段的客户端实现无奈利用。
模式三：路由设计版本门路
通过 HTTP 定位 API 和 Web 资源都须要通过 URI，很天然咱们也能够在 URI 上退出版本信息，比方“/v2/myapi”，通过路由来辨认申请的具体 API 版本。
如果一个 API 有多个差别较大版本，那么咱们可能就会有“/v3/myapi”、“/v4/myapi”等一系列 URI。从客户端视角，因为路由不同，所以其实能够认为每个版本都产生了一个新的 API。
这种设计尽管保障了兼容性，但新的性能实际上并没有提供给已有使用者，想用新性能还是须要客户端的扭转。而且新版本减少了 API 的数量，进步了整体经营老本。
模式四：申请参数版本字段
通过 HTTP 申请资源也容许在 URL 中带参数，利用这个个性咱们能够传递心愿申请的 API 版本，比方“/myapi?version=2”。
这种形式的可读性很好，也遵循 HTTP 的默认规范，对于 API 设计者来说比拟容易实现，但存在理论经营过程中的挑战，特地是多层级 API 调用在路由过程中参数传递的问题，某种意义上会毁坏兼容性。在一些通过 API 网关进行重定向的时候，因为路由零碎不晓得参数的意义，有可能从平安角度主动打消，造成申请真正达到服务侧时参数失落。
以上四种常见模式实际上各自有不同的适用性场景，因而很难说 API 版本策略肯定是采纳哪种模式。比方当“破坏性”扭转产生在某一个业务实体之上时，采纳显式版本路由来明确调用的 API 版本就可能是最佳形式；而仅仅是为客户端能够采纳更好的缓存技术来进步用户体验的版本改良，可能采纳头文件中的字段来标注版本就是适合的。
API 版本演进策略
读到这里，大家可能会认为必须在公布第一个 API 版本之前定义版本控制策略，否则后续 API 扭转将会面临微小的挑战。事实却并非如此，可能真正帮忙大家迎战 API 版本挑战的是策略上的灵便，依据具体业务上下文抉择适合的版本模式。
提早决策可能是件好事件
咱们都分明当初软件和零碎所面临的业务不确定性，一开始很难预期接下来针对业务实体的变动，比方当下没有人能够预言将来两年数字货币带来的新需要和新性能是什么样子的。而驾驭这样的不确定性其中的一条黄金定律就是“提早决策”，在遵循了良好凋谢 API 设计规范的根底之上，造成良好的业务和技术单干，就可能针对每个凋谢 API 保留将来扭转的灵活性。
解耦每项 API 治理工作
凋谢 API 自身是一个简单零碎，这里咱们仅仅是谈了版本治理的挑战，如果退出注册发现等机制，咱们会发现的确会相互影响，进而让策略探讨变得异样简单。咱们的倡议依然是放弃这些关注点的拆散，解耦各项治理工作，不要在一项治理策略中引入针对另外几项的依赖，比方版本策略的工作必须依赖于注册机制采纳某种特定模式。一旦开始关联这些工作，咱们就很难设计出真正意义上简略的解决方案。而咱们都晓得在凋谢的互联网生态中，唯有简略才可能长久，唯有容纳才可能生存。
起源：ThoughtWorks 商业洞见
作者：肖然
每周四晚 8 点【冬哥有话说】线上直播，4 月“DevOps 之庖丁解牛”，拆解 DevOps 的工具及具体实战。公众号留言“回放”可查看往期直播视频
- 0401《数据库继续交付流水线分享与演示（Azure DevOps+Flyway）》
- 0408《继续交付中的版本治理与基于 Azure DevOps 扩大框架的插件开发》
- 工夫待定《微服务，多团队合作中的 API 测试怎么做 – Pact 契约测试》
- 工夫待定《BoatHouse 端到端流水线展现》