The highest tagged major version is
README
¶
mux 
mux 是一个实现了 http.Handler 的中间件，为用户提供了以下功能：
- 正则路由；
- 路由参数；
- 丰富的 OPTIONS 请求处理方式；
- 根据路由生成地址。
mux 本身就是一个实现了 http.Handler 接口的中间件，
所有实现官方接口 http.Handler 的都可以附加到 mux 上作为中间件使用。
middleware 提供了诸如按域名过滤等常用的中间件功能。
m := mux.New(false, false, nil, nil).
Get("/users/1", h). // GET /user/1
Post("/login", h). // POST /api/login
Get("/posts/{id:\\d+}", h). // GET /blog/post/{id:\\d+} 正则路由
Options("/users/1", "GET") // OPTIONS /user/1 手动指定该路由项的 OPTIONS 请求方法返回内容
// 统一前缀路径的路由
p := m.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", m)
安装
go get github.com/issue9/mux
文档
版权
Documentation
¶
Overview ¶
Package mux 是一个提供了路由匹配功能的中间件。
m := mux.New(false, false, nil, nil).
Get("/users/1", h).
Post("/login", h).
Get("/posts/{id:\\d+}", h). // 正则路由
Options("/users/1", "GET") // 手动指定 OPTIONS 请求的返回内容。
// 统一前缀路径的路由
p := m.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}", h)
res.Post(h) // 相当于 m.Post("/api/users/{id}", h)
res.URL(map[string]string{"id": "5"}) // 生成 /users/5
http.ListenAndServe(":8080", m)
正则表达式
路由中支持以正则表达式的方式进行匹配，表达式以大括号包含，内部以冒号分隔， 前半部分为变量的名称，后半部分为变量可匹配类型的正则表达式。比如：
/posts/{id:\\d+} // 将被转换成 /posts/(?P<id>\\d+)
/posts/{:\\d+} // 将被转换成 /posts/\\d+
命名参数
若路由字符串中，所有的正则表达式都只有名称部分（没有冒号及之后的内容）， 则会被转换成命名参数，因为不需要作正则验证，性能会比较正则稍微好上一些。 命名参数匹配所有字符。
/posts/{id}.html // 匹配 /posts/1.html
/posts-{id}-{page}.html // 匹配 /posts-1-10.html
通配符
在路由字符串中若是以命名参数结尾的，则表示可以匹配之后的任意字符。
/blog/assets/{path}
/blog/{tags:\\w+}/{path}
/blog/assets{path}
路径匹配规则
可能会出现多条记录与同一请求都匹配的情况，这种情况下， 系统会找到一条认为最匹配的路由来处理，判断规则如下：
- 普通路由优先于正则路由；
- 正则路由优先于命名路由；
比如：
/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
路由参数
通过正则表达式匹配的路由，其中带命名的参数可通过 GetParams() 获取：
params := GetParams(r)
id, err := params.Int("id")
// 或是
id := params.MustInt("id", 0) // 0 表示在无法获取 id 参数的默认值
OPTIONS ¶
默认情况下，用户无须显示地实现它，系统会自动实现。 当然用户也可以使用 *.Options() 函数指定特定的数据； 或是直接使用 *.Handle() 指定一个自定义的实现方式。
如果不需要的话，也可以在 New() 中将 disableOptions 设置为 true。 显示设定 OPTIONS，不受 disableOptions 的影响。
m := mux.New(...)
m.Get("/posts/{id}", nil) // 默认情况下， OPTIONS 的报头为 GET, OPTIONS
m.Options("/posts/{id}", "*") // 强制改成 *
m.Delete("/posts/{id}", nil) // OPTIONS 依然为 *
m.Remove("/posts/{id}", http.MethodOptions) // 在当前路由上禁用 OPTIONS
m.Handle("/posts/{id}", h, http.MethodOptions) // 显示指定一个处理函数 h
适用范围
由于路由项采用了切片(slice) 的形式保存路由项， 如果在运行过程中需要大量的增删路由操作，性能上会比较差， 建议使用其它的库的代替。其它情况下，性能还是不错的， 具体的可运行 `go test -bench=.` 查看。
Index ¶
- Variables
- func Params(r *http.Request) params.Params
- type Mux
- func (mux *Mux) AddMiddlewares(m ...middleware.Middleware) *Muxdeprecated
- func (mux *Mux) Any(pattern string, h http.Handler) *Mux
- func (mux *Mux) AnyFunc(pattern string, fun http.HandlerFunc) *Mux
- func (mux *Mux) AppendMiddlewares(m ...middleware.Middleware) *Mux
- func (mux *Mux) Clean() *Mux
- func (mux *Mux) Delete(pattern string, h http.Handler) *Mux
- func (mux *Mux) DeleteFunc(pattern string, fun http.HandlerFunc) *Mux
- func (mux *Mux) Get(pattern string, h http.Handler) *Mux
- func (mux *Mux) GetFunc(pattern string, fun http.HandlerFunc) *Mux
- func (mux *Mux) Handle(pattern string, h http.Handler, methods ...string) error
- func (mux *Mux) HandleFunc(pattern string, fun http.HandlerFunc, methods ...string) error
- func (mux *Mux) Name(name, pattern string) error
- func (mux *Mux) Options(pattern string, allow string) *Mux
- func (mux *Mux) Patch(pattern string, h http.Handler) *Mux
- func (mux *Mux) PatchFunc(pattern string, fun http.HandlerFunc) *Mux
- func (mux *Mux) Post(pattern string, h http.Handler) *Mux
- func (mux *Mux) PostFunc(pattern string, fun http.HandlerFunc) *Mux
- func (mux *Mux) Prefix(prefix string) *Prefix
- func (mux *Mux) Put(pattern string, h http.Handler) *Mux
- func (mux *Mux) PutFunc(pattern string, fun http.HandlerFunc) *Mux
- func (mux *Mux) Remove(pattern string, methods ...string) *Mux
- func (mux *Mux) ResetMiddlewares() *Mux
- func (mux *Mux) Resource(pattern string) *Resource
- func (mux *Mux) ServeHTTP(w http.ResponseWriter, r *http.Request)
- func (mux *Mux) URL(name string, params map[string]string) (string, error)
- func (mux *Mux) UnshiftMiddlewares(m ...middleware.Middleware) *Mux
- type Prefix
- func (p *Prefix) Any(pattern string, h http.Handler) *Prefix
- func (p *Prefix) AnyFunc(pattern string, fun http.HandlerFunc) *Prefix
- func (p *Prefix) Clean() *Prefix
- func (p *Prefix) Delete(pattern string, h http.Handler) *Prefix
- func (p *Prefix) DeleteFunc(pattern string, fun http.HandlerFunc) *Prefix
- func (p *Prefix) Get(pattern string, h http.Handler) *Prefix
- func (p *Prefix) GetFunc(pattern string, fun http.HandlerFunc) *Prefix
- func (p *Prefix) Handle(pattern string, h http.Handler, methods ...string) error
- func (p *Prefix) HandleFunc(pattern string, fun http.HandlerFunc, methods ...string) error
- func (p *Prefix) Mux() *Mux
- func (p *Prefix) Name(name, pattern string) error
- func (p *Prefix) Options(pattern string, allow string) *Prefix
- func (p *Prefix) Patch(pattern string, h http.Handler) *Prefix
- func (p *Prefix) PatchFunc(pattern string, fun http.HandlerFunc) *Prefix
- func (p *Prefix) Post(pattern string, h http.Handler) *Prefix
- func (p *Prefix) PostFunc(pattern string, fun http.HandlerFunc) *Prefix
- func (p *Prefix) Prefix(prefix string) *Prefix
- func (p *Prefix) Put(pattern string, h http.Handler) *Prefix
- func (p *Prefix) PutFunc(pattern string, fun http.HandlerFunc) *Prefix
- func (p *Prefix) Remove(pattern string, methods ...string) *Prefix
- func (p *Prefix) Resource(pattern string) *Resource
- func (p *Prefix) URL(name string, params map[string]string) (string, error)
- type Resource
- func (r *Resource) Any(h http.Handler) *Resource
- func (r *Resource) AnyFunc(fun http.HandlerFunc) *Resource
- func (r *Resource) Clean() *Resource
- func (r *Resource) Delete(h http.Handler) *Resource
- func (r *Resource) DeleteFunc(fun http.HandlerFunc) *Resource
- func (r *Resource) Get(h http.Handler) *Resource
- func (r *Resource) GetFunc(fun http.HandlerFunc) *Resource
- func (r *Resource) Handle(h http.Handler, methods ...string) error
- func (r *Resource) HandleFunc(fun http.HandlerFunc, methods ...string) error
- func (r *Resource) Mux() *Mux
- func (r *Resource) Name(name string) error
- func (r *Resource) Options(allow string) *Resource
- func (r *Resource) Patch(h http.Handler) *Resource
- func (r *Resource) PatchFunc(fun http.HandlerFunc) *Resource
- func (r *Resource) Post(h http.Handler) *Resource
- func (r *Resource) PostFunc(fun http.HandlerFunc) *Resource
- func (r *Resource) Put(h http.Handler) *Resource
- func (r *Resource) PutFunc(fun http.HandlerFunc) *Resource
- func (r *Resource) Remove(methods ...string) *Resource
- func (r *Resource) URL(params map[string]string) (string, error)
Constants ¶
This section is empty.
Variables ¶
var ErrNameExists = errors.New("存在相同名称的路由项")
ErrNameExists 当为一个路由项命名时，若存在相同名称的，则返回此错误信息。
Functions ¶
Types ¶
type Mux ¶
type Mux struct {
// contains filtered or unexported fields
}
Mux 提供了强大的路由匹配功能，可以对路径按正则或是请求方法进行匹配。
用法如下：
m := mux.New()
m.Get("/abc/h1", h1).
Post("/abc/h2", h2).
Handle("/api/{version:\\d+}",h3, http.MethodGet, http.MethodPost) // 只匹配 GET 和 POST
http.ListenAndServe(m)
func New ¶
func New(disableOptions, skipCleanPath bool, notFound, methodNotAllowed http.HandlerFunc) *Mux
New 声明一个新的 Mux。
disableOptions 是否禁用自动生成 OPTIONS 功能； skipCleanPath 是否不对访问路径作处理，比如 "//api" ==> "/api"； notFound 404 页面的处理方式，为 nil 时会调用默认的方式进行处理； methodNotAllowed 405 页面的处理方式，为 nil 时会调用默认的方式进行处理， 调用此方法前，会设置 Allow 报头，如果不需要，则要在 methodNotAllowed 中去掉。
func (*Mux) AddMiddlewares
deprecated
added in
v1.1.0
func (mux *Mux) AddMiddlewares(m ...middleware.Middleware) *Mux
AddMiddlewares 添加中间件，可多次调用。
Deprecated: 采用 AppendMiddlewares 代替
func (*Mux) AnyFunc ¶
func (mux *Mux) AnyFunc(pattern string, fun http.HandlerFunc) *Mux
AnyFunc 相当于 Mux.HandleFunc(pattern, func) 的简易写法
func (*Mux) AppendMiddlewares ¶ added in v1.2.0
func (mux *Mux) AppendMiddlewares(m ...middleware.Middleware) *Mux
AppendMiddlewares 添加中间件，可多次调用。
func (*Mux) DeleteFunc ¶
func (mux *Mux) DeleteFunc(pattern string, fun http.HandlerFunc) *Mux
DeleteFunc 相当于 Mux.HandleFunc(pattern, func, http.MethodDelete) 的简易写法
func (*Mux) GetFunc ¶
func (mux *Mux) GetFunc(pattern string, fun http.HandlerFunc) *Mux
GetFunc 相当于 Mux.HandleFunc(pattern, func, http.MethodGet) 的简易写法
func (*Mux) Handle ¶
Handle 添加一条路由数据。
pattern 为路由匹配模式，可以是正则匹配也可以是字符串匹配； methods 该路由项对应的请求方法，可通过 SupportedMethods() 获得当前支持的请求方法。
func (*Mux) HandleFunc ¶
HandleFunc 功能同 Mux.Handle()，但是将第二个参数从 http.Handler 换成了 http.HandlerFunc
func (*Mux) Options ¶
Options 将 OPTIONS 请求方法的报头 allow 值固定为指定的值。
若无特殊需求，不用调用此方法，系统会自动计算符合当前路由的请求方法列表。 如果想实现对处理方法的自定义，可以显示地调用 Handle 方法:
Mux.Handle("/api/1", handle, http.MethodOptions)
func (*Mux) PatchFunc ¶
func (mux *Mux) PatchFunc(pattern string, fun http.HandlerFunc) *Mux
PatchFunc 相当于 Mux.HandleFunc(pattern, func, http.MethodPatch) 的简易写法
func (*Mux) PostFunc ¶
func (mux *Mux) PostFunc(pattern string, fun http.HandlerFunc) *Mux
PostFunc 相当于 Mux.HandleFunc(pattern, func, "POST") 的简易写法
func (*Mux) PutFunc ¶
func (mux *Mux) PutFunc(pattern string, fun http.HandlerFunc) *Mux
PutFunc 相当于 Mux.HandleFunc(pattern, func, http.MethodPut) 的简易写法
func (*Mux) ResetMiddlewares ¶ added in v1.1.0
ResetMiddlewares 清除中间件。
func (*Mux) UnshiftMiddlewares ¶ added in v1.2.0
func (mux *Mux) UnshiftMiddlewares(m ...middleware.Middleware) *Mux
UnshiftMiddlewares 前排插入中间件。可多次调用
type Prefix ¶
type Prefix struct {
// contains filtered or unexported fields
}
Prefix 可以将具有统一前缀的路由项集中在一起操作。
p := srv.Prefix("/api")
p.Get("/users") // 相当于 srv.Get("/api/users")
p.Get("/user/1") // 相当于 srv.Get("/api/user/1")
func (*Prefix) AnyFunc ¶
func (p *Prefix) AnyFunc(pattern string, fun http.HandlerFunc) *Prefix
AnyFunc 相当于 Mux.AnyFunc(prefix+pattern, func) 的简易写法
func (*Prefix) Clean ¶
Clean 清除所有以 Prefix.prefix 开头的 Entry。
当指定多个相同的 Prefix 时，调用其中的一个 Clean 也将会清除其它的：
p1 := mux.Prefix("prefix")
p2 := mux.Prefix("prefix")
p2.Clean() 将同时清除 p1 的内容，因为有相同的前缀。
func (*Prefix) DeleteFunc ¶
func (p *Prefix) DeleteFunc(pattern string, fun http.HandlerFunc) *Prefix
DeleteFunc 相当于 Mux.DeleteFunc(prefix+pattern, func) 的简易写法
func (*Prefix) GetFunc ¶
func (p *Prefix) GetFunc(pattern string, fun http.HandlerFunc) *Prefix
GetFunc 相当于 Mux.GetFunc(prefix+pattern, func) 的简易写法
func (*Prefix) HandleFunc ¶
HandleFunc 功能同 Mux.HandleFunc(prefix+pattern, fun, ...)
func (*Prefix) PatchFunc ¶
func (p *Prefix) PatchFunc(pattern string, fun http.HandlerFunc) *Prefix
PatchFunc 相当于 Mux.PatchFunc(prefix+pattern, func) 的简易写法
func (*Prefix) PostFunc ¶
func (p *Prefix) PostFunc(pattern string, fun http.HandlerFunc) *Prefix
PostFunc 相当 于Mux.PostFunc(prefix+pattern, func) 的简易写法
func (*Prefix) Prefix ¶
Prefix 在现在有 Prefix 的基础上声明一个新的 Prefix 实例。
p := mux.Prefix("/api")
v := p.Prefix("/v2")
v.Get("/users") // 相当于 g.Get("/api/v2/users")
v.Get("/user/1") // 相当于 g.Get("/api/v2/user/1")
func (*Prefix) PutFunc ¶
func (p *Prefix) PutFunc(pattern string, fun http.HandlerFunc) *Prefix
PutFunc 相当于 Mux.PutFunc(prefix+pattern, func) 的简易写法
type Resource ¶
type Resource struct {
// contains filtered or unexported fields
}
Resource 以资源地址为对象的路由配置。
r, _ := srv.Resource("/api/users/{id}")
r.Get(h) // 相当于 srv.Get("/api/users/{id}")
r.Post(h) // 相当于 srv.Post("/api/users/{id}")
url := r.URL(map[string]string{"id":5}) // 获得 /api/users/5
func (*Resource) AnyFunc ¶
func (r *Resource) AnyFunc(fun http.HandlerFunc) *Resource
AnyFunc 相当于 Mux.AnyFunc(pattern, func) 的简易写法
func (*Resource) DeleteFunc ¶
func (r *Resource) DeleteFunc(fun http.HandlerFunc) *Resource
DeleteFunc 相当于 Mux.DeleteFunc(pattern, func) 的简易写法
func (*Resource) GetFunc ¶
func (r *Resource) GetFunc(fun http.HandlerFunc) *Resource
GetFunc 相当于 Mux.GetFunc(pattern, func) 的简易写法
func (*Resource) HandleFunc ¶
func (r *Resource) HandleFunc(fun http.HandlerFunc, methods ...string) error
HandleFunc 功能同 Mux.HandleFunc(pattern, fun, ...)
func (*Resource) PatchFunc ¶
func (r *Resource) PatchFunc(fun http.HandlerFunc) *Resource
PatchFunc 相当于 Mux.PatchFunc(pattern, func) 的简易写法
func (*Resource) PostFunc ¶
func (r *Resource) PostFunc(fun http.HandlerFunc) *Resource
PostFunc 相当于 Mux.PostFunc(pattern, func) 的简易写法
func (*Resource) PutFunc ¶
func (r *Resource) PutFunc(fun http.HandlerFunc) *Resource
PutFunc 相当于 Mux.PutFunc(pattern, func) 的简易写法
func (*Resource) 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
Source Files
Directories