版本控制子包为您的api提供完整的版本控制。它实现了api指南中编写的所有建议。

版本比较由go-version包完成。它支持匹配模式，如“>= 1.0，< 3”等。

  1. import (
  2.     // [...]
  4.     "github.com/kataras/iris/v12"
  5.     "github.com/kataras/iris/v12/versioning"
  6. )

特性

  • 每个路由版本匹配，一个正常的iris处理程序与“开关”的情况下，通过地图为版本=>处理程序
  • 每组版本化的路由和弃用API
  • 版本匹配，如”>= 1.0，< 2.0”或只是”2.0.1”等。
  • 版本未找到处理程序(可以通过简单地添加版本控制来定制。映射上的customNotMatchVersionHandler)
  • 版本从“Accept”和“Accept- version”头文件中检索(可以通过中间件定制)
  • 如果找到了版本，用“X-API-Version”标题回应。
  • 通过弃用包装器，可定制“X-API-Warn”、“X-API-Deprecation-Date”、“X-API-Deprecation-Info”的弃用选项。


获取版本

通过version . getversion (ctx)检索当前请求版本。

默认情况下，GetVersion将尝试读取:

  • Accept header, i.e Accept: "application/json; version=1.0"
  • Accept-Version header, i.e Accept-Version: "1.0"

您还可以通过中间件使用上下文的存储值为处理程序设置自定义版本。例如:

  1. func(ctx iris.Context) {
  2.     ctx.Values().Set(versioning.Key, ctx.URLParamDefault("version", "1.0"))
  3.     ctx.Next()
  4. }

将版本与处理程序匹配

versioning.NewMatcher(versioning.Map) iris.Handler 创建一个单独的处理程序，该处理程序根据请求的版本决定需要执行什么处理程序。

  1. app := iris.New()
  3. // middleware for all versions.
  4. myMiddleware := func(ctx iris.Context) {
  5.     // [...]
  6.     ctx.Next()
  7. }
  9. myCustomNotVersionFound := func(ctx iris.Context) {
  10.     ctx.StatusCode(iris.StatusNotFound)
  11.     ctx.Writef("%s version not found", versioning.GetVersion(ctx))
  12. }
  14. userAPI := app.Party("/api/user")
  15. userAPI.Get("/", myMiddleware, versioning.NewMatcher(versioning.Map{
  16.     "1.0":               sendHandler(v10Response),
  17.     ">= 2, < 3":         sendHandler(v2Response),
  18.     versioning.NotFound: myCustomNotVersionFound,
  19. }))

反对

使用 versioning.Deprecated(handler iris.Handler, options versioning.DeprecationOptions) iris.Handler 函数可以将特定的处理程序版本标记为已弃用。

  1. v10Handler := versioning.Deprecated(sendHandler(v10Response), versioning.DeprecationOptions{
  2.     // if empty defaults to: "WARNING! You are using a deprecated version of this API."
  3.     WarnMessage string 
  4.     DeprecationDate time.Time
  5.     DeprecationInfo string
  6. })
  8. userAPI.Get("/", versioning.NewMatcher(versioning.Map{
  9.     "1.0": v10Handler,
  10.     // [...]
  11. }))

这将使处理程序发送这些头到客户端:

  • "X-API-Warn": options.WarnMessage
  • "X-API-Deprecation-Date": context.FormatTime(ctx, options.DeprecationDate))
  • "X-API-Deprecation-Info": options.DeprecationInfo

版本控制。如果你不关心日期和信息，DefaultDeprecationOptions可以被传递。

按版本对路由进行分组

也可以按版本对路由进行分组。

使用versioning.NewGroup(version string) versioning.Group。可以创建一个组来注册版本化的路由。versioning.RegisterGroups(r iris.Party, versionNotFoundHandler iris.Handler, groups …versioning.Group)必须在最后被调用，以注册到一个特定的方的路由。

  1. app := iris.New()
  3. userAPI := app.Party("/api/user")
  4. // [... static serving, middlewares and etc goes here].
  6. userAPIV10 := versioning.NewGroup("1.0")
  7. userAPIV10.Get("/", sendHandler(v10Response))
  9. userAPIV2 := versioning.NewGroup(">= 2, < 3")
  10. userAPIV2.Get("/", sendHandler(v2Response))
  11. userAPIV2.Post("/", sendHandler(v2Response))
  12. userAPIV2.Put("/other", sendHandler(v2Response))
  14. versioning.RegisterGroups(userAPI, versioning.NotFoundHandler, userAPIV10, userAPIV2)

中间件可以注册到实际的iris。只有一方，使用我们在上面学到的方法，即使用版本控制。匹配，以检测当“x”或没有请求版本时您希望执行的代码/处理程序。

弃用的组

只需调用组中的Deprecated(version. deprecationoptions)通知API使用者该特定版本已被弃用。

  1. userAPIV10 := versioning.NewGroup("1.0").Deprecated(versioning.DefaultDeprecationOptions)

在处理程序内部手动比较版本

  1. // reports if the "version" is matching to the "is".
  2. // the "is" can be a constraint like ">= 1, < 3".
  3. //报告“版本”是否与“是”匹配。
  4. //“is”可以是像“>= 1，< 3”这样的约束。
  5. If(version string, is string) bool
  1. // same as `If` but expects a Context to read the requested version.
  2. // 与“If”相同，但是需要上下文来读取请求的版本。
  3. Match(ctx iris.Context, expectedVersion string) bool
  1. app.Get("/api/user", func(ctx iris.Context) {
  2.     if versioning.Match(ctx, ">= 2.2.3") {
  3.         // [logic for >= 2.2.3 version of your handler goes here]
  4.         return
  5.     }
  6. })