Как работать с параметрами маршрутов, query strings и заголовками запросов в Fiber?

Параметры маршрутов, query strings и заголовки в Fiber

Fiber предоставляет единообразный API для чтения всех частей HTTP-запроса через методы объекта *fiber.Ctx.

Параметры маршрута (path parameters)

package main

import "github.com/gofiber/fiber/v2"

func main() {
	app := fiber.New()

	// Именованный параметр :id
	app.Get("/users/:id", func(c *fiber.Ctx) error {
		id := c.Params("id") // всегда string
		return c.JSON(fiber.Map{"id": id})
	})

	// Несколько параметров
	app.Get("/posts/:year/:month/:slug", func(c *fiber.Ctx) error {
		year := c.Params("year")
		month := c.Params("month")
		slug := c.Params("slug")
		return c.JSON(fiber.Map{"year": year, "month": month, "slug": slug})
	})

	// Wildcard: захватывает остаток пути
	app.Get("/files/*", func(c *fiber.Ctx) error {
		path := c.Params("*") // всё после /files/
		return c.SendString("File: " + path)
	})

	// Опциональный параметр
	app.Get("/items/:id?", func(c *fiber.Ctx) error {
		id := c.Params("id", "default-id") // второй аргумент — значение по умолчанию
		return c.SendString(id)
	})

	app.Listen(":3000")
}

Query string параметры

// GET /search?q=golang&page=2&limit=20&active=true
app.Get("/search", func(c *fiber.Ctx) error {
	q := c.Query("q")                           // "golang"
	page := c.QueryInt("page", 1)               // 2 (с дефолтом 1)
	limit := c.QueryInt("limit", 10)            // 20
	active := c.QueryBool("active", false)      // true

	return c.JSON(fiber.Map{
		"query":  q,
		"page":   page,
		"limit":  limit,
		"active": active,
	})
})

// Парсинг query-параметров в структуру
type SearchParams struct {
	Q      string `query:"q"`
	Page   int    `query:"page"`
	Limit  int    `query:"limit"`
}

app.Get("/search2", func(c *fiber.Ctx) error {
	params := new(SearchParams)
	if err := c.QueryParser(params); err != nil {
		return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{"error": err.Error()})
	}
	return c.JSON(params)
})

Заголовки запроса

app.Get("/headers", func(c *fiber.Ctx) error {
	// Чтение конкретного заголовка (регистронезависимо)
	contentType := c.Get("Content-Type")
	auth := c.Get("Authorization")
	userAgent := c.Get("User-Agent")

	// Заголовок с дефолтным значением
	acceptLang := c.Get("Accept-Language", "en")

	// Все заголовки через fasthttp напрямую
	c.Request().Header.VisitAll(func(key, value []byte) {
		// обходим все заголовки без аллокаций
		_ = string(key) + ": " + string(value)
	})

	return c.JSON(fiber.Map{
		"content_type": contentType,
		"auth":         auth,
		"user_agent":   userAgent,
		"accept_lang":  acceptLang,
	})
})

Дополнительные методы

c.IP()           // IP клиента
c.IPs()          // X-Forwarded-For как []string
c.Hostname()     // Host без порта
c.Protocol()     // "http" или "https"
c.Path()         // путь без query string
c.OriginalURL()  // полный URL включая query
c.Method()       // "GET", "POST" и т.д.

Подводные камни

• c.Params() всегда возвращает string. Для числовых ID используйте strconv.Atoi() или c.ParamsInt("id"); ошибка парсинга возвращается вторым значением.
• c.QueryInt() не различает «не передан» и «0». Если нужно знать, был ли параметр в запросе, используйте c.Query("page") == "" для проверки.
• Query-параметры URL-декодируются автоматически. Не применяйте url.QueryUnescape() повторно — это двойное декодирование.
• Заголовки регистронезависимы по HTTP-спецификации, но fasthttp их нормализует. Используйте каноническую запись (Content-Type, а не content-type) для надёжности.
• c.IP() при работе за прокси возвращает IP прокси. Используйте c.Get("X-Real-IP") или c.IPs()[0] и включите ProxyHeader в fiber.Config.
• Wildcard-параметр * захватывает всё включая слеши. Это отличается от Express, где * не захватывает /; учитывайте при проектировании маршрутов для файловых путей.
• c.QueryParser() не валидирует данные. После парсинга обязательно проверяйте значения — Fiber не выполняет валидацию автоматически.

• Давать ответ про params, query и headers в Fiber только на уровне определения, не показывая поведение в реальном приложении.
• Игнорировать границы ответственности вокруг темы «params, query и headers в Fiber»: кто отменяет работу, кто владеет ресурсом и где формируется ответ клиенту.
• Не связывать params, query и headers в Fiber с observability, тестированием или безопасностью, когда это влияет на продакшен-поведение.

• Точно объясняет, что именно делает params, query и headers в Fiber и где это используется в Go-коде.
• Связывает params, query и headers в Fiber с корректным lifecycle запроса, отменой, конкурентностью или конфигурацией сервера там, где это уместно.
• Не изобретает API и опирается на реальные контракты официальной документации.