🔌Routing

---

라우팅은 애플리케이션의 엔드포인트(URIs)가 클라이언트 요청에 응답하는 방식을 말합니다.

Handlers

Signature

func(c *fiber.Ctx) error

Example

app.Get("/", func(c *fiber.Ctx) error {
    return c.SendString("Hello, World 👋!")
})

Paths

Route paths는 request method와 결합되어 요청이 이루어질 수 있는 엔드포인트를 정의합니다. Route paths는 strings 또는 string patterns일 수 있습니다.

문자열 기반 route paths 예시

// 이 route path는 루트 경로 "/"에 대한 요청과 일치합니다:
app.Get("/", func(c *fiber.Ctx) error {
      return c.SendString("root")
})

// 이 route path는 "/about"에 대한 요청과 일치합니다:
app.Get("/about", func(c *fiber.Ctx) error {
    return c.SendString("about")
})

// 이 route path는 "/random.txt"에 대한 요청과 일치합니다:
app.Get("/random.txt", func(c *fiber.Ctx) error {
    return c.SendString("random.txt")
})

expressJs 프레임워크와 같이 route 선언 순서가 중요한 역할을 합니다. 요청이 수신되면 선언된 순서대로 route가 확인됩니다.

따라서 고정된 부분을 포함하는 route 뒤에 가변 매개변수가 있는 route를 작성하는 것에 주의하세요. 그렇지 않으면 이러한 가변 부분이 대신 일치하여 예기치 않은 동작이 발생할 수 있습니다.

Parameters

Route parameters는 route에서 named 또는 not named segments인 동적 요소입니다. 이 segments는 URL에서 해당 위치에 지정된 값을 캡처하는 데 사용됩니다. 얻어진 값은 path에 지정된 route parameter의 이름을 각각의 키로 사용하여 Params 함수를 사용하거나 이름 없는 매개변수의 경우 문자(*, +)와 이를 카운터로 사용하여 검색할 수 있습니다.

:, +, *는 parameter를 도입하는 문자입니다.

Greedy parameters는 wildcard(*) 또는 plus(+) 기호로 표시됩니다.

라우팅은 또한 선택적 매개변수를 사용할 가능성을 제공합니다. 명명된 매개변수의 경우 최종 "?"로 표시되는 반면, plus 기호는 선택 사항이 아닙니다. 선택적이고 greedy한 매개변수 범위에 wildcard 문자를 사용할 수 있습니다.

route parameters를 사용하여 route 정의 예시

// Parameters
app.Get("/user/:name/books/:title", func(c *fiber.Ctx) error {
    fmt.Fprintf(c, "%s\n", c.Params("name"))
    fmt.Fprintf(c, "%s\n", c.Params("title"))
    return nil
})

// Plus - greedy - not optional 
app.Get("/user/+", func(c *fiber.Ctx) error {
    return c.SendString(c.Params("+"))
})

// 선택적 parameter
app.Get("/user/:name?", func(c *fiber.Ctx) error {
    return c.SendString(c.Params("name"))
})

// Wildcard - greedy - optional
app.Get("/user/*", func(c *fiber.Ctx) error {
    return c.SendString(c.Params("*"))
})

// 이 route path는 parameter 문자가 이스케이프되므로 "/v1/some/resource/name:customVerb"에 대한 요청과 일치합니다.
app.Get(`/v1/some/resource/name\:customVerb`, func(c *fiber.Ctx) error {
    return c.SendString("Hello, Community")
})

하이픈(-)과 점(.)은 문자 그대로 해석되므로 route parameters와 함께 유용한 목적으로 사용할 수 있습니다.

모든 특수 parameter 문자는 "\"로 이스케이프할 수도 있으며 값을 잃어버리므로 원하는 경우 route에서 사용할 수 있습니다. 예를 들어 google api design guide의 사용자 지정 메서드에서처럼 말입니다. backticks ``를 사용하는 것이 권장되는데, go의 정규 표현식 문서에서는 항상 backticks를 사용하여 모호하지 않고 이스케이프 문자가 예기치 않은 방식으로 정규 표현식 패턴을 방해하지 않도록 합니다.

// http://localhost:3000/plantae/prunus.persica
app.Get("/plantae/:genus.:species", func(c *fiber.Ctx) error {
    fmt.Fprintf(c, "%s.%s\n", c.Params("genus"), c.Params("species"))
    return nil // prunus.persica
})

// http://localhost:3000/flights/LAX-SFO
app.Get("/flights/:from-:to", func(c *fiber.Ctx) error {
    fmt.Fprintf(c, "%s-%s\n", c.Params("from"), c.Params("to"))
    return nil // LAX-SFO 
})

우리의 지능형 라우터는 이 경우 도입 parameter 문자가 요청 route의 일부여야 한다는 것을 인식하고 그에 따라 처리할 수 있습니다.

// http://localhost:3000/shop/product/color:blue/size:xs
app.Get("/shop/product/color::color/size::size", func(c *fiber.Ctx) error {
    fmt.Fprintf(c, "%s:%s\n", c.Params("color"), c.Params("size"))
    return nil // blue:xs
})

게다가 연속된 여러 parameter와 wildcard 또는 plus 문자와 같은 route의 여러 이름 없는 parameter 문자가 가능하므로 사용자를 위한 라우터의 가능성을 크게 확장합니다.

// GET /@v1
// Params: "sign" -> "@", "param" -> "v1"
app.Get("/:sign:param", handler)

// GET /api-v1 
// Params: "name" -> "v1"
app.Get("/api-:name", handler)

// GET /customer/v1/cart/proxy
// Params: "*1" -> "customer/", "*2" -> "/cart"
app.Get("/*v1*/proxy", handler)

// GET /v1/brand/4/shop/blue/xs
// Params: "*1" -> "brand/4", "*2" -> "blue/xs" 
app.Get("/v1/*/shop/*", handler)

우리는 express routing에 맞춰 강력하게 라우팅을 조정했지만, 정규 표현식은 상당히 느리기 때문에 현재 정규 표현식을 사용할 가능성은 없습니다. 0.1.7 버전(express 4)으로 온라인 Express route tester에서 가능성을 테스트할 수 있습니다.

Constraints

Route constraints는 들어오는 URL과 일치할 때 실행되며 URL path가 parameters에 의해 route 값으로 토큰화됩니다. 이 기능은 v2.37.0에서 도입되었으며 .NET Core에서 영감을 받았습니다.

Constraints는 parameters에 대한 유효성 검사가 아닙니다. parameter 값에 대해 constraints가 유효하지 않으면 Fiber는 404 handler를 반환합니다.

Constraint	Example	Example matches
int	:id<int>	123456789, -123456789
bool	:active<bool>	true,false
guid	:id<guid>	CD2C1638-1638-72D5-1638-DEADBEEF1638
float	:weight<float>	1.234, -1,001.01e8
minLen(value)	:username<minLen(4)>	Test (최소 4자 이상이어야 함)
maxLen(value)	:filename<maxLen(8)>	MyFile (8자를 넘지 않아야 함)
len(length)	:filename<len(12)>	somefile.txt (정확히 12자)
min(value)	:age<min(18)>	19 (정수 값은 최소 18 이상이어야 함)
max(value)	:age<max(120)>	91 (정수 값은 120을 넘지 않아야 함)
range(min,max)	:age<range(18,120)>	91 (정수 값은 최소 18 이상 최대 120 이하여야 함)
alpha	:name<alpha>	Rick (문자열은 하나 이상의 알파벳 문자로 구성되어야 하며, a-z이고 대소문자를 구분하지 않음)
datetime	:dob<datetime(2006\\-01\\-02)>	2005-11-01
regex(expression)	:date<regex(\d{4}-\d{2}-\d{2})>	2022-08-27 (정규 표현식과 일치해야 함)

예제

Single Constraint

app.Get("/:test<min(5)>", func(c *fiber.Ctx) error {
  return c.SendString(c.Params("test"))
})

// curl -X GET http://localhost:3000/12 
// 12

// curl -X GET http://localhost:3000/1
// Cannot GET /1

Multiple Constraints

여러 constraints에는 ;를 사용할 수 있습니다.

app.Get("/:test<min(100);maxLen(5)>", func(c *fiber.Ctx) error {
  return c.SendString(c.Params("test"))
})

// curl -X GET http://localhost:3000/120000
// Cannot GET /120000

// curl -X GET http://localhost:3000/1
// Cannot GET /1

// curl -X GET http://localhost:3000/250 
// 250

Regex Constraint

Fiber는 route를 등록할 때 regex query를 미리 컴파일합니다. 따라서 regex constraint에 대한 성능 오버헤드는 없습니다.

app.Get(`/:date<regex(\d{4}-\d{2}-\d{2})>`, func(c *fiber.Ctx) error {
  return c.SendString(c.Params("date"))
})

// curl -X GET http://localhost:3000/125
// Cannot GET /125

// curl -X GET http://localhost:3000/test
// Cannot GET /test

// curl -X GET http://localhost:3000/2022-08-27
// 2022-08-27

datetime constraint를 사용할 때는 route 관련 문자(*, +, ?, :, /, <, >, ;, (, ))를 사용하기 전에 잘못된 파싱을 방지하기 위해 \\를 사용해야 합니다.

Optional Parameter 예제

선택적 parameters에도 constraints를 부과할 수 있습니다.

app.Get("/:test<int>?", func(c *fiber.Ctx) error {
  return c.SendString(c.Params("test"))
})
// curl -X GET http://localhost:3000/42
// 42
// curl -X GET http://localhost:3000/
//
// curl -X GET http://localhost:3000/7.0
// Cannot GET /7.0

Middleware

요청이나 응답을 변경하도록 설계된 함수를 middleware 함수라고 합니다. Next는 Fiber 라우터 함수로, 호출되면 현재 route와 일치하는 다음 함수를 실행합니다.

middleware 함수 예제

app.Use(func(c *fiber.Ctx) error {
  // 모든 응답에 대해 사용자 지정 헤더 설정:
  c.Set("X-Custom-Header", "Hello, World")

  // 다음 middleware로 이동:
  return c.Next()
})

app.Get("/", func(c *fiber.Ctx) error {
  return c.SendString("Hello, World!")
})

Use 메서드 경로는 마운트 또는 접두사 경로이며 middleware가 시작하는 요청된 경로에만 적용되도록 제한합니다.

동적으로 Routes 추가에 대한 제한

애플리케이션이 시작된 후 동적으로 routes를 추가하는 것은 설계 및 성능 고려사항으로 인해 지원되지 않습니다. 애플리케이션이 시작되기 전에 모든 routes를 정의해야 합니다.

Grouping

많은 엔드포인트가 있는 경우 Group을 사용하여 routes를 구성할 수 있습니다.

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

  api := app.Group("/api", middleware) // /api

  v1 := api.Group("/v1", middleware)   // /api/v1
  v1.Get("/list", handler)             // /api/v1/list
  v1.Get("/user", handler)             // /api/v1/user

  v2 := api.Group("/v2", middleware)   // /api/v2
  v2.Get("/list", handler)             // /api/v2/list
  v2.Get("/user", handler)             // /api/v2/user

  log.Fatal(app.Listen(":3000"))
}

이에 대한 자세한 내용은 Grouping 가이드를 참조하세요.