Micronaut API 版本控制

从 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') 注释的客户端。

w3cschool 编程狮，随时随地学编程

Micronaut API 版本控制

默认版本

版本控制客户端请求

Micronaut 介绍

Micronaut 快速开始

Micronaut 控制反转

Micronaut 应用配置

Micronaut 面向切面编程

Micronaut HTTP 服务器

Micronaut HTTP 客户端

Micronaut 云原生特性

Micronaut 无服务器函数

Micronaut 消息驱动的微服务

Micronaut 独立命令行应用程序

Micronaut 配置

Micronaut 日志

Micronaut 语言支持

Micronaut 管理与监控

Micronaut 安全

Micronaut 多租户

Micronaut CLI

Micronaut 国际化

Micronaut 附录