server

Documentation

Index

• Constants
• func AddRoutes(routes Routes)
• func Error(code int, msg string, errs ...error) error
• func OnStart(hook Hook)
• func Shutdown(ctx context.Context) error
• type Config
• type Handler
• type Hook
• type Method
  • func (m Method) String() string
• type Route
  • func R(uri string, method Method, handlers ...Handler) *Route
• type RouteList
  • func (rl RouteList) Register(router Router) error
• type RouteMap
  • func (rm RouteMap) Register(router Router) error
• type Router
• type Routes
• type Server
  • func New(config *Config) *Server
  • func (s *Server) AddRoutes(routes Routes) error
  • func (s *Server) Handler() http.Handler
  • func (s *Server) MustAddRoutes(routes Routes)
  • func (s *Server) Serve() error
  • func (s *Server) Shutdown(ctx context.Context) error

Constants

const (
	// ErrCodeOK 代表业务正常。
	ErrCodeOK = 0

	// ErrCodeBadRequest 代表上游请求参数不合法。
	ErrCodeBadRequest = 1

	// ErrCodeInvalidError 代表业务返回了一个错误的 error 类型。
	// 业务应该始终使用 `Error()` 方法返回错误，而不能直接返回一个普通的 error。
	ErrCodeInvalidError = 2

	// ErrCodeServerPanic 代表业务代码崩溃，框架抓住这个错误并返回错误信息。
	ErrCodeServerPanic = 3
)

const (
	// DefaultMaxHeaderBytes 是默认的 HTTP header 大小。
	DefaultMaxHeaderBytes = http.DefaultMaxHeaderBytes
)

Functions

func AddRoutes

func AddRoutes(routes Routes)

AddRoutes 向默认 HTTP server 注册路由。

func Error

func Error(code int, msg string, errs ...error) error

Error 构造一个带错误码的业务错误。 可以通过设置 errs，自动让框架在错误信息中附带各种系统错误的信息，方便调试。

func OnStart

func OnStart(hook Hook)

OnStart 注册一个回调，这个回调会在 HTTP server 初始化完成后且启动之前执行。

func Shutdown

func Shutdown(ctx context.Context) error

Shutdown 关闭当前服务。

Types

type Config

type Config struct {
	Addr string `config:"addr"` // 服务器监听的地址。

	ReadTimeout       time.Duration `config:"read_timeout"`        // ReadTimeout 设置读 HTTP 数据超时。
	ReadHeaderTimeout time.Duration `config:"read_header_timeout"` // ReadHeaderTimeout 设置读 HTTP header 超时。
	WriteTimeout      time.Duration `config:"write_timeout"`       // WriteTimeout 设置写超时。
	IdleTimeout       time.Duration `config:"idle_timeout"`        // IdleTimeout 设置空闲超时。
	MaxHeaderBytes    int           `config:"max_header_bytes"`    // MaxHeaderBytes 设置 HTTP header 最大大小，默认是 DefaultMaxHeaderBytes。

	Debug bool `config:"debug"` // Debug 表示是否处于调试状态。

	PingURI string `config:"ping_uri"` // PingURI 表示用作探针的 uri 地址，这个接口会在服务正常的时候返回 HTTP 200 OK。
}

Config 是 HTTP server 的配置。

type Handler

type Handler interface{}

Handler 代表一个处理函数。

Handler 支持的函数签名格式：

• func(ctx context.Context, req *T) (res *U, err error)：最推荐的业务函数签名形式。 其中 `T` 和 `U` 是请求和应答的结构类型。
• func(writer http.ResponseWriter, req *http.Request)：如果需要使用更底层的能力，例如传输文件，可以使用这种形式。 这个签名跟 http.HandlerFunc 一致。
• http.Handler：也可以直接注册一个 http.Handler 实例，应用场景同上。

type Hook

type Hook func(ctx context.Context, s *Server) error

Hook 是一个 HTTP server 状态回调函数。

type Method

type Method string

Method 代表 HTTP 请求方法。

const (
	GET     Method = "GET"
	POST    Method = "POST"
	PUT     Method = "PUT"
	DELETE  Method = "DELETE"
	HEAD    Method = "HEAD"
	PATCH   Method = "PATCH"
	OPTIONS Method = "OPTIONS"

	ANY Method = "ANY" // 可以接受任意 HTTP 请求。
)

各种 HTTP 请求方法。

func (Method) String

func (m Method) String() string

type Route

type Route struct {
	URI      string
	Method   Method
	Handlers []Handler
}

Route 是单条路由配置。

func R

func R(uri string, method Method, handlers ...Handler) *Route

R 生成一条路由记录。

type RouteList

type RouteList []*Route

RouteList 是一个 Route 列表。

func (RouteList) Register

func (rl RouteList) Register(router Router) error

Register 将 rl 的路由配置注册到 router 里面去。

type RouteMap

type RouteMap map[string]Routes

RouteMap 是路由配置表。

func (RouteMap) Register

func (rm RouteMap) Register(router Router) error

Register 将 rm 的路由配置注册到 router 里面去。

type Router

type Router interface {
	SubRouter(uri string, handlers ...Handler) (Router, error)
	Handle(method Method, uri string, handlers ...Handler) error
	HandleAny(uri string, handlers ...Handler) error
}

Router 代表一个路由器实现，Routes 可以向 Router 注册路由信息。

type Routes

type Routes interface {
	Register(router Router) error
}

Routes 是一个抽象的路由配置表。

type Server

type Server struct {
	// contains filtered or unexported fields
}

Server 代表一个 HTTP 服务。

func New

func New(config *Config) *Server

New 创建一个新的 HTTP 服务。

func (*Server) AddRoutes

func (s *Server) AddRoutes(routes Routes) error

AddRoutes 将 routes 路由信息添加到路有里面去。

func (*Server) Handler

func (s *Server) Handler() http.Handler

Handler 返回一个 http.Handler 用于在外部启动服务。

func (*Server) MustAddRoutes

func (s *Server) MustAddRoutes(routes Routes)

MustAddRoutes 将 routes 路由信息添加到路有里面去，如果过程中发生任何错误，直接 panic。 由于一般来说 routes 格式错误都是程序 bug，所以这个函数可以简化业务代码，无需额外判断一个 error。

func (*Server) Serve

func (s *Server) Serve() error

Serve 开始提供 HTTP 服务。这个函数永远不会返回，直到 HTTP 服务终止。

func (*Server) Shutdown

func (s *Server) Shutdown(ctx context.Context) error

Shutdown 关闭 HTTP 服务。