路由参数 #

一、参数类型概述 #

1.1 参数分类 #

Fiber支持多种参数类型：

类型 来源 获取方法
路径参数 URL路径 c.Params()
查询参数 URL查询字符串 c.Query()
表单参数 请求体（表单） c.FormValue()
JSON参数 请求体（JSON） c.BodyParser()
请求头 HTTP头部 c.Get()
Cookie HTTP Cookie c.Cookies()

1.2 参数位置示意 #

text 
GET /users/123/posts?page=1&limit=10
         │           │
         │           └── 查询参数
         └── 路径参数

POST /users
Content-Type: application/json

{"name": "John", "age": 25}
└── JSON参数（请求体）

二、路径参数 #

2.1 基本用法 #

go 
// 必需参数
app.Get("/users/:id", func(c *fiber.Ctx) error {
    id := c.Params("id")
    return c.SendString("User ID: " + id)
})

// 访问 /users/123 → User ID: 123

2.2 可选参数 #

go 
// 可选参数（带?）
app.Get("/users/:id?", func(c *fiber.Ctx) error {
    id := c.Params("id", "default")
    return c.SendString("User ID: " + id)
})

// 访问 /users/123 → User ID: 123
// 访问 /users     → User ID: default

2.3 多个参数 #

go 
app.Get("/users/:userId/posts/:postId", func(c *fiber.Ctx) error {
    userId := c.Params("userId")
    postId := c.Params("postId")
    return c.JSON(fiber.Map{
        "userId": userId,
        "postId": postId,
    })
})

// 访问 /users/1/posts/100
// 返回 {"userId": "1", "postId": "100"}

2.4 整数参数 #

go 
app.Get("/page/:num", func(c *fiber.Ctx) error {
    // 获取整数参数，带默认值
    num := c.ParamsInt("num", 1)
    return c.SendString("Page: " + strconv.Itoa(num))
})

// 访问 /page/5  → Page: 5
// 访问 /page/   → Page: 1（默认值）

2.5 通配符参数 #

go 
// 匿名通配符
app.Get("/files/*", func(c *fiber.Ctx) error {
    path := c.Params("*")
    return c.SendString("File: " + path)
})

// 命名通配符
app.Get("/download/*filepath", func(c *fiber.Ctx) error {
    filepath := c.Params("filepath")
    return c.SendString("Download: " + filepath)
})

// 访问 /files/docs/readme.md
// 返回 File: docs/readme.md

2.6 正则参数 #

go 
// 只匹配数字
app.Get("/users/:id<\\d+>", func(c *fiber.Ctx) error {
    id := c.Params("id")
    return c.SendString("User ID: " + id)
})

// 只匹配字母
app.Get("/category/:name<[a-z]+>", func(c *fiber.Ctx) error {
    name := c.Params("name")
    return c.SendString("Category: " + name)
})

// 自定义正则
app.Get("/code/:code<[A-Z]{3}[0-9]{3}>", func(c *fiber.Ctx) error {
    code := c.Params("code")
    return c.SendString("Code: " + code)
})

三、查询参数 #

3.1 基本用法 #

go 
app.Get("/search", func(c *fiber.Ctx) error {
    q := c.Query("q")
    return c.SendString("Search: " + q)
})

// 访问 /search?q=golang
// 返回 Search: golang

3.2 带默认值 #

go 
app.Get("/list", func(c *fiber.Ctx) error {
    page := c.Query("page", "1")
    limit := c.Query("limit", "10")
    return c.JSON(fiber.Map{
        "page":  page,
        "limit": limit,
    })
})

// 访问 /list
// 返回 {"page": "1", "limit": "10"}

// 访问 /list?page=2&limit=20
// 返回 {"page": "2", "limit": "20"}

3.3 获取所有查询参数 #

go 
app.Get("/params", func(c *fiber.Ctx) error {
    // 获取所有查询参数
    params := c.Queries()
    return c.JSON(params)
})

// 访问 /params?a=1&b=2&c=3
// 返回 {"a": "1", "b": "2", "c": "3"}

3.4 解析到结构体 #

go 
type SearchQuery struct {
    Q     string `query:"q"`
    Page  int    `query:"page"`
    Limit int    `query:"limit"`
}

app.Get("/search", func(c *fiber.Ctx) error {
    var query SearchQuery
    if err := c.QueryParser(&query); err != nil {
        return err
    }
    return c.JSON(query)
})

// 访问 /search?q=golang&page=1&limit=10
// 返回 {"Q": "golang", "Page": 1, "Limit": 10}

四、表单参数 #

4.1 基本用法 #

go 
app.Post("/login", func(c *fiber.Ctx) error {
    username := c.FormValue("username")
    password := c.FormValue("password")
    
    return c.JSON(fiber.Map{
        "username": username,
        "password": password,
    })
})

4.2 带默认值 #

go 
app.Post("/settings", func(c *fiber.Ctx) error {
    theme := c.FormValue("theme", "light")
    lang := c.FormValue("lang", "en")
    
    return c.JSON(fiber.Map{
        "theme": theme,
        "lang":  lang,
    })
})

4.3 获取所有表单参数 #

go 
app.Post("/form", func(c *fiber.Ctx) error {
    // 获取所有表单值
    values := c.Request().PostArgs()
    
    result := make(map[string]string)
    values.VisitAll(func(key, value []byte) {
        result[string(key)] = string(value)
    })
    
    return c.JSON(result)
})

4.4 解析到结构体 #

go 
type LoginForm struct {
    Username string `form:"username"`
    Password string `form:"password"`
    Remember bool   `form:"remember"`
}

app.Post("/login", func(c *fiber.Ctx) error {
    var form LoginForm
    if err := c.BodyParser(&form); err != nil {
        return err
    }
    return c.JSON(form)
})

五、JSON参数 #

5.1 解析JSON #

go 
type User struct {
    Name  string `json:"name"`
    Email string `json:"email"`
    Age   int    `json:"age"`
}

app.Post("/users", func(c *fiber.Ctx) error {
    var user User
    if err := c.BodyParser(&user); err != nil {
        return c.Status(400).JSON(fiber.Map{
            "error": "Invalid JSON",
        })
    }
    return c.JSON(user)
})

5.2 解析到Map #

go 
app.Post("/data", func(c *fiber.Ctx) error {
    var data map[string]interface{}
    if err := c.BodyParser(&data); err != nil {
        return err
    }
    return c.JSON(data)
})

5.3 获取原始Body #

go 
app.Post("/raw", func(c *fiber.Ctx) error {
    body := c.Body()
    return c.Send(body)
})

app.Post("/raw-string", func(c *fiber.Ctx) error {
    body := c.BodyString()
    return c.SendString(body)
})

六、请求头参数 #

6.1 获取请求头 #

go 
app.Get("/headers", func(c *fiber.Ctx) error {
    // 获取单个请求头
    contentType := c.Get("Content-Type")
    auth := c.Get("Authorization")
    
    // 获取所有请求头
    headers := c.GetReqHeaders()
    
    return c.JSON(fiber.Map{
        "content-type": contentType,
        "authorization": auth,
        "all": headers,
    })
})

6.2 常用请求头快捷方法 #

go 
app.Get("/info", func(c *fiber.Ctx) error {
    return c.JSON(fiber.Map{
        "host":        c.Hostname(),
        "protocol":    c.Protocol(),
        "ip":          c.IP(),
        "ips":         c.IPs(),
        "userAgent":   c.Get("User-Agent"),
        "contentType": c.Get("Content-Type"),
        "accept":      c.Get("Accept"),
    })
})

七、Cookie参数 #

7.1 获取Cookie #

go 
app.Get("/cookie", func(c *fiber.Ctx) error {
    // 获取单个Cookie
    session := c.Cookies("session")
    token := c.Cookies("token", "default")
    
    // 获取所有Cookie
    cookies := c.GetReqHeaders()["Cookie"]
    
    return c.JSON(fiber.Map{
        "session": session,
        "token":   token,
        "cookies": cookies,
    })
})

7.2 设置Cookie #

go 
app.Get("/set-cookie", func(c *fiber.Ctx) error {
    // 设置Cookie
    c.Cookie(&fiber.Cookie{
        Name:     "session",
        Value:    "abc123",
        Expires:  time.Now().Add(24 * time.Hour),
        HTTPOnly: true,
        Secure:   true,
        SameSite: "Lax",
    })
    
    return c.SendString("Cookie set")
})

7.3 删除Cookie #

go 
app.Get("/clear-cookie", func(c *fiber.Ctx) error {
    c.ClearCookie("session")
    return c.SendString("Cookie cleared")
})

八、文件参数 #

8.1 单文件上传 #

go 
app.Post("/upload", func(c *fiber.Ctx) error {
    // 获取上传的文件
    file, err := c.FormFile("file")
    if err != nil {
        return err
    }
    
    // 保存文件
    err = c.SaveFile(file, "./uploads/"+file.Filename)
    if err != nil {
        return err
    }
    
    return c.JSON(fiber.Map{
        "filename": file.Filename,
        "size":     file.Size,
        "header":   file.Header,
    })
})

8.2 多文件上传 #

go 
app.Post("/uploads", func(c *fiber.Ctx) error {
    // 解析multipart表单
    form, err := c.MultipartForm()
    if err != nil {
        return err
    }
    
    // 获取所有文件
    files := form.File["files"]
    
    var filenames []string
    for _, file := range files {
        err := c.SaveFile(file, "./uploads/"+file.Filename)
        if err != nil {
            return err
        }
        filenames = append(filenames, file.Filename)
    }
    
    return c.JSON(fiber.Map{
        "count":     len(filenames),
        "filenames": filenames,
    })
})

九、参数验证 #

9.1 手动验证 #

go 
app.Post("/users", func(c *fiber.Ctx) error {
    var user User
    if err := c.BodyParser(&user); err != nil {
        return c.Status(400).JSON(fiber.Map{
            "error": "Invalid request body",
        })
    }
    
    // 手动验证
    if user.Name == "" {
        return c.Status(400).JSON(fiber.Map{
            "error": "Name is required",
        })
    }
    
    if user.Email == "" {
        return c.Status(400).JSON(fiber.Map{
            "error": "Email is required",
        })
    }
    
    return c.JSON(user)
})

9.2 使用验证器 #

go 
type User struct {
    Name  string `json:"name" validate:"required,min=2,max=50"`
    Email string `json:"email" validate:"required,email"`
    Age   int    `json:"age" validate:"required,min=0,max=150"`
}

app.Post("/users", func(c *fiber.Ctx) error {
    var user User
    if err := c.BodyParser(&user); err != nil {
        return c.Status(400).JSON(fiber.Map{
            "error": "Invalid request body",
        })
    }
    
    // 使用validator验证
    validate := validator.New()
    if err := validate.Struct(user); err != nil {
        return c.Status(400).JSON(fiber.Map{
            "error": err.Error(),
        })
    }
    
    return c.JSON(user)
})

十、实战示例 #

10.1 分页参数处理 #

go 
type PaginationQuery struct {
    Page     int    `query:"page" validate:"min=1"`
    Limit    int    `query:"limit" validate:"min=1,max=100"`
    Sort     string `query:"sort" validate:"oneof=asc desc"`
    OrderBy  string `query:"order_by"`
    Search   string `query:"search"`
}

func GetPagination(c *fiber.Ctx) (*PaginationQuery, error) {
    query := &PaginationQuery{
        Page:    1,
        Limit:   10,
        Sort:    "asc",
        OrderBy: "id",
    }
    
    if err := c.QueryParser(query); err != nil {
        return nil, err
    }
    
    return query, nil
}

app.Get("/users", func(c *fiber.Ctx) error {
    pagination, err := GetPagination(c)
    if err != nil {
        return c.Status(400).JSON(fiber.Map{
            "error": "Invalid pagination parameters",
        })
    }
    
    return c.JSON(fiber.Map{
        "page":  pagination.Page,
        "limit": pagination.Limit,
        "sort":  pagination.Sort,
    })
})

10.2 综合参数处理 #

go 
type PostRequest struct {
    // 路径参数
    UserID string `params:"userId"`
    
    // 查询参数
    Draft bool `query:"draft"`
    
    // 请求体
    Title   string   `json:"title"`
    Content string   `json:"content"`
    Tags    []string `json:"tags"`
}

app.Post("/users/:userId/posts", func(c *fiber.Ctx) error {
    var req PostRequest
    
    // 解析路径参数
    if err := c.ParamsParser(&req); err != nil {
        return err
    }
    
    // 解析查询参数
    if err := c.QueryParser(&req); err != nil {
        return err
    }
    
    // 解析请求体
    if err := c.BodyParser(&req); err != nil {
        return err
    }
    
    return c.JSON(req)
})

十一、总结 #

11.1 参数获取方法汇总 #

方法 用途 示例
c.Params() 路径参数 c.Params(“id”)
c.Query() 查询参数 c.Query(“page”)
c.FormValue() 表单参数 c.FormValue(“name”)
c.BodyParser() JSON/表单解析 c.BodyParser(&user)
c.Get() 请求头 c.Get(“Authorization”)
c.Cookies() Cookie c.Cookies(“session”)
c.FormFile() 上传文件 c.FormFile(“file”)

11.2 下一步 #

现在你已经掌握了路由参数，接下来让我们学习 路由分组，更好地组织你的路由！

最后更新：2026-03-28