Golang中API版本控制方法探讨

jarrodhroberson:

这是对公共API进行版本控制的正确方式 使用Accept头部进行版本控制

这个头部可以用来管理子域名吗？

Accept: application/api2.example+json

我认为这里没有“一刀切”的解决方案。只要您确定始终希望同步发布所有API的新版本，那么您使用 v1.mydomain.com 和 v2.mydomain.com 的策略就没有任何问题。我不太了解您的具体用例，但我能预见到可能只想发布某个API的新主版本，而将其他API留在旧版本的情况。只要不是这种情况，我认为您的方法似乎是合理的。

像Jarrod建议的那样使用请求头也是个好方法，但我有时更喜欢在URI中就能轻松看到正在使用的API版本，而不必去检查请求头。在我看来，这能让版本分离更加明显。

Sibert:

我理解得对吗？

不完全正确。多面向意味着您的1台源服务器同时为 v1.domain.com 和 v2.domain.com 提供服务。我这里提到的防火墙不仅仅是常规的端口限制。有些（硬件或软件）防火墙可以过滤自定义规则。

根据您加强安全性的方式，有些服务器在负载均衡器端（例如 Nginx 或 Apache）或实际的防火墙规则中实施了严格的接口限制。这样做的目的是通过让防火墙仅将 v1.domain.com、v2.domain.com 等列入白名单，来防止意外暴露（例如由初级开发人员或一些粗心的外包承包商导致的 testing.domain.com）。

在您的情况下，现在还为时过早，所以暂时只需记住这个步骤。

编辑：

1. 一个著名的例子是 Cloudflare 的防火墙规则，如果您使用他们的 CDN+DNS 作为面向外部的服务，它允许自定义模式。

Sibert:

我理解这是同一个API具有不同的路由，对吗？

必须查看其文档。否则，我假设是1个API（/endpoint/），2种不同的路由（/api/v2 和 /api/v1），1个版本差异（v2）。

Sibert:

子域名方法在未来会引起任何麻烦吗？

应该不是问题，因为所有4个URI都是唯一的，并且您可以自由地推出以下更新：

1. API路径改进（不向后兼容和向后兼容的更改）
2. 输入数据模式更改
3. 新的API可以拥有自己的缓存，而不会干扰现有API的缓存
4. 输出数据模式更改
5. 可以推出互不干扰的弃用和移除。

我能看到的是，使用子域名方法假设您可以轻松访问DNS管理以推出API版本更新。对于小型项目或者您就是DNS管理员，这不会是个问题。否则，您需要经过网络部门的一些繁琐流程。

/vX/ 路径方法允许您在相同的网络和DNS设置下工作，因此每次推出API更新时，可以少联系一个部门。

另一个问题是，假设您从一个源服务器提供服务，您需要将服务器配置为多面向以服务多个子域名。但是，如果每个版本都有自己的源服务器集群，那么使用子域名来分离 v1 和 v2 服务器是有意义的。

API版本控制有很多方法。最重要的部分是文档 + 弃用通知、内置弃用警告、与客户的沟通以及宽限期。

在Go中实现API版本控制，子域名方案是可行的生产级方案，但需要权衡架构复杂度。

子域名版本控制的实现示例

// main.go - 主路由分发
package main

import (
    "net/http"
    "strings"
)

func versionRouter(w http.ResponseWriter, r *http.Request) {
    host := strings.Split(r.Host, ":")[0]
    
    switch {
    case strings.HasPrefix(host, "v1.api."):
        v1Handler(w, r)
    case strings.HasPrefix(host, "v2.api."):
        v2Handler(w, r)
    default:
        http.NotFound(w, r)
    }
}

func v1Handler(w http.ResponseWriter, r *http.Request) {
    w.Write([]byte(`{"api": "v1", "endpoint": "` + r.URL.Path + `"}`))
}

func v2Handler(w http.ResponseWriter, r *http.Request) {
    w.Write([]byte(`{"api": "v2", "endpoint": "` + r.URL.Path + `"}`))
}

func main() {
    http.HandleFunc("/", versionRouter)
    http.ListenAndServe(":8080", nil)
}

多可执行文件方案

// cmd/api-v1/main.go
package main

import (
    "net/http"
)

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("/users", func(w http.ResponseWriter, r *http.Request) {
        w.Write([]byte(`{"version": "v1", "data": "users"}`))
    })
    http.ListenAndServe(":8081", mux)
}

// cmd/api-v2/main.go  
package main

import (
    "net/http"
)

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("/users", func(w http.ResponseWriter, r *http.Request) {
        w.Write([]byte(`{"version": "v2", "data": {"users": []}}`))
    })
    http.ListenAndServe(":8082", mux)
}

使用反向代理配置（Nginx示例）

server {
    listen 80;
    server_name v1.api.example.com;
    location / {
        proxy_pass http://localhost:8081;
    }
}

server {
    listen 80;
    server_name v2.api.example.com;
    location / {
        proxy_pass http://localhost:8082;
    }
}

潜在问题分析

1. 证书管理复杂度：每个子域名需要SSL证书，通配符证书可缓解
2. DNS配置：需要为每个版本配置DNS记录
3. 客户端缓存：不同子域名导致客户端缓存隔离
4. CORS配置：需要为每个子域名单独配置CORS
5. 监控分散：日志和监控需要聚合多个服务

// 中间件示例：跨版本共享功能
type SharedMiddleware struct {
    next http.Handler
}

func (m *SharedMiddleware) ServeHTTP(w http.ResponseWriter, r *http.Request) {
    // 共享的认证、日志等逻辑
    w.Header().Set("X-API-Version", getVersionFromHost(r.Host))
    m.next.ServeHTTP(w, r)
}

func getVersionFromHost(host string) string {
    parts := strings.Split(host, ".")
    if len(parts) > 0 && strings.HasPrefix(parts[0], "v") {
        return parts[0]
    }
    return "unknown"
}

子域名方案适合大型微服务架构，但会增加运维复杂度。路径方案（/api/v1/）在大多数场景下更简单直接。