路由

简介

Goravel 路由模块可以使用 facades.Route() 进行操作。

HTTP 驱动

Goravel 默认使用 ginopen in new window 作为 HTTP 驱动，如果想使用其他驱动，可以到 config/http.go 中进行配置，目前官方默认支持 ginopen in new window 与 fiberopen in new window 两种驱动：

驱动地址
Ginhttps://github.com/goravel/ginopen in new window
Fiberhttps://github.com/goravel/fiberopen in new window

默认路由文件

所有路由文件都在 /routes 目录中进行定义。框架默认有一个示例路由 /routes/web.go，其中 func Web() 方法被注册到 app/providers/route_service_provider.go 文件中，以实现路由的绑定。

你可以在 routes 目录下新增路由文件，以进行更细颗粒的管理，然后在 app/providers/route_service_provider.go 文件中进行注册。

启动 HTTP 服务器

在根目录下 main.go 中启动 HTTP 服务器，facades.Route().Run() 将会自动获取 route.host 的配置。

package main

import (
  "github.com/goravel/framework/facades"

  "goravel/bootstrap"
)

func main() {
  // This bootstraps the framework and gets it ready for use.
  bootstrap.Boot()

  // Start http server by facades.Route().
  go func() {
    if err := facades.Route().Run(); err != nil {
      facades.Log().Errorf("Route run error: %v", err)
    }
  }()

  select {}
}

启动 HTTPS 服务器

使用前请先完善 config/http.go 中的 http.tls 配置，facades.Route().RunTLS() 方法将会根据相关配置启动 HTTPS 服务：

// main.go
if err := facades.Route().RunTLS(); err != nil {
  facades.Log().Errorf("Route run error: %v", err)
}

你也可以使用 facades.Route().RunTLSWithCert() 方法，自定义 host 与 证书：

// main.go
if err := facades.Route().RunTLSWithCert("127.0.0.1:3000", "ca.pem", "ca.key"); err != nil {
  facades.Log().Errorf("Route run error: %v", err)
}

关闭 HTTP/HTTPS 服务器

你可以调用 Shutdown 方法优雅的关闭 HTTP/HTTPS 服务器，该方法将会等待所有请求处理完毕后再执行关闭操作。

// main.go
bootstrap.Boot()

// Create a channel to listen for OS signals
quit := make(chan os.Signal)
signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)

// Start http server by facades.Route().
go func() {
  if err := facades.Route().Run(); err != nil {
    facades.Log().Errorf("Route run error: %v", err)
  }
}()

// Listen for the OS signal
go func() {
  <-quit
  if err := facades.Route().Shutdown(); err != nil {
    facades.Log().Errorf("Route Rhutdown error: %v", err)
  }

  os.Exit(0)
}()

select {}

路由方法

方法作用
Group路由分组
Prefix路由前缀
ServeHTTP测试路由
Get基本路由
Post基本路由
Put基本路由
Delete基本路由
Patch基本路由
Options基本路由
Any基本路由
Resource资源路由
Static文件路由
StaticFile文件路由
StaticFS文件路由
Middleware中间件

基本路由

facades.Route().Get("/", func(ctx http.Context) http.Response {
  return ctx.Response().Json(http.StatusOK, http.Json{
    "Hello": "Goravel",
  })
})
facades.Route().Post("/", userController.Show)
facades.Route().Put("/", userController.Show)
facades.Route().Delete("/", userController.Show)
facades.Route().Patch("/", userController.Show)
facades.Route().Options("/", userController.Show)
facades.Route().Any("/", userController.Show)

资源路由

import "github.com/goravel/framework/contracts/http"

resourceController := NewResourceController()
facades.Route().Resource("/resource", resourceController)

type ResourceController struct{}
func NewResourceController () *ResourceController {
  return &ResourceController{}
}
// GET /resource
func (c *ResourceController) Index(ctx http.Context) {}
// GET /resource/{id}
func (c *ResourceController) Show(ctx http.Context) {}
// POST /resource
func (c *ResourceController) Store(ctx http.Context) {}
// PUT /resource/{id}
func (c *ResourceController) Update(ctx http.Context) {}
// DELETE /resource/{id}
func (c *ResourceController) Destroy(ctx http.Context) {}

路由分组

facades.Route().Group(func(router route.Router) {
  router.Get("group/{id}", func(ctx http.Context) http.Response {
    return ctx.Response().Success().String(ctx.Request().Query("id", "1"))
  })
})

路由前缀

facades.Route().Prefix("users").Get("/", userController.Show)

文件路由

import "net/http"

facades.Route().Static("static", "./public")
facades.Route().StaticFile("static-file", "./public/logo.png")
facades.Route().StaticFS("static-fs", http.Dir("./public"))

路由传参

facades.Route().Get("/input/{id}", func(ctx http.Context) http.Response {
  return ctx.Response().Success().Json(http.Json{
    "id": ctx.Request().Input("id"),
  })
})

详见请求

中间件

import "github.com/goravel/framework/http/middleware"

facades.Route().Middleware(middleware.Cors()).Get("users", userController.Show)

详见中间件

Fallback 路由

使用 Fallback 方法，你可以定义一个在没有其他路由匹配传入请求时将执行的路由。

facades.Route().Fallback(func(ctx http.Context) http.Response {
  return ctx.Response().String(404, "not found")
})

速率限制

定义速率限制器

Goravel 包含强大且可自定义的速率限制服务，你可以利用这些服务来限制给定路由或一组路由的流量。首先，你应该定义满足应用程序需求的速率限制器配置。通常，这应该在应用程序的 app/providers/route_service_provider.go 文件的 configureRateLimiting 方法中完成。

速率限制器使用 facades.RateLimiter() 的 For 方法进行定义。For 方法接受一个速率限制器名称和一个闭包，该闭包返回应该应用于分配给速率限制器的路由的限制配置。速率限制器名称可以是你希望的任何字符串：

import (
  contractshttp "github.com/goravel/framework/contracts/http"
  "github.com/goravel/framework/facades"
  "github.com/goravel/framework/http/limit"
)

func (receiver *RouteServiceProvider) configureRateLimiting() {
  facades.RateLimiter().For("global", func(ctx contractshttp.Context) contractshttp.Limit {
    return limit.PerMinute(1000)
  })
}

如果传入的请求超过指定的速率限制，Goravel 将自动返回一个带有 429 HTTP 状态码的响应。如果你想定义自己的响应，应该由速率限制返回，你可以使用 Response 方法：

facades.RateLimiter().For("global", func(ctx http.Context) http.Limit {
  return limit.PerMinute(1000).Response(func(ctx http.Context) {
    ctx.Request().AbortWithStatus(http.StatusTooManyRequests)
  })
})

由于速率限制器回调接收传入的 HTTP 请求实例，你可以根据传入的请求或经过身份验证的用户动态构建适当的速率限制：

facades.RateLimiter().For("global", func(ctx contractshttp.Context) contractshttp.Limit {
  // 假设
  if is_vip() {
    return limit.PerMinute(100)
  }

  return nil
})

分段速率限制

有时你可能希望按某个任意值对速率限制进行分段。例如，你可能希望每个 IP 地址每分钟允许用户访问给定路由 100 次。为此，你可以在构建速率限制时使用 By 方法：

facades.RateLimiter().For("global", func(ctx contractshttp.Context) contractshttp.Limit {
  if is_vip() {
    return limit.PerMinute(100).By(ctx.Request().Ip())
  }

  return nil
})

为了使用另一个示例来说明此功能，我们可以将每个经过身份验证的用户 ID 的路由访问限制为每分钟 100 次，或者对于访客来说，每个 IP 地址每分钟访问 10 次：

facades.RateLimiter().For("global", func(ctx contractshttp.Context) contractshttp.Limit {
  if userID != 0 {
    return limit.PerMinute(100).By(userID)
  }

  return limit.PerMinute(10).By(ctx.Request().Ip())
})

多个速率限制

如果需要，你可以返回给定速率限制器配置的速率限制数组。将根据路由在数组中的放置顺序评估每个速率限制：

facades.RateLimiter().ForWithLimits("login", func(ctx contractshttp.Context) []contractshttp.Limit {
  return []contractshttp.Limit{
    limit.PerMinute(500),
    limit.PerMinute(100).By(ctx.Request().Ip()),
  }
})

将速率限制器附加到路由

可以使用 Throttle middleware 将速率限制器附加到路由或路由组。路由中间件接受你希望分配给路由的速率限制器的名称：

import github.com/goravel/framework/http/middleware

facades.Route().Middleware(middleware.Throttle("global")).Get("/", func(ctx http.Context) http.Response {
  return ctx.Response().Json(200, http.Json{
    "Hello": "Goravel",
  })
})

跨域资源共享 (CORS)

Goravel 已默认启用 CORS，详细配置可以到 config/cors.go 文件中进行修改。

有关 CORS 和 CORS 标头的更多信息，请参阅 MDN 关于 CORS 的 Web 文档open in new window。