重构 关于 API 项目,版本迭代,兼容旧的版本

wangping · September 06, 2015 · Last by jimrokliu replied at September 07, 2015 · 10469 hits

用 grape 部署的独立的 api 项目,怎么样的迭代比较好呢?

比如从 v1 升到 v2. etc: /v1/main_page to /v2/main_page

其实有很多的接口可能不会变,可能就是改了几个接口,加了几个接口,但是对于整个项目几百个接口来说可能只是很少的一部分。 那么是否有必要全部接口升为为 v2, 也就是备份一份,还是不变,只是有变化的去增加。 (我们现在的做法是 androoid 和 ios 各一份,然后 不增加版本号,每次在接口用代码的手段进行兼容,不行的时候加接口,感觉不是很妙~~~)

还有有一个兼容旧版本,一般兼容多少个版本呢,有经验的聊聊呗~~~

个人经验,不知是否有帮助. 对版本接口维护,个人认为是灾难性的。不同版本的业务逻辑,需要操作最新版本的数据结构。同时还要维护各版本的文档,各版本的自动化测试或者人工测试 ok.

所以个人认为比较好的做法是。

在开始设计的时候, 查询类的接口,应尽可能使用被动式提供数据的无状态接口,格式应竟可能使用对象 (不使用二维的集合).这样的接口对于扩展字段非常的方便,也很容易做到向下兼容. 操作类的接口,尽可能地将资源分离,比如修改用户信息,跟修改用户头像信息或者修改用户职位信息,这样的接口,尽可能使用独立的资源。

对于实在没有办法需要全面升级接口的. 如果可能,保持原有的业务,原有的接口运转正常. 然后构建一套全新的隔离的接口. 最后做下版本使用监控。当观察到所有用户都使用新版本的客户端的时候,并保持一段时间的时候。放弃对老版本的维护,继而下掉老版本的资源。当然,万不得已的时候,还可以用强制更新。

虽然 copy 一份到 v2 的工作量不小,但是升级版本并不会很频繁。而通过代码手段兼容接口,虽然爽了这一时,后期很可能灾难性地难以维护 所以我还是倾向于 copy 一份出来

#1 楼 @luax 也就是说首先代码控制,然后实在不行就 copy 一份?

@wangping 不是的,我的意思是在设计的时候,规避这种情况。规避这种情况的方法有这么几种,

1.数据查询类的比较简单。比如一个商品接口,原先没有提供多图,后来需要提供多图的,简单的增加一个多图集合字段就可以。又比如商品需要增加优惠券信息,再增加优惠券的扩展字段就可以。

这样的增量接口,对于老的自动化测试来说,不会失效,仍然可以跑。这种都是比较简单的。

2 操作类的接口,尽可能的原子化,这样修改该一个功能的时候影响比较小。但是一般人都不太会犯这样的错误

3 比较难搞的是数据结构设计不合理。其实用楼主的方案比较可取,那就是新增一个接口。只能说尽可能避免。

V2 那种涉及大面积重构的. 建议是先保证原来的接口运转正常。然后监控客户端升级状态。

之前我用过继承的方法来处理。这样同样的代码不需要重复去写。小 bug 就直接修掉,真要有功能变更什么的。加一个版本。可以保证新老 api 都可以正常使用,然后后期通过访问的 api 版本。然后去考虑合并版本号。

如果逻辑基本没改,可以 v1 和 v2 都引用同一个 controller/action 的组合,这样只多加几条 routes。我觉得最关键的还是保证修改代码不会导致老版本 API 行为发生改变或者挂掉。这点只能多加 request 测试,给每个 API response 校验 JSON schema。

有规格测试吗?否则搞多版本你会死的很惨。

You need to Sign in before reply, if you don't have an account, please Sign up first.