Micronaut API 版本控制

2023-03-06 16:23 更新

从 1.1.x 开始，Micronaut 通过专用的 @Version 注解支持 API 版本控制。

以下示例演示了如何对 API 进行版本控制：

对 API 进行版本控制

Java Groovy Kotlin

import io.micronaut.core.version.annotation.Version;
import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Get;

@Controller("/versioned")
class VersionedController {

    @Version("1") // (1)
    @Get("/hello")
    String helloV1() {
        return "helloV1";
    }

    @Version("2") // (2)
    @Get("/hello")
    String helloV2() {
        return "helloV2";
    }

import io.micronaut.core.version.annotation.Version
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Get

@Controller("/versioned")
class VersionedController {

    @Version("1") // (1)
    @Get("/hello")
    String helloV1() {
        "helloV1"
    }

    @Version("2") // (2)
    @Get("/hello")
    String helloV2() {
        "helloV2"
    }

import io.micronaut.core.version.annotation.Version
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Get

@Controller("/versioned")
internal class VersionedController {

    @Version("1") // (1)
    @Get("/hello")
    fun helloV1(): String {
        return "helloV1"
    }

    @Version("2") // (2)
    @Get("/hello")
    fun helloV2(): String {
        return "helloV2"
    }

helloV1 方法声明为版本 1
helloV2 方法声明为版本 2

然后通过在配置文件（例如 application.yml）中将 micronaut.router.versioning.enabled 设置为 true 来启用版本控制：

启用版本控制

Properties Yaml Toml Groovy Hocon JSON

micronaut.router.versioning.enabled=true

micronaut:
  router:
    versioning:
      enabled: true

[micronaut]
  [micronaut.router]
    [micronaut.router.versioning]
      enabled=true

micronaut {
  router {
    versioning {
      enabled = true
    }
  }
}

{
  micronaut {
    router {
      versioning {
        enabled = true
      }
    }
  }
}

{
  "micronaut": {
    "router": {
      "versioning": {
        "enabled": true
      }
    }
  }
}

默认情况下，Micronaut 有两种基于名为 X-API-VERSION 的 HTTP 标头或名为 api-version 的请求参数来解析版本的策略，但这是可配置的。完整的配置示例如下所示：

配置版本控制

Properties Yaml Toml Groovy Hocon JSON

micronaut.router.versioning.enabled=true
micronaut.router.versioning.parameter.enabled=false
micronaut.router.versioning.parameter.names=v,api-version
micronaut.router.versioning.header.enabled=true
micronaut.router.versioning.header.names[0]=X-API-VERSION
micronaut.router.versioning.header.names[1]=Accept-Version

micronaut:
  router:
    versioning:
      enabled: true
      parameter:
        enabled: false
        names: 'v,api-version'
      header:
        enabled: true
        names:
          - 'X-API-VERSION'
          - 'Accept-Version'

[micronaut]
  [micronaut.router]
    [micronaut.router.versioning]
      enabled=true
      [micronaut.router.versioning.parameter]
        enabled=false
        names="v,api-version"
      [micronaut.router.versioning.header]
        enabled=true
        names=[
          "X-API-VERSION",
          "Accept-Version"
        ]

micronaut {
  router {
    versioning {
      enabled = true
      parameter {
        enabled = false
        names = "v,api-version"
      }
      header {
        enabled = true
        names = ["X-API-VERSION", "Accept-Version"]
      }
    }
  }
}

{
  micronaut {
    router {
      versioning {
        enabled = true
        parameter {
          enabled = false
          names = "v,api-version"
        }
        header {
          enabled = true
          names = ["X-API-VERSION", "Accept-Version"]
        }
      }
    }
  }
}

{
  "micronaut": {
    "router": {
      "versioning": {
        "enabled": true,
        "parameter": {
          "enabled": false,
          "names": "v,api-version"
        },
        "header": {
          "enabled": true,
          "names": ["X-API-VERSION", "Accept-Version"]
        }
      }
    }
  }
}

此示例启用版本控制
parameter.enabled 启用或禁用基于参数的版本控制
parameter.names 将参数名称指定为逗号分隔的列表
header.enabled 启用或禁用基于标头的版本控制
header.names 将标题名称指定为列表

如果这还不够，您还可以实现接收 HttpRequest 的 RequestVersionResolver 接口，并可以实现您选择的任何策略。

默认版本

可以通过配置提供默认版本。

配置默认版本

Properties Yaml Toml Groovy Hocon JSON

micronaut.router.versioning.enabled=true
micronaut.router.versioning.default-version=3

micronaut:
  router:
    versioning:
      enabled: true
      default-version: 3

[micronaut]
  [micronaut.router]
    [micronaut.router.versioning]
      enabled=true
      default-version=3

micronaut {
  router {
    versioning {
      enabled = true
      defaultVersion = 3
    }
  }
}

{
  micronaut {
    router {
      versioning {
        enabled = true
        default-version = 3
      }
    }
  }
}

{
  "micronaut": {
    "router": {
      "versioning": {
        "enabled": true,
        "default-version": 3
      }
    }
  }
}

此示例启用版本控制并设置默认版本

如果满足以下条件，则路由不匹配：

配置默认版本
请求中找不到版本
路由定义了一个版本
路由版本与默认版本不匹配

如果传入请求指定了版本，则默认版本无效。

版本控制客户端请求

Micronaut 的声明式 HTTP 客户端还支持通过 @Version 注释对传出请求进行自动版本控制。

默认情况下，如果您使用 @Version 注释客户端接口，则提供给注释的值将使用 X-API-VERSION 标头包含在内。

例如：

Java Groovy Kotlin

import io.micronaut.core.version.annotation.Version;
import io.micronaut.http.annotation.Get;
import io.micronaut.http.client.annotation.Client;
import org.reactivestreams.Publisher;
import io.micronaut.core.async.annotation.SingleResult;

@Client("/hello")
@Version("1") // (1)
public interface HelloClient {

    @Get("/greeting/{name}")
    String sayHello(String name);

    @Version("2")
    @Get("/greeting/{name}")
    @SingleResult
    Publisher<String> sayHelloTwo(String name); // (2)
}

import io.micronaut.core.version.annotation.Version
import io.micronaut.http.annotation.Get
import io.micronaut.http.client.annotation.Client
import reactor.core.publisher.Mono


@Client("/hello")
@Version("1") // (1)
interface HelloClient {

    @Get("/greeting/{name}")
    String sayHello(String name)

    @Version("2")
    @Get("/greeting/{name}")
    Mono<String> sayHelloTwo(String name) // (2)
}

import io.micronaut.core.version.annotation.Version
import io.micronaut.http.annotation.Get
import io.micronaut.http.client.annotation.Client
import reactor.core.publisher.Mono

@Client("/hello")
@Version("1") // (1)
interface HelloClient {

    @Get("/greeting/{name}")
    fun sayHello(name : String) : String

    @Version("2")
    @Get("/greeting/{name}")
    fun sayHelloTwo(name : String) : Mono<String>  // (2)
}

@Version 注释可以在类型级别使用来指定要用于所有方法的版本
在方法级别定义时，它仅用于该方法

可以使用 DefaultClientVersioningConfiguration 配置每次调用发送版本的默认行为：

表 1. DefaultClientVersioningConfiguration 的配置属性
属性	类型	描述
`micronaut.http.client.versioning.default.headers`	java.util.List	请求标头名称列表。
`micronaut.http.client.versioning.default.parameters`	java.util.List	请求查询参数名称列表。

例如使用 Accept-Version 作为标头名称：

配置客户端版本控制

Properties Yaml Toml Groovy Hocon JSON

micronaut.http.client.versioning.default.headers[0]=Accept-Version
micronaut.http.client.versioning.default.headers[1]=X-API-VERSION

micronaut:
  http:
    client:
      versioning:
        default:
          headers:
            - 'Accept-Version'
            - 'X-API-VERSION'

[micronaut]
  [micronaut.http]
    [micronaut.http.client]
      [micronaut.http.client.versioning]
        [micronaut.http.client.versioning.default]
          headers=[
            "Accept-Version",
            "X-API-VERSION"
          ]

micronaut {
  http {
    client {
      versioning {
        'default' {
          headers = ["Accept-Version", "X-API-VERSION"]
        }
      }
    }
  }
}

{
  micronaut {
    http {
      client {
        versioning {
          default {
            headers = ["Accept-Version", "X-API-VERSION"]
          }
        }
      }
    }
  }
}

{
  "micronaut": {
    "http": {
      "client": {
        "versioning": {
          "default": {
            "headers": ["Accept-Version", "X-API-VERSION"]
          }
        }
      }
    }
  }
}

默认键是指默认配置。您可以使用传递给@Client 的值（通常是服务 ID）来指定特定于客户端的配置。例如：

配置版本控制

Properties Yaml Toml Groovy Hocon JSON

micronaut.http.client.versioning.greeting-service.headers[0]=Accept-Version
micronaut.http.client.versioning.greeting-service.headers[1]=X-API-VERSION

micronaut:
  http:
    client:
      versioning:
        greeting-service:
          headers:
            - 'Accept-Version'
            - 'X-API-VERSION'

[micronaut]
  [micronaut.http]
    [micronaut.http.client]
      [micronaut.http.client.versioning]
        [micronaut.http.client.versioning.greeting-service]
          headers=[
            "Accept-Version",
            "X-API-VERSION"
          ]

micronaut {
  http {
    client {
      versioning {
        greetingService {
          headers = ["Accept-Version", "X-API-VERSION"]
        }
      }
    }
  }
}

{
  micronaut {
    http {
      client {
        versioning {
          greeting-service {
            headers = ["Accept-Version", "X-API-VERSION"]
          }
        }
      }
    }
  }
}

{
  "micronaut": {
    "http": {
      "client": {
        "versioning": {
          "greeting-service": {
            "headers": ["Accept-Version", "X-API-VERSION"]
          }
        }
      }
    }
  }
}

上面使用了一个名为 greeting-service 的键，它可以用来配置一个用@Client('greeting-service') 注释的客户端。

以上内容是否对您有帮助：