Micronaut API 版本控制

2023-03-06 16:23 更新

從 1.1.x 開始，Micronaut 通過專用的 @Version 注解支持 API 版本控制。

以下示例演示了如何對(duì) API 進(jìn)行版本控制：

對(duì) API 進(jìn)行版本控制

 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"
    }

  1. helloV1 方法聲明為版本 1

  2. helloV2 方法聲明為版本 2

然后通過在配置文件（例如 application.yml）中將 micronaut.router.versioning.enabled 設(shè)置為 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
      }
    }
  }
}

默認(rèn)情況下，Micronaut 有兩種基于名為 X-API-VERSION 的 HTTP 標(biāo)頭或名為 api-version 的請(qǐng)求參數(shù)來解析版本的策略，但這是可配置的。完整的配置示例如下所示：

配置版本控制

 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 啟用或禁用基于參數(shù)的版本控制

  • parameter.names 將參數(shù)名稱指定為逗號(hào)分隔的列表

  • header.enabled 啟用或禁用基于標(biāo)頭的版本控制

  • header.names 將標(biāo)題名稱指定為列表

如果這還不夠，您還可以實(shí)現(xiàn)接收 HttpRequest 的 RequestVersionResolver 接口，并可以實(shí)現(xiàn)您選擇的任何策略。

默認(rèn)版本

可以通過配置提供默認(rèn)版本。

配置默認(rèn)版本

 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
      }
    }
  }
}

  • 此示例啟用版本控制并設(shè)置默認(rèn)版本

如果滿足以下條件，則路由不匹配：

  • 配置默認(rèn)版本

  • 請(qǐng)求中找不到版本

  • 路由定義了一個(gè)版本

  • 路由版本與默認(rèn)版本不匹配

如果傳入請(qǐng)求指定了版本，則默認(rèn)版本無效。

版本控制客戶端請(qǐng)求

Micronaut 的聲明式 HTTP 客戶端還支持通過 @Version 注釋對(duì)傳出請(qǐng)求進(jìn)行自動(dòng)版本控制。

默認(rèn)情況下，如果您使用 @Version 注釋客戶端接口，則提供給注釋的值將使用 X-API-VERSION 標(biāo)頭包含在內(nèi)。

例如：

 JavaGroovy 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)
}

  1. @Version 注釋可以在類型級(jí)別使用來指定要用于所有方法的版本

  2. 在方法級(jí)別定義時(shí)，它僅用于該方法

可以使用 DefaultClientVersioningConfiguration 配置每次調(diào)用發(fā)送版本的默認(rèn)行為：

表 1. DefaultClientVersioningConfiguration 的配置屬性
屬性 類型 描述

micronaut.http.client.versioning.default.headers

java.util.List

請(qǐng)求標(biāo)頭名稱列表。

micronaut.http.client.versioning.default.parameters

java.util.List

請(qǐng)求查詢參數(shù)名稱列表。

例如使用 Accept-Version 作為標(biāo)頭名稱：

配置客戶端版本控制

 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"]
          }
        }
      }
    }
  }
}

默認(rèn)鍵是指默認(rèn)配置。您可以使用傳遞給@Client 的值（通常是服務(wù) 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"]
          }
        }
      }
    }
  }
}

上面使用了一個(gè)名為 greeting-service 的鍵，它可以用來配置一個(gè)用@Client('greeting-service') 注釋的客戶端。


以上內(nèi)容是否對(duì)您有幫助：
在線筆記
App下載
App下載

掃描二維碼

下載編程獅App

公眾號(hào)
微信公眾號(hào)

編程獅公眾號(hào)