Application

description
elton实例的相关方法说明

Application

New

创建一个elton实例，并初始化相应的http.Server。

Example

package main
import (
    "github.com/vicanso/elton"
)
func main() {
    e := elton.New()
    err := e.ListenAndServe(":3000")
    if err != nil {
        panic(err)
    }
}

NewWithoutServer

创建一个Elton的实例，并未初始化相应的http.Server，主要用于需要自定义http server的场景，如各类超时设置等。

Example

package main
import (
    "net/http"
    "time"
    "github.com/vicanso/elton"
)
func main() {
    e := elton.NewWithoutServer()
    s := &http.Server{
        Handler:      e,
        ReadTimeout:  5 * time.Second,
        WriteTimeout: 10 * time.Second,
    }
    e.Server = s
    err := e.ListenAndServe(":3000")
    if err != nil {
        panic(err)
    }
}

ErrorHandler

自定义的Error处理，若路由处理过程中返回Error，则会触发此调用，若未指定此处理函数，则使用默认的处理，简单的输出err.Error()。

注意若在处理过程中返回的Error已被处理（如Error Handler），则并不会触发此出错调用，尽量使用中间件将Error转换为相应的输出（如JSON），而此处理仅用于针对未处理出错响应。

Example

package main
import (
    "log"
    "net/http"
    "github.com/vicanso/elton"
    "github.com/vicanso/hes"
)
func main() {
    e := elton.New()
    e.ErrorHandler = func(c *elton.Context, err error) {
        if err != nil {
            log.Printf("未处理异常，url:%s, err:%v", c.Request.RequestURI, err)
        }
        he, ok := err.(*hes.Error)
        if ok {
            c.Response.WriteHeader(he.StatusCode)
            c.Response.Write([]byte(he.Message))
        } else {
            c.Response.WriteHeader(http.StatusInternalServerError)
            c.Response.Write([]byte(err.Error()))
        }
    }
    e.GET("/", func(c *elton.Context) (err error) {
        return hes.New("abcd")
    })
    err := e.ListenAndServe(":3000")
    if err != nil {
        panic(err)
    }
}

NotFoundHandler

未匹配到相应路由时的处理，当无法获取到相应路由时，则会调用此函数（未匹配相应路由时，所有的中间件也不会被调用）。如果有相关统计需要或者自定义的404页面，则可调整此函数，否则可不设置使用默认处理(返回404 Not Found)。

Example

package main
import (
    "log"
    "net/http"
    "github.com/vicanso/elton"
    "github.com/vicanso/hes"
)
func main() {
    e := elton.New()
    e.NotFoundHandler = func(resp http.ResponseWriter, req *http.Request) {
        // 可增加统计，方便分析404的处理是被攻击还是接口调用错误
        log.Printf("404, url:%s", req.RequestURI)
        resp.WriteHeader(http.StatusNotFound)
        resp.Write([]byte("Custom not found"))
    }
    e.GET("/ping", func(c *elton.Context) (err error) {
        return hes.New("abcd")
    })
    err := e.ListenAndServe(":3000")
    if err != nil {
        panic(err)
    }
}

MethodNotAllowedHandler

该HTTP请求方式不允许，路由匹配正确但是method不匹配时，则会调用此函数（此时所有的中间件也不会被调用）。如果有相关统计需要或者自定义的405页面，则可调整此函数，否则可不设置使用默认处理(返回405 Method Not Allowed)。

Example

package main
import (
    "log"
    "net/http"
    "github.com/vicanso/elton"
    "github.com/vicanso/hes"
)
func main() {
    e := elton.New()
    e.MethodNotAllowedHandler = func(resp http.ResponseWriter, req *http.Request) {
        // 可增加统计，方便分析405的处理是被攻击还是接口调用错误
        log.Printf("405, method: %s, url:%s", req.Method, req.RequestURI)
        resp.WriteHeader(http.StatusMethodNotAllowed)
        resp.Write([]byte("Custom method not allowed"))
    }
    e.GET("/ping", func(c *elton.Context) (err error) {
        return hes.New("abcd")
    })
    err := e.ListenAndServe(":3000")
    if err != nil {
        panic(err)
    }
}

GenerateID

ID生成函数，用于每次请求调用时，生成唯一的ID值。

Example

package main
import (
    "log"
    "math/rand"
    "time"
    "github.com/oklog/ulid"
    "github.com/vicanso/elton"
    "github.com/vicanso/elton/middleware"
)
func main() {
    e := elton.New()
    e.GenerateID = func() string {
        t := time.Now()
        entropy := rand.New(rand.NewSource(t.UnixNano()))
        return ulid.MustNew(ulid.Timestamp(t), entropy).String()
    }
    e.Use(middleware.NewDefaultResponder())
    e.GET("/", func(c *elton.Context) (err error) {
        log.Println(c.ID)
        c.Body = c.ID
        return
    })
    err := e.ListenAndServe(":3000")
    if err != nil {
        panic(err)
    }
}

EnableTrace

是否启用调用跟踪，设置此参数为true，则会记录每个Handler的调用时长，建议使用时对全局中间件设定名称。

Example

package main
import (
    "log"
    "github.com/vicanso/elton"
    "github.com/vicanso/elton/middleware"
)
func main() {
    e := elton.New()
    e.EnableTrace = true
    e.OnTrace(func(c *elton.Context, traceInfos elton.TraceInfos) {
        log.Println(traceInfos[0])
        // 设置HTTP响应头：Server-Timing
        c.ServerTiming(traceInfos, "elton-")
    })
    fn := middleware.NewDefaultResponder()
    // 自定义该中间件的名称，如果设置为"-"，则忽略该中间件
    e.UseWithName(fn, "responder")
    e.GET("/", func(c *elton.Context) (err error) {
        c.Body = "Hello, World!"
        return
    })
    err := e.ListenAndServe(":3000")
    if err != nil {
        panic(err)
    }
}

SignedKeys

用于生成带签名的cookie的密钥，基于keygrip来生成与校验是否合法。使用SignedCookie获取cookie时，会校验cookie的合法性，而AddSignedCookie则会在添加cookie的同时再另外添加相对应的sig cookie。

Example

package main
import (
    "bytes"
    "net/http"
    "github.com/vicanso/elton"
)
func main() {
    e := elton.New()
    e.SignedKeys = new(elton.RWMutexSignedKeys)
    // 密钥，用于生成cookie的签名
    e.SignedKeys.SetKeys([]string{
        "secret key",
    })
    e.GET("/", func(c *elton.Context) (err error) {
        cookie, _ := c.SignedCookie("jt")
        // 如果该cookie不存在
        if cookie == nil {
            // 设置signed cookie
            err = c.AddSignedCookie(&http.Cookie{
                Name:  "jt",
                Value: "abcd",
            })
            if err != nil {
                return
            }
        }
        c.BodyBuffer = bytes.NewBufferString("Hello, World!")
        return
    })
    err := e.ListenAndServe(":3000")
    if err != nil {
        panic(err)
    }
}

ListenAndServe

设定监听地址，并调用http.Server的ListenAndServe提供HTTP服务。

Example

package main
import (
    "github.com/vicanso/elton"
)
func main() {
    e := elton.New()
    err := e.ListenAndServe(":3000")
    if err != nil {
        panic(err)
    }
}

ListenAndServeTLS

设定监听地址，并调用http.Server的ListenAndServeTLS提供HTTPS服务。

Example

package main
import (
    "github.com/vicanso/elton"
)
func main() {
    // 加密证书相关路径
    certFile := "~/cert/cert"
    keyFile := "~/cert/key"
    e := elton.New()
    err := e.ListenAndServeTLS(":3000", certFile, keyFile)
    if err != nil {
        panic(err)
    }
}

Close

关闭服务，调用http.Server的Close方法。

Example

package main
import (
    "time"
    "github.com/vicanso/elton"
)
func main() {
    e := elton.New()
    go func() {
        time.Sleep(5 * time.Second)
        e.Close()
    }()
    err := e.ListenAndServe(":3000")
    if err != nil {
        panic(err)
    }
}

GracefulClose

优雅的关闭当前服务，首先将实例的状态设置为StatusClosing，此时所有新的请求都将直接出错，在等于指定时间后，则调用http.Server的Close方法。

Example

package main
import (
    "time"
    "github.com/vicanso/elton"
)
func main() {
    e := elton.New()
    go func() {
        e.GracefulClose(10 * time.Second)
    }()
    err := e.ListenAndServe(":3000")
    if err != nil {
        panic(err)
    }
}

Handle

添加Handler的处理函数，配置请求的Method与Path，添加相应的处理函数。Elton还支持GET，POST，PUT，PATCH，DELETE，HEAD，TRACE以及OPTIONS的方法，这几个方法与Handle一致，Method则为相对应的处理，以及可使用ALL来指定支持所有的http method。

Example

package main
import (
    "github.com/vicanso/elton"
    "github.com/vicanso/elton/middleware"
)
func main() {
    e := elton.New()
    e.Use(middleware.NewDefaultResponder())
    noop := func(c *elton.Context) error {
        return c.Next()
    }
    e.Handle("GET", "/", noop, func(c *elton.Context) (err error) {
        c.Body = "Hello, World!"
        return
    })
    e.POST("/users/{type}", func(c *elton.Context) (err error) {
        c.Body = "OK"
        return
    })
    e.GET("/files/*", func(c *elton.Context) (err error) {
        c.Body = "file content"
        return
    })
    err := e.ListenAndServe(":3000")
    if err != nil {
        panic(err)
    }
}

Use/UseWithName

添加全局中间件处理函数，对于所有路由都需要使用到的中间件，则使用此函数添加，若非所有路由都使用到，可以只添加到相应的Group或者就单独添加至Handler。特别需要注意的是，如session之类需要读取数据库的，如非必要，不要使用全局中间件形式。UseWithName在添加中间件时指定其名称，用于在trace时生成统计耗时使用。

Example

package main
import (
    "log"
    "time"
    "github.com/vicanso/elton"
    "github.com/vicanso/elton/middleware"
)
func main() {
    e := elton.New()
    // 记录HTTP请求的时间、响应码
    e.Use(func(c *elton.Context) (err error) {
        startedAt := time.Now()
        req := c.Request
        err = c.Next()
        log.Printf("%s %s %d use %s", req.Method, req.URL.RequestURI(), c.StatusCode, time.Since(startedAt).String())
        return err
    })
    e.UseWithName(middleware.NewDefaultResponder(), "responder")
    e.GET("/", func(c *elton.Context) (err error) {
        c.Body = "Hello, World!"
        return
    })
    err := e.ListenAndServe(":3000")
    if err != nil {
        panic(err)
    }
}

Pre

添加全局前置中间件处理函数，对于所有请求都会调用（包括无匹配路由的请求），一般用于前置时对url做调整，如删除前缀等。

Example

package main
import (
    "net/http"
    "strings"
    "github.com/vicanso/elton"
    "github.com/vicanso/elton/middleware"
)
func main() {
    e := elton.New()
    // 如果url以/api开头，则替换
    urlPrefix := "/api"
    e.Pre(func(req *http.Request) {
        path := req.URL.Path
        if strings.HasPrefix(path, urlPrefix) {
            req.URL.Path = path[len(urlPrefix):]
        }
    })
    e.Use(middleware.NewDefaultResponder())
    e.GET("/", func(c *elton.Context) (err error) {
        c.Body = "Hello, World!"
        return
    })
    err := e.ListenAndServe(":3000")
    if err != nil {
        panic(err)
    }
}

AddGroup

将group中的所有路由处理添加至Elton，需要注意，在调用AddGroup时则将该分组下的所有路由都添加至实例，因此如果在AddGroup后再调整该group则是无效的。

Example

package main
import (
    "github.com/vicanso/elton"
    "github.com/vicanso/elton/middleware"
)
func main() {
    e := elton.New()
    e.Use(middleware.NewDefaultResponder())
    userGroup := elton.NewGroup("/users", func(c *elton.Context) error {
        return c.Next()
    })
    userGroup.GET("/me", func(c *elton.Context) error {
        c.Body = "nickname"
        return nil
    })
    e.AddGroup(userGroup)
    err := e.ListenAndServe(":3000")
    if err != nil {
        panic(err)
    }
}

OnError

添加Error的监听函数，如果当任一Handler的处理返回Error，并且其它的Handler并未将此Error处理(建议使用专门的中间件处理出错)，则会触发error事件，建议使用此事件来监控程序未处理异常。

Example

package main
import (
    "errors"
    "log"
    "github.com/vicanso/elton"
    "github.com/vicanso/elton/middleware"
)
func main() {
    e := elton.New()
    e.OnError(func(c *elton.Context, err error) {
        // 发送邮件告警等
        log.Println("error: " + err.Error())
    })
    e.Use(middleware.NewDefaultResponder())
    e.GET("/", func(c *elton.Context) (err error) {
        c.Body = "Hello, World!"
        return
    })
    // 由于未设置公共的出错处理中间件，此error会触发事件
    // 实际使用中，需要添加公共的error handler来处理，error事件只用于监控异常的出错
    e.GET("/error", func(c *elton.Context) (err error) {
        return errors.New("abcd")
    })
    err := e.ListenAndServe(":3000")
    if err != nil {
        panic(err)
    }
}