PHP `API Versioning` 策略：`URI`, `Header`, `Query Parameter`

各位观众老爷，大家好！今天咱们聊聊PHP API的版本控制，这可是个让多少英雄好汉挠破头的课题。别怕，今天咱们就用大白话，把这事儿掰开了揉碎了，让大家彻底明白！

想象一下，你开发了一个超牛的API，用户嗷嗷待哺。结果呢？需求天天变，昨天说要加个字段，今天说要改个算法。你改吧，用户炸锅了：“大哥，我代码都写好了，你这么一改，我全白费了！”。这就是API版本控制的意义所在，它能让你的API在升级迭代的同时，保证老用户不受影响。

我们今天主要讲三种常见的API版本控制策略：URI版本控制、Header版本控制和Query Parameter版本控制。咱们一个一个来，保证你听得懂，学得会！

一、URI版本控制：最直接的“贴标签”方式

URI版本控制，顾名思义，就是把版本号直接放在API的URL里。这就像给每个版本的API贴个标签，简单粗暴，一眼就能看出来。

优点：

• 简单易懂： 用户一看URL就知道用的是哪个版本的API。
• 易于实现： 服务器端路由配置也很方便。
• 可缓存性好： 不同版本的API URL不同，可以利用HTTP缓存。

缺点：

• URL冗余： 版本号会显得有点“碍眼”，不够优雅。
• 路由配置复杂： 如果API数量很多，路由配置会比较繁琐。

代码示例：

假设我们的API是用来获取用户信息的，URI版本控制的URL可能是这样的：

• api.example.com/v1/users (v1版本)
• api.example.com/v2/users (v2版本)

PHP实现 (使用Laravel框架为例):

<?php

namespace AppHttpControllersApi;

use AppHttpControllersController;
use AppModelsUser;
use IlluminateHttpRequest;

class UserController extends Controller
{
    // v1版本
    public function v1_index()
    {
        $users = User::all();
        return response()->json($users);
    }

    // v2版本
    public function v2_index()
    {
        $users = User::paginate(10); // 使用分页
        return response()->json($users);
    }
}

routes/api.php:

<?php

use IlluminateSupportFacadesRoute;
use AppHttpControllersApiUserController;

Route::prefix('v1')->group(function () {
    Route::get('users', [UserController::class, 'v1_index']);
});

Route::prefix('v2')->group(function () {
    Route::get('users', [UserController::class, 'v2_index']);
});

解释：

• 我们定义了两个路由组，分别对应v1和v2版本。
• 每个路由组都关联到UserController的不同方法(v1_index和v2_index)。
• v1_index返回所有用户，v2_index返回分页后的用户（每页10个）。

这样，用户访问api.example.com/v1/users就会调用v1_index方法，访问api.example.com/v2/users就会调用v2_index方法。

二、Header版本控制：隐藏的“暗号”

Header版本控制，就是通过HTTP请求头来指定API的版本。这就像在请求头里加了个“暗号”，服务器通过这个“暗号”来判断应该返回哪个版本的数据。

优点：

• URL简洁： URL比较干净，没有版本号。
• 语义清晰： HTTP Header本来就是用来传递元数据的，用它来传递版本信息也算合理。

缺点：

• 用户不易发现： 用户需要查看HTTP Header才能知道API的版本。
• 实现稍复杂： 服务器端需要解析HTTP Header。
• 可缓存性稍差： 部分HTTP缓存服务器可能忽略自定义Header。

常见的Header：

• Accept： 指定客户端能接受的MIME类型，可以用来区分版本。例如：Accept: application/vnd.example.v1+json
• Content-Type： 指定请求体的MIME类型，也可以用来区分版本。例如：Content-Type: application/vnd.example.v2+json
• X-API-Version： 自定义的Header，例如：X-API-Version: 2.0

代码示例：

假设我们使用自定义Header X-API-Version来控制版本。

PHP实现 (使用Laravel框架为例):

<?php

namespace AppHttpControllersApi;

use AppHttpControllersController;
use AppModelsUser;
use IlluminateHttpRequest;

class UserController extends Controller
{
    public function index(Request $request)
    {
        $version = $request->header('X-API-Version');

        if ($version == '1') {
            $users = User::all();
            return response()->json($users);
        } elseif ($version == '2') {
            $users = User::paginate(10);
            return response()->json($users);
        } else {
            return response()->json(['error' => 'Unsupported API version'], 400);
        }
    }
}

routes/api.php:

<?php

use IlluminateSupportFacadesRoute;
use AppHttpControllersApiUserController;

Route::get('users', [UserController::class, 'index']);

解释：

• 我们只有一个路由/users，所有的版本控制逻辑都在UserController@index方法里。
• $request->header('X-API-Version') 获取请求头中的X-API-Version值。
• 根据X-API-Version的值，返回不同版本的数据。
• 如果X-API-Version的值不在支持的范围内，返回错误信息。

用户需要在请求头中添加X-API-Version: 1或X-API-Version: 2来指定API版本。

三、Query Parameter版本控制：灵活的“小尾巴”

Query Parameter版本控制，就是通过URL的查询参数来指定API的版本。这就像在URL后面加了个“小尾巴”，告诉服务器要哪个版本的数据。

优点：

• 简单易用： 用户只需要在URL后面添加一个查询参数。
• 灵活方便： 可以很方便地在客户端修改版本号。
• 可缓存性好： 不同版本的API URL不同，可以利用HTTP缓存。

缺点：

• URL冗余： URL会比较长，不够美观。
• 语义不清晰： 查询参数通常用来传递过滤条件，用它来传递版本信息可能不太符合语义。

代码示例：

假设我们使用查询参数version来控制版本。

PHP实现 (使用Laravel框架为例):

<?php

namespace AppHttpControllersApi;

use AppHttpControllersController;
use AppModelsUser;
use IlluminateHttpRequest;

class UserController extends Controller
{
    public function index(Request $request)
    {
        $version = $request->query('version');

        if ($version == '1') {
            $users = User::all();
            return response()->json($users);
        } elseif ($version == '2') {
            $users = User::paginate(10);
            return response()->json($users);
        } else {
            return response()->json(['error' => 'Unsupported API version'], 400);
        }
    }
}

routes/api.php:

<?php

use IlluminateSupportFacadesRoute;
use AppHttpControllersApiUserController;

Route::get('users', [UserController::class, 'index']);

解释：

• 我们只有一个路由/users，所有的版本控制逻辑都在UserController@index方法里。
• $request->query('version') 获取URL中的version查询参数的值。
• 根据version的值，返回不同版本的数据。
• 如果version的值不在支持的范围内，返回错误信息。

用户需要访问api.example.com/users?version=1或api.example.com/users?version=2来指定API版本。

四、选择哪个策略？

好了，三种策略都讲完了，那么问题来了，到底选哪个呢？ 这其实没有绝对的答案，要根据你的具体情况来决定。

特性	URI版本控制	Header版本控制	Query Parameter版本控制
简洁性	较差	优秀	较差
易用性	优秀	较差	优秀
可发现性	优秀	较差	一般
缓存友好度	优秀	一般	优秀
语义性	一般	优秀	较差

• 如果你追求简单粗暴，一眼就能看出来版本，那就选URI版本控制。
• 如果你追求URL的简洁，不想让版本号“碍眼”，那就选Header版本控制。
• 如果你追求灵活方便，想让用户可以随时修改版本，那就选Query Parameter版本控制。

当然，你也可以混合使用这些策略。例如，你可以使用URI版本控制作为主要方式，然后使用Header版本控制作为补充。

五、一些最佳实践

除了选择合适的版本控制策略，还有一些最佳实践可以帮助你更好地管理API版本：

• 保持向后兼容： 尽量避免破坏性的变更。如果必须进行破坏性变更，请提前通知用户，并提供迁移指南。
• 提供默认版本： 如果没有指定版本号，则返回默认版本的数据。
• 废弃旧版本： 不要无限期地维护所有版本。当某个版本不再使用时，请及时废弃它。
• 使用API网关： API网关可以帮助你更好地管理API版本，例如路由、认证、授权等。
• 自动化测试： 为每个版本的API编写自动化测试，确保API的质量。
• 文档！文档！文档！： 为每个版本的API编写详细的文档，让用户知道如何使用。

六、实战案例：一个电商API的版本控制

假设我们正在开发一个电商API，用于获取商品信息。

需求：

• v1版本：返回商品的ID、名称和价格。
• v2版本：返回商品的ID、名称、价格和描述。

选择URI版本控制：

URL：

• api.example.com/v1/products (v1版本)
• api.example.com/v2/products (v2版本)

PHP实现 (使用Laravel框架为例):

<?php

namespace AppHttpControllersApi;

use AppHttpControllersController;
use AppModelsProduct;
use IlluminateHttpRequest;

class ProductController extends Controller
{
    // v1版本
    public function v1_index()
    {
        $products = Product::select('id', 'name', 'price')->get();
        return response()->json($products);
    }

    // v2版本
    public function v2_index()
    {
        $products = Product::all();
        return response()->json($products);
    }
}

routes/api.php:

<?php

use IlluminateSupportFacadesRoute;
use AppHttpControllersApiProductController;

Route::prefix('v1')->group(function () {
    Route::get('products', [ProductController::class, 'v1_index']);
});

Route::prefix('v2')->group(function () {
    Route::get('products', [ProductController::class, 'v2_index']);
});

返回结果：

v1版本：

[
  {
    "id": 1,
    "name": "iPhone 14",
    "price": 799
  },
  {
    "id": 2,
    "name": "Samsung Galaxy S23",
    "price": 699
  }
]

v2版本：

[
  {
    "id": 1,
    "name": "iPhone 14",
    "price": 799,
    "description": "The latest iPhone with a stunning display and powerful performance."
  },
  {
    "id": 2,
    "name": "Samsung Galaxy S23",
    "price": 699,
    "description": "The new Samsung Galaxy with advanced camera and long-lasting battery."
  }
]

七、总结

API版本控制是个重要的课题，它可以让你在快速迭代的同时，保证老用户不受影响。 今天我们讲了三种常见的版本控制策略：URI版本控制、Header版本控制和Query Parameter版本控制。 希望通过今天的讲解，大家能够对API版本控制有更深入的了解，并在实际项目中灵活运用。

记住，没有最好的策略，只有最适合你的策略。 选择一个适合你的策略，并坚持下去，你的API就会越来越健壮！

好了，今天的讲座就到这里。 感谢大家的收听！ 如果有什么问题，欢迎提问。 咱们下次再见！