跳到主要内容

实施 API 版本控制

在软件开发的动态环境中，维护强大且灵活的 API 对于构建可扩展和可互操作的系统至关重要。随着软件随时间演进，不可避免地需要对 API 进行更改和更新。API 版本控制提供了一种系统的方法来引入重大更改，同时保持向后兼容性。

在本指南中，你将了解几种不同的 API 版本控制策略以及如何在 APISIX 中实施它们。

前置条件​

  • 安装 Docker。
  • 安装 cURL 以向服务发送请求进行验证。
  • 按照 快速入门教程 在 Docker 或 Kubernetes 中启动一个新的 APISIX 实例。

基于路径的版本控制​

基于路径的版本控制是 API 版本控制最流行的方法之一，它涉及将版本号直接合并到 API 端点的 URL 路径中，例如：

https://apis.yourdomain.com/v1/foo
https://apis.yourdomain.com/v2/foo

要在 APISIX 中实施此策略，请为每个 API 版本创建一个路由，如下所示：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT -d '
{
  "id": "apis-v1",
  "uri": "/v1/*",
  "upstream": {
    "type": "roundrobin",
    "nodes": {
      "https://apis.yourdomain.com": 1
    },
    "pass_host": "node",
    "scheme": "https"
  }
}'
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT -d '
{
  "id": "apis-v2",
  "uri": "/v2/*",
  "upstream": {
    "type": "roundrobin",
    "nodes": {
      "https://apis.yourdomain.com": 1
    },
    "pass_host": "node",
    "scheme": "https"
  }
}'

基于查询的版本控制​

基于查询的版本控制是另一种 API 版本控制方法，它涉及将版本号合并到 URL 查询参数中，例如：

https://apis.yourdomain.com/foo?version=1
https://apis.yourdomain.com/foo?version=2

要在 APISIX 中实施此策略，请为每个 API 版本创建一个路由，并配置其匹配条件和优先级，如下所示：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT -d '
{
  "id": "apis-v1",
  "uri": "/*",
  "vars": [[ "arg_version", "==", "1" ]],
  "priority": 2,
  "upstream": {
    "type": "roundrobin",
    "nodes": {
      "https://apis.yourdomain.com": 1
    },
    "pass_host": "node",
    "scheme": "https"
  }
}'
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT -d '
{
  "id": "apis-v2",
  "uri": "/*",
  "vars": [[ "arg_version", "==", "2" ]],
  "priority": 3,
  "upstream": {
    "type": "roundrobin",
    "nodes": {
      "https://apis.yourdomain.com": 1
    },
    "pass_host": "node",
    "scheme": "https"
  }
}'

由于两个路由都配置为匹配相同的 URI，设置优先级将允许具有较高优先级的路由首先匹配请求。

基于标头的版本控制​

第三种 API 版本控制方法是使用 HTTP 标头进行版本控制。版本可以包含在自定义标头中，例如：

GET /foo HTTP/1.1
...
Api-Version: 1
GET /foo HTTP/1.1
...
Api-Version: 2

要在 APISIX 中实施此策略，请为每个 API 版本创建一个路由，并配置其匹配条件和优先级，如下所示：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT -d '
{
  "id": "apis-v1",
  "uri": "/*",
  "vars": [[ "http_api_version", "==", "1" ]],
  "priority": 2,
  "upstream": {
    "type": "roundrobin",
    "nodes": {
      "https://apis.yourdomain.com": 1
    },
    "pass_host": "node",
    "scheme": "https"
  }
}'
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT -d '
{
  "id": "apis-v2",
  "uri": "/*",
  "vars": [[ "http_api_version", "==", "2" ]],
  "priority": 3,
  "upstream": {
    "type": "roundrobin",
    "nodes": {
      "https://apis.yourdomain.com": 1
    },
    "pass_host": "node",
    "scheme": "https"
  }
}'

相应地调整标头过滤条件，例如当 内容协商 用于版本控制时。

由于两个路由都配置为匹配相同的 URI，设置优先级将允许具有较高优先级的路由首先匹配请求。

下一步​

版本 API 时,您通常需要将请求转发到不同的URI路径,而不是原来的请求路径,或者将请求从已贬值的端点转向版本化的端点. 关于请求重写,见proxy-rewrite插件.