PHP 开发的 API 多版本管理实践

时间:2024-01-15 23:24:14

遇到的情况

本文针对移动互联网客户端需要兼容旧版的情况,强制升级到最新版本的 app 不在讨论之列。

bugtags.com 项目中,我们的版本遵循下面规范。
1.0.1
大功能.小更新.bug 修正
我们的版本列表如下:

1.0、1.1、1.2、1.3、1.4
2.0、2.1、2.2、2.3
3.0、3.1

5.0

这样一个版本结构,所有版本都可以用,跨度最大时,1.0 用户要跟 5.0 用户并存。
以 /api/user/info 接口举例,经过这么多版本的迭代,版本 1.0 跟 3.0 的返回数据结构可能已经完全不同了。
对于这样一个系统,如何设计一个完备的版本架构非常重要。

理解其中的困难

移动互联网,有别于传统的 web 开发。其快速迭代、版本升级与传统的 web 开发相比,有如下困难:

  1. 用户获取困难,留存率低
  2. 客户端升级成本高,部分用户拒绝升级
  3. 多个版本服务器端代码量大,急剧拉高维护成本

架构的目的及要求

  1. 简化版本管理流程,易配置管理
  2. 缩小服务器端的 php 代码规模
  3. 尽量不要引入新的要素

微信群里的讨论

请求形式的约定

  1. 使用域名,如 v1.api.bugtags.com 来区分接口的版本
  2. 将版本信息放到 url 的 pathinfo 中,如 api.bugtags.com/v1/
  3. 将版本信息放到请求参数中,如 api.bugtags.com/user/1?_ver=1.0.1
  4. 将版本信息放到 http header 中,如 API_VER: 1.0.1

版本号用域名是比较不被认同的方案,主要原因是域名管理往往跨部门,增加了沟通成本。
http 头是我个人最赞同的一种方式,可以保持 url 的整洁。
url 参数中携带版本号的方式也很好,但是要注意不要跟业务逻辑的参数名重复。

两种常见的管理代码的方式

git/svn 的 tag 管理方式

优点,随时切换分支成本低,尤其在 git 管理代码时。
缺点,如果多个版本需要修改时,代码合并工作量大。

只有一个分支,在代码中根据版本信息做判断

优点,代码的总体规模小(只有一份代码)
缺点,在需要判断版本的地方会有大量的分支语句

我总结的解决办法

最后的解决办法充分利用了 php 的 autoload 加载机制和命名空间。

  1. 假设 base 是所有业务的基础,是第一个版本,也是生命周期最长的版本。
  2. v10 对版本 1.x.x 提供服务,最大限度消除业务点上的版本逻辑判断,但是不绝对拒绝。
  3. v20/v30 基于 v10 版本开发
  4. v40 版本基于 v30 版本开发

PHP 开发的 API 多版本管理实践

举例说明

v10 提供 a,b,c 三个接口
v20 提供 a1,b,c 三个接口, a1 是 a 的修改
v30 提供 a,b1,c 三个接口, b1 是 b 的修改

用下面三段代码来具体描述

<?php
/**
* View/Api/Base/Config/Config.php
*/
namespace View\Api\Config;
class Config {
function index(){echo __METHOD__;}
}
?>
<?php
/**
* View/Api/V10/Config/Config.php
*/
namespace View\Api\Config;
class Config {
function index(){echo __METHOD__;}
}
?>
<?php
/**
* View/Api/V20/Config/Config.php
*/
namespace View\Api\Config;
class Config {
function index(){echo __METHOD__;}
}
?>

配置版本:

访问版本 代码版本
v10 base
v11 base
v20 v10
v30 v10
  • 基础目录 base 存放大部分公共代码
  • 版本目录 v10/v20 都是版本目录,里面存放此版本与 基础版本不同的逻辑
  • 版本区别以文件为最小粒度,以上面三段代码可以看出。

用户要访问 /api/user/info?ver=3.0.1 此时,类的加载顺序依次为:

  1. 在 v30 下尝试加载 Config.php 失败
  2. 在 v10 下尝试加载 Config.php 失败
  3. 在 Base 下尝试加载 Config.php 成功
  4. 执行相关逻辑

这是限制只能继承一层的原因是尽可能的降低系统的复杂度。这种方式管理代码已经在几个项目中得到一些验证。系统代码的复杂度可以很大程度上降低,尤其是多个版本迭代、又不能强制升级的系统中。另外需要注意的就是 :

  1. 使用这个方式处理加载时,在经过几个版本的沉淀后,应该将通用部分渐渐沉淀到BASE版本中
  2. 发布系统最好带有删除文件功能,否则被部分沉淀后,高版本会依旧使用高版本的代码。

笔者在开发和运营 bugtags.com ,这是一款能够极大的提升 app 开发者测试效率的 SDK 产品,欢迎使用、转发推荐。

PHP 开发的 API 多版本管理实践