go + gin 静态资源路由与后端 api 路由冲突

在使用 go 和 gin 框架时，有时会遇到静态资源路由与后端 api 路由冲突的问题。

出错示例

下面的代码展示了如何设置一个静态资源路由和一个 api 路由：

package main

import (
    "github.com/gin-gonic/gin"
)

func main() {
    r := gin.default()

    // 静态资源
    r.static("/", "./assets")

    // api
    api := r.group("/api/v1")
    {
        api.get("user", test)
    }

    r.run(":8080")
}

在这种情况下，访问 /api/v1/user 会导致以下错误：

Git Factory

为每个编码任务配置并管理独立的 Git worktree，支持并行分支和清晰的 PR 工作流，避免合并冲突。

下载

panic: '/api/v1/:user' in new path '/api/v1/:user' conflicts with existing wildcard '/<em>filepath' in existing prefix '/</em>filepath'

解决方法

解决此冲突的一个简单方法是为静态资源路由添加一个前缀。例如：

r.static("/file", "./assets")

现在，访问 /file/image.png 将命中静态资源路由，而访问 /api/v1/user 将命中 api 路由。

其他注意事项

需要注意的是，gin 的路由遵循前缀树结构。这意味着动态路由会占据一个独占节点。因此，如果使用动态参数，例如 :id，则应确保其有独占的前缀。例如：

api.GET("users/:id", Test) // 会与 "users/article" 冲突
api.GET("users/_:id", Test) // 可以避免冲突，因为前缀不同