在 Go 中，Huma 是一个相对较新的框架，旨在简化和增强构建 RESTful API 的体验。它基于 Go 的标准库 net/http，并在其基础上引入了简化路由定义、验证、文档生成等功能，使得 API 开发更加高效。

版本控制是开发 API 时的一个重要概念，它允许我们在 API 变化时保持兼容性，并确保不同版本的客户端能够顺利地与服务端交互。在 Go Huma 中，版本控制通常是在路由层面上进行管理的。

---

1. Go Huma 版本控制基础

在 Huma 中，版本控制通常通过 API 路由的路径、路由组或自定义的中间件来处理。版本控制的目标是能够在 API 版本发生变化时，确保现有客户端不会受到影响，同时允许新版本的 API 提供新的功能或改变已有的行为。

2. 常见的版本控制策略

有几种常见的 API 版本控制策略，Go Huma 可以通过这些策略来组织 API 路由。

2.1 路径版本控制

路径版本控制是最常见的版本控制方式，它通过在 API 路径中指定版本号来区分不同的 API 版本。例如，/v1/users 表示版本 1 的用户 API，/v2/users 表示版本 2 的用户 API。

在 Huma 中，我们可以通过路由组来实现这一策略：

package main

import (
    "fmt"
    "github.com/dizzyfool/huma"
    "net/http"
)

func main() {
    // 创建一个新的 Huma API 实例
    api := huma.NewAPI("My API", "1.0")

    // 路由版本控制: v1
    api.Route("/v1/users", func(r huma.Router) {
        r.Get("/profile").HandleFunc(func(w http.ResponseWriter, r *http.Request) {
            fmt.Fprintln(w, "v1 Profile")
        })
    })

    // 路由版本控制: v2
    api.Route("/v2/users", func(r huma.Router) {
        r.Get("/profile").HandleFunc(func(w http.ResponseWriter, r *http.Request) {
            fmt.Fprintln(w, "v2 Profile with new fields")
        })
    })

    http.ListenAndServe(":8080", api)
}

在上面的例子中，我们通过 api.Route() 为每个版本定义了不同的路由组。在版本 v1 中，/v1/users/profile 路径指向旧的 API 实现，而 v2 则可能有不同的字段或行为，指向新的 API 实现。

2.2 子路由版本控制

另一种常见的做法是通过子路由控制版本。如果你希望版本控制在一个功能模块中进行，而不是在整个 API 路径中，子路由版本控制会是一个理想选择。

package main

import (
    "fmt"
    "github.com/dizzyfool/huma"
    "net/http"
)

func main() {
    // 创建一个新的 Huma API 实例
    api := huma.NewAPI("My API", "1.0")

    // 定义 /users 路由组
    users := api.Route("/users", func(r huma.Router) {
        // 版本控制: v1
        r.Route("/v1", func(r huma.Router) {
            r.Get("/profile").HandleFunc(func(w http.ResponseWriter, r *http.Request) {
                fmt.Fprintln(w, "v1 Profile")
            })
        })
        // 版本控制: v2
        r.Route("/v2", func(r huma.Router) {
            r.Get("/profile").HandleFunc(func(w http.ResponseWriter, r *http.Request) {
                fmt.Fprintln(w, "v2 Profile with new fields")
            })
        })
    })

    // 启动 HTTP 服务
    http.ListenAndServe(":8080", users)
}

在这个例子中，我们定义了 /users/v1 和 /users/v2 路由，两个版本的 API 路径在同一组下。通过子路由版本控制，可以将不同版本的 API 聚合到一个主要功能模块下，结构更加清晰。

2.3 请求头版本控制

对于某些场景，我们希望通过请求头而不是 URL 来区分不同版本的 API。例如，可以通过请求的 Accept 或 X-API-Version 头来指定 API 的版本。

package main

import (
    "fmt"
    "github.com/dizzyfool/huma"
    "net/http"
)

func main() {
    // 创建新的 Huma API 实例
    api := huma.NewAPI("My API", "1.0")

    // 版本控制: 根据请求头来选择 API 版本
    api.Get("/users/profile", func(w http.ResponseWriter, r *http.Request) {
        version := r.Header.Get("X-API-Version")

        switch version {
        case "v1":
            fmt.Fprintln(w, "v1 Profile")
        case "v2":
            fmt.Fprintln(w, "v2 Profile with new fields")
        default:
            http.Error(w, "Unsupported API version", http.StatusNotAcceptable)
        }
    })

    http.ListenAndServe(":8080", api)
}

在这个例子中，我们通过检查请求头中的 X-API-Version 来选择不同的 API 版本。客户端在发送请求时，能够指定使用哪个版本的 API。

3. 版本控制的最佳实践

• 保持向后兼容性：每次发布新版本时，尽量保持老版本的支持，以避免现有用户的中断。
• 明确版本变更：当 API 改动较大时，可以增加版本号。每个版本应该清晰标注，并有明确的文档说明变化。
• 文档生成：在使用 Huma 开发 API 时，利用框架自动生成的文档可以帮助客户端开发者了解 API 的版本及变化。
• 逐步弃用旧版本：当你决定弃用某个版本时，可以通过 API 文档通知客户端，并在未来版本中完全移除。

---

4. 总结

Go Huma 提供了一些灵活的方式来进行版本控制，帮助开发者在开发过程中更好地管理 API 的版本。通过路径版本控制、子路由版本控制和请求头版本控制，开发者可以根据需求选择合适的方案来构建兼容性强、易于维护的 API 系统。