README
¶
mux
这是一个用于定制路由的包,适用于第三方框架实现自己的路由功能。想直接使用,需要少量的代码实例化泛型对象。
所有实现的路由都支持以下功能:
- 路由参数;
- 支持正则表达式作为路由项匹配方式;
- 拦截正则表达式的行为;
- 自定义的 OPTIONS 请求处理方式;
- 自动生成 HEAD 请求处理方式;
- 根据路由反向生成地址;
- 任意风格的路由,比如 discuz 这种不以 / 作为分隔符的;
- 分组路由,比如按域名,或是版本号等;
- CORS 跨域资源的处理;
- 支持中间件;
- 支持 OPTIONS * 请求;
- 静态文件系统;
- TRACE 请求方法的支持;
- panic 处理;
import "github.com/issue9/mux/v7"
router := mux.NewRouterOf[http.Handler]("", ...) // 采用泛型实现自定义对象
router.Get("/users/1", h).
Post("/login", h).
Get("/pages/{id:\\d+}.html", h). // 匹配 /pages/123.html 等格式,path = 123
Get("/posts/{path}.html", h). // 匹配 /posts/2020/11/11/title.html 等格式,path = 2020/11/11/title
// 统一前缀路径的路由
p := router.Prefix("/api")
p.Get("/logout", h) // 相当于 m.Get("/api/logout", h)
p.Post("/login", h) // 相当于 m.Get("/api/login", h)
// 对同一资源的不同操作
res := p.Resource("/users/{id:\\d+}")
res.Get(h) // 相当于 m.Get("/api/users/{id:\\d+}", h)
res.Post(h) // 相当于 m.Post("/api/users/{id:\\d+}", h)
res.URL(map[string]string{"id": "5"}) // 构建一条基于此路由项的路径:/users/5
http.ListenAndServe(":8080", router)
语法
路由参数采用大括号包含,内部包含名称和规则两部分:{name:rule}
,
其中的 name 表示参数的名称,rule 表示对参数的约束规则。
name 可以包含 -
前缀,表示在实际执行过程中,不捕获该名称的对应的值,
可以在一定程序上提升性能。
rule 表示对参数的约束,一般为正则或是空,为空表示匹配任意值, 拦截器一栏中有关 rule 的高级用法。以下是一些常见的示例。
/posts/{id}.html // 匹配 /posts/1.html
/posts-{id}-{page}.html // 匹配 /posts-1-10.html
/posts/{path:\\w+}.html // 匹配 /posts/2020/11/11/title.html
/tags/{tag:\\w+}/{path} // 匹配 /tags/abc/title.html
路径匹配规则
可能会出现多条记录与同一请求都匹配的情况,这种情况下, 系统会找到一条认为最匹配的路由来处理,判断规则如下:
- 普通路由优先于正则路由;
- 拦截器优先于正则路由;
- 正则路由优先于命名路由;
比如:
/posts/{id}.html // 1
/posts/{id:\\d+}.html // 2
/posts/1.html // 3
/posts/1.html // 匹配 3
/posts/11.html // 匹配 2
/posts/index.html // 匹配 1
路径的匹配是以从左到右的顺序进行的,父节点不会因为没有子节点匹配而扩大自己的匹配范围,
比如 /posts/{id}-{page:digit}.html
可以匹配 /posts/1-1.html
,但无法匹配
/posts/1-1-1.html
,虽然理论上 1-1-
也能匹配 {id}
,但是 1-
已经优先匹配了,
在子元素找不到的情况下,并不会将父元素的匹配范围扩大到 1-1-
。
路由参数
通过正则表达式匹配的路由,其中带命名的参数可通过 GetParams()
获取:
import "github.com/issue9/mux/v7"
params := mux.GetParams(r)
id, err := params.Int("id")
// 或是
id := params.MustInt("id", 0) // 在无法获取 id 参数时采用 0 作为默认值返回
高级用法
分组路由
可以通过匹配 Matcher
接口,定义了一组特定要求的路由项。
// server.go
import "github.com/issue9/mux/v7"
import "github.com/issue9/mux/v7/muxutil"
m := mux.NewRouters(...)
def := mux.NewRouter("default")
m.AddRouter(muxutil.NewPathVersion("version-key", "v1"), def)
def.Get("/path", h1)
host := mux.NewRouter("host")
m.AddRouter(muxutil.NewHosts("*.example.com"), host)
host.Get("/path", h2)
http.ListenAndServe(":8080", m)
// client.go
// 访问 h2 的内容
r := http.NewRequest(http.MethodGet, "https://abc.example.com/path", nil)
r.Do()
// 访问 h1 的内容
r := http.NewRequest(http.MethodGet, "https://other_domain.com/v1/path", nil)
r.Do()
拦截器
正常情况下,/posts/{id:\d+}
或是 /posts/{id:[0-9]+}
会被当作正则表达式处理,
但是正则表达式的性能并不是很好,这个时候我们可以通过在 NewRouter
传递 Interceptor
进行拦截:
import "github.com/issue9/mux/v7"
func digit(path string) bool {
for _, c := range path {
if c < '0' || c > '9' {
return false
}
}
return len(path) > 0
}
// 路由中的 \d+ 和 [0-9]+ 均采用 digit 函数进行处理,不再是正则表达式。
opt := mux.Options{Interceptors: map[string]mux.InterceptorFunc{"\\d+": digit, "[0-9]+": digit}
r := mux.NewRouter("", opt)
这样在所有路由项中的 [0-9]+
和 \\d+
将由 digit
函数处理,
不再会被编译为正则表达式,在性能上会有很大的提升。
通过该功能,也可以自定义一些非正常的正则表达这式,然后进行拦截,比如:
/posts/{id:digit}/.html
如果不拦截,最终传递给正则表达式,可能会出现编译错误,通过拦截器可以将 digit 合法化。 目前提供了以下几个拦截器:
- InterceptorDigit 限定为数字字符,相当于正则的
[0-9]
; - InterceptorWord 相当于正则的
[a-zA-Z0-9]
; - InterceptorAny 表示匹配任意非空内容;
用户也可以自行实现 InterceptorFunc
作为拦截器。具体可参考 OptionsOf.Interceptors。
CORS
CORS 不再是以中间件的形式提供,而是通过 NewRouter 直接传递有关 CORS 的配置信息, 这样可以更好地处理每个地址支持的请求方法。
OPTIONS 请求方法由系统自动生成。
import "github.com/issue9/mux/v7"
r := mux.NewRouter("name" ,&mux.Options{CORS: AllowedCORS}) // 任意跨域请求
r.Get("/posts/{id}", nil) // 默认情况下, OPTIONS 的报头为 GET, OPTIONS
http.ListenAndServe(":8080", m)
// client.go
// 访问 h2 的内容
r := http.NewRequest(http.MethodGet, "https://localhost:8080/posts/1", nil)
r.Header.Set("Origin", "https://example.com")
r.Do() // 跨域,可以正常访问
r = http.NewRequest(http.MethodOptions, "https://localhost:8080/posts/1", nil)
r.Header.Set("Origin", "https://example.com")
r.Header.Set("Access-Control-Request-Method", "GET")
r.Do() // 预检请求,可以正常访问
静态文件
可以使用 ServeFile
与命名参数相结合的方式实现静态文件的访问:
r := NewRouter("")
r.Get("/assets/{path}", func(w http.ResponseWriter, r *http.Request){
err := muxutil.ServeFile(os.DirFS("/static/"), "path", "index.html", w, r)
if err!= nil {
http.Error(err.Error(), http.StatusInternalServerError)
}
})
自定义路由
官方提供的 http.Handler 未必是符合每个人的要求,通过 RouterOf 用户可以很方便地实现自定义格式的 http.Handler, 只需要以下几个步骤:
- 定义一个专有的路由处理类型,可以是类也可以是函数;
- 根据此类型,生成对应的 RouterOf、PrefixOf、ResourceOf、MiddlewareFuncOf 等类型;
- 定义 CallOf 函数;
- 将 CallOf 传递给 NewOf;
type Context struct {
*http.Request
W http.ResponseWriter
P Params
}
type HandlerFunc func(ctx *Context)
type Router = RouterOf[HandlerFunc]
type Prefix = PrefixOf[HandlerFunc]
type Resource = ResourceOf[HandlerFunc]
type MiddlewareFunc = MiddlewareFuncOf[HandlerFunc]
type Middleware = MiddlewareOf[HandlerFunc]
func New(name string)* Router {
call := func(w http.ResponseWriter, r *http.Request, ps Params, h HandlerFunc) {
ctx := &Context {
R: r,
W: w,
P: ps,
}
h(ctx)
}
opt := func(n types.Node) Handler {
return HandlerFunc(func(ctx* Context){
ctx.W.Header().Set("Allow", n.AllowHeader())
})
}
m := func(n types.Node) Handler {
return HandlerFunc(func(ctx* Context){
ctx.W.Header().Set("Allow", n.AllowHeader())
ctx.W.WriteHeader(405)
})
}
notFound func(ctx* Context) {
ctx.W.WriteHeader(404)
}
return NewRouterOf[HandlerFunc](name, f, notFound, m, opt)
}
以上就是自定义路由的全部功能,之后就可以直接使用:
r := New("router", nil)
r.Get("/path", func(ctx *Context){
// TODO
ctx.W.WriteHeader(200)
})
r.Prefix("/admin").Get("/login", func(ctx *Context){
// TODO
ctx.W.WriteHeader(501)
})
更多自定义路由的介绍可参考 https://caixw.io/posts/2022/build-go-router-with-generics.html 或是 examples 下的示例。
性能
https://caixw.github.io/go-http-routers-testing/ 提供了与其它几个框架的对比情况。
版权
Documentation
¶
Overview ¶
Package mux 适用第三方框架实现可定制的路由
语法 ¶
路由参数采用大括号包含,内部包含名称和规则两部分:`{name:rule}`, 其中的 name 表示参数的名称,rule 表示对参数的约束规则。
name 可以包含 `-` 前缀,表示在实际执行过程中,不捕获该名称的对应的值, 可以在一定程序上提升性能。
rule 表示对参数的约束,一般为正则或是空,为空表示匹配任意值, 拦截器一栏中有关 rule 的高级用法。以下是一些常见的示例。
/posts/{id}.html // 匹配 /posts/1.html /posts-{id}-{page}.html // 匹配 /posts-1-10.html /posts/{path:\\w+}.html // 匹配 /posts/2020/11/11/title.html /tags/{tag:\\w+}/{path} // 匹配 /tags/abc/title.html
Index ¶
- func CheckSyntax(pattern string) error
- func Debug(p string, w http.ResponseWriter, r *http.Request) error
- func Methods() []string
- func ServeFile(fsys fs.FS, p, index string, w http.ResponseWriter, r *http.Request)
- func Trace(w http.ResponseWriter, r *http.Request, body bool) error
- func URL(pattern string, params map[string]string) (string, error)
- type CallOf
- type InterceptorFunc
- type Option
- func AllowedCORS(maxAge int) Option
- func AnyInterceptor(rule string) Option
- func CORS(origin []string, allowHeaders []string, exposedHeaders []string, maxAge int, ...) Option
- func DenyCORS() Option
- func DigitInterceptor(rule string) Option
- func Interceptor(f InterceptorFunc, rule ...string) Option
- func Lock(l bool) Option
- func LogRecovery(status int, l *log.Logger) Option
- func Recovery(f RecoverFunc) Option
- func StatusRecovery(status int) Option
- func URLDomain(prefix string) Option
- func WordInterceptor(rule string) Option
- func WriteRecovery(status int, out io.Writer) Option
- func WriterRecovery(status int, out io.Writer) Optiondeprecated
- type PrefixOf
- func (p *PrefixOf[T]) Any(pattern string, h T) *PrefixOf[T]
- func (p *PrefixOf[T]) Clean()
- func (p *PrefixOf[T]) Delete(pattern string, h T) *PrefixOf[T]
- func (p *PrefixOf[T]) Get(pattern string, h T) *PrefixOf[T]
- func (p *PrefixOf[T]) Handle(pattern string, h T, methods ...string) *PrefixOf[T]
- func (p *PrefixOf[T]) Patch(pattern string, h T) *PrefixOf[T]
- func (p *PrefixOf[T]) Post(pattern string, h T) *PrefixOf[T]
- func (p *PrefixOf[T]) Prefix(prefix string, m ...types.MiddlewareOf[T]) *PrefixOf[T]
- func (p *PrefixOf[T]) Put(pattern string, h T) *PrefixOf[T]
- func (p *PrefixOf[T]) Remove(pattern string, methods ...string)
- func (p *PrefixOf[T]) Resource(pattern string, m ...types.MiddlewareOf[T]) *ResourceOf[T]
- func (p *PrefixOf[T]) Router() *RouterOf[T]
- func (p *PrefixOf[T]) URL(strict bool, pattern string, params map[string]string) (string, error)
- type RecoverFunc
- type ResourceOf
- func (r *ResourceOf[T]) Any(h T) *ResourceOf[T]
- func (r *ResourceOf[T]) Clean()
- func (r *ResourceOf[T]) Delete(h T) *ResourceOf[T]
- func (r *ResourceOf[T]) Get(h T) *ResourceOf[T]
- func (r *ResourceOf[T]) Handle(h T, methods ...string) *ResourceOf[T]
- func (r *ResourceOf[T]) Patch(h T) *ResourceOf[T]
- func (r *ResourceOf[T]) Post(h T) *ResourceOf[T]
- func (r *ResourceOf[T]) Put(h T) *ResourceOf[T]
- func (r *ResourceOf[T]) Remove(methods ...string)
- func (r *ResourceOf[T]) Router() *RouterOf[T]
- func (r *ResourceOf[T]) URL(strict bool, params map[string]string) (string, error)
- type RouterOf
- func (r *RouterOf[T]) Any(pattern string, h T) *RouterOf[T]
- func (r *RouterOf[T]) Clean()
- func (r *RouterOf[T]) Delete(pattern string, h T) *RouterOf[T]
- func (r *RouterOf[T]) Get(pattern string, h T) *RouterOf[T]
- func (r *RouterOf[T]) Handle(pattern string, h T, methods ...string) *RouterOf[T]
- func (r *RouterOf[T]) Name() string
- func (r *RouterOf[T]) Patch(pattern string, h T) *RouterOf[T]
- func (r *RouterOf[T]) Post(pattern string, h T) *RouterOf[T]
- func (r *RouterOf[T]) Prefix(prefix string, m ...types.MiddlewareOf[T]) *PrefixOf[T]
- func (r *RouterOf[T]) Put(pattern string, h T) *RouterOf[T]
- func (r *RouterOf[T]) Remove(pattern string, methods ...string)
- func (r *RouterOf[T]) Resource(pattern string, m ...types.MiddlewareOf[T]) *ResourceOf[T]
- func (r *RouterOf[T]) Routes() map[string][]string
- func (r *RouterOf[T]) ServeContext(w http.ResponseWriter, req *http.Request, ctx *types.Context)
- func (r *RouterOf[T]) ServeHTTP(w http.ResponseWriter, req *http.Request)
- func (r *RouterOf[T]) URL(strict bool, pattern string, params map[string]string) (string, error)
- func (r *RouterOf[T]) Use(m ...types.MiddlewareOf[T])
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Debug ¶
Debug 输出调试信息
p 是指路由中的参数名,比如以下示例中,p 的值为 debug:
r.Get("/test{debug}", func(w http.ResponseWriter, r *http.Request) { p := mux.GetParams(r).String("debug") Debug(p, w, r) }
p 所代表的路径包含了前缀的 /。
func ServeFile ¶
ServeFile 提供对静态文件的服务
p 表示需要读取的文件名; index 表示 p 为目录时,默认读取的文件,为空表示 index.html;
如果不需要自定义 index 的功能,则可以直接使用 http.ServeFile 或是 http.ServeFileFS。
Types ¶
type InterceptorFunc ¶
type InterceptorFunc = syntax.InterceptorFunc
type Option ¶
func CORS ¶
func CORS(origin []string, allowHeaders []string, exposedHeaders []string, maxAge int, allowCredentials bool) Option
CORS 自定义跨域请求设置项
origin 对应 Origin 报头。如果包含了 *,那么其它的设置将不再启作用。 如果此值为空,表示不启用跨域的相关设置;
allowHeaders 对应 Access-Control-Allow-Headers 可以包含 *,表示可以是任意值,其它值将不再启作用;
exposedHeaders 对应 Access-Control-Expose-Headers;
maxAge 对应 Access-Control-Max-Age 有以下几种取值:
- 0 不输出该报头;
- -1 表示禁用;
- 其它 >= -1 的值正常输出数值;
allowCredentials 对应 Access-Control-Allow-Credentials;
func Interceptor ¶
func Interceptor(f InterceptorFunc, rule ...string) Option
Interceptor 针对带参数类型路由的拦截处理
在解析诸如 /authors/{id:\\d+} 带参数的路由项时, 用户可以通过拦截并自定义对参数部分 {id:\\d+} 的解析, 从而不需要走正则表达式的那一套解析流程,可以在一定程度上增强性能。
一旦正则表达式被拦截,则节点类型也将不再是正则表达式, 其处理优先级会比正则表达式类型高。 在某些情况下,可能会造成处理结果不相同。比如:
/authors/{id:\\d+} // 1 /authors/{id:[0-9]+} // 2
以上两条记录是相同的,但因为表达式不同,也能正常添加, 处理流程,会按添加顺序优先比对第一条,所以第二条是永远无法匹配的。 但是如果你此时添加了 (InterceptorDigit, "[0-9]+"), 使第二个记录的优先级提升,会使第一条永远无法匹配到数据。
可多次调用,表示同时指定了多个。
func WriteRecovery ¶ added in v7.2.0
WriteRecovery 向 io.Writer 输出错误信息
status 表示向客户端输出的状态码; out 表示输出通道,比如 os.Stderr 等;
func WriterRecovery
deprecated
Deprecated: 使用 WriteRecovery 代替
type PrefixOf ¶
type PrefixOf[T any] struct { // contains filtered or unexported fields }
PrefixOf 操纵统一前缀的路由
func (*PrefixOf[T]) Clean ¶
func (p *PrefixOf[T]) Clean()
Clean 清除所有以 PrefixOf.prefix 开头的路由项
当指定多个相同的 PrefixOf 时,调用其中的一个 PrefixOf.Clean 也将会清除其它的:
r := NewRouterOf(...) p1 := r.Prefix("prefix") p2 := r.Prefix("prefix") p2.Clean() 将同时清除 p1 的内容,因为有相同的前缀。
func (*PrefixOf[T]) Prefix ¶
func (p *PrefixOf[T]) Prefix(prefix string, m ...types.MiddlewareOf[T]) *PrefixOf[T]
Prefix 在现有 PrefixOf 的基础上声明一个新的 PrefixOf 实例
m 中间件函数,按顺序调用,会继承 p 的中间件并按在 m 之前;
func (*PrefixOf[T]) Resource ¶
func (p *PrefixOf[T]) Resource(pattern string, m ...types.MiddlewareOf[T]) *ResourceOf[T]
Resource 创建一个资源路由项
pattern 资源地址; m 中间件函数,按顺序调用,会继承 p 的中间件并按在 m 之前;
type RecoverFunc ¶
type RecoverFunc = options.RecoverFunc
type ResourceOf ¶
type ResourceOf[T any] struct { // contains filtered or unexported fields }
ResourceOf 以资源地址为对象的路由
func (*ResourceOf[T]) Handle ¶
func (r *ResourceOf[T]) Handle(h T, methods ...string) *ResourceOf[T]
func (*ResourceOf[T]) Remove ¶
func (r *ResourceOf[T]) Remove(methods ...string)
Remove 删除指定匹配模式的路由项
func (*ResourceOf[T]) Router ¶
func (r *ResourceOf[T]) Router() *RouterOf[T]
Router 返回与当前资源关联的 RouterOf 实例
func (*ResourceOf[T]) URL ¶
URL 根据参数构建一条 URL
params 匹配路由参数中的同名参数,或是不存在路由参数,比如普通的字符串路由项, 该参数不启作用;
res, := m.Resource("/posts/{id}") res.URL(map[string]string{"id": "1"}, "") // /posts/1 res, := m.Resource("/posts/{id}/{path}") res.URL(map[string]string{"id": "1","path":"author/profile"}) // /posts/1/author/profile
type RouterOf ¶
type RouterOf[T any] struct { // contains filtered or unexported fields }
RouterOf 可自定义处理函数类型的路由
router := NewRouterOf[http.Handler](...) router.Get("/abc/h1", h1). Post("/abc/h2", h2). Handle("/api/{version:\\d+}",h3, http.MethodGet, http.MethodPost) // 只匹配 GET 和 POST http.ListenAndServe(router)
func NewRouterOf ¶
func NewRouterOf[T any](name string, call CallOf[T], notFound T, methodNotAllowedBuilder, optionsBuilder types.BuildNodeHandleOf[T], o ...Option) *RouterOf[T]
NewRouterOf 声明路由
name 路由名称,可以为空; T 表示用户用于处理路由项的方法。
func (*RouterOf[T]) Get ¶
Get 相当于 RouterOf.Handle(pattern, h, http.MethodGet) 的简易写法
h 不应该主动调用 WriteHeader,否则会导致 HEAD 请求获取不到 Content-Length 报头。
func (*RouterOf[T]) Handle ¶
Handle 添加一条路由数据
pattern 为路由匹配模式,可以是正则匹配也可以是字符串匹配, 若语法不正确,则直接 panic,可以通过 CheckSyntax 检测语法的有效性,其它接口也相同。 methods 该路由项对应的请求方法,如果未指定值,则表示所有支持的请求方法,其中 OPTIONS 和 HEAD 不受控。
func (*RouterOf[T]) Prefix ¶
func (r *RouterOf[T]) Prefix(prefix string, m ...types.MiddlewareOf[T]) *PrefixOf[T]
Prefix 声明一个 PrefixOf 实例
prefix 路由前缀字符串,可以为空; m 中间件函数,按顺序调用,会继承 r 的中间件并按在 m 之前;
func (*RouterOf[T]) Remove ¶
Remove 移除指定的路由项
当未指定 methods 时,将删除所有 method 匹配的项。 指定错误的 methods 值,将自动忽略该值。
func (*RouterOf[T]) Resource ¶
func (r *RouterOf[T]) Resource(pattern string, m ...types.MiddlewareOf[T]) *ResourceOf[T]
Resource 创建一个资源路由项
pattern 资源地址; m 中间件函数,按顺序调用,会继承 r 的中间件并按在 m 之前;
func (*RouterOf[T]) ServeContext ¶
func (*RouterOf[T]) ServeHTTP ¶
func (r *RouterOf[T]) ServeHTTP(w http.ResponseWriter, req *http.Request)