biu

README

BIU

a set of toolkits for go-restful.

Installation

go get -u github.com/tuotoo/biu

Examples

pkg-examples

Contributing

All our projects follow the GitFlow branching model, from development to release. If you are not familiar with it, there are several guides and tutorials to make you understand what it is about.

Thanks

• go-restful
• jwt-go
• Gin
• Beego
• json-iterator
• errc
• zerolog
• httpexpect
• easyjson
• pocket
• ...and many more Open Source Cool Go Projects 🌟

Documentation

Overview

Example

package main

import (
	"github.com/tuotoo/biu"
	"github.com/tuotoo/biu/box"
	"github.com/tuotoo/biu/opt"
)

// Foo controller
type Foo struct{}

// WebService implements CtlInterface
func (ctl Foo) WebService(ws biu.WS) {
	ws.Route(ws.GET("/").Doc("Get Bar").
		Param(ws.QueryParameter("num", "number").
			DataType("integer")).
		DefaultReturns("Bar", Bar{}),
		opt.RouteID("example.foo"),
		opt.RouteTo(ctl.getBar),
		opt.RouteErrors(map[int]string{
			100: "num not Number",
		}),
	)

	ws.Route(ws.POST("/").
		Doc("Post Req"),
		opt.RouteID("example.post"),
		opt.RouteAPI(ctl.post),
		opt.RouteErrors(map[int]string{
			100: "num not Number",
		}),
	)

	// add more routes as you like:
	// ws.Route(ws.POST("/foo"),nil)
	// ...
}

// Bar is the response of getBar
type Bar struct {
	Msg string `json:"msg"`
	Num int    `json:"num"`
}

func (ctl Foo) getBar(ctx box.Ctx) {
	num, err := ctx.Query("num").Int()
	ctx.Must(err, 100)

	ctx.ResponseJSON(Bar{Msg: "bar", Num: num})
}

func (ctl Foo) post(ctx box.Ctx, api struct {
	Form struct{ Num int }
}) {
	ctx.ResponseJSON(Bar{Msg: "POST", Num: api.Form.Num})
}

func main() {
	c := biu.New()
	c.Filter(biu.LogFilter())
	c.AddServices("/v1", nil,
		biu.NS{
			NameSpace:  "foo",
			Controller: Foo{},
			Desc:       "Foo Controller",
		},
	)
	// Note: you should add swagger service after adding services.
	// swagger document will be available at http://localhost:8080/v1/swagger
	swaggerService := c.NewSwaggerService(biu.SwaggerInfo{
		Title:        "Foo Bar",
		Description:  "Foo Bar Service",
		ContactName:  "TuoToo",
		ContactEmail: "jqs7@tuotoo.com",
		ContactURL:   "https://tuotoo.com",
		Version:      "1.0.0",
		RoutePrefix:  "/v1",
	})
	c.Add(swaggerService)
	c.Run(":8080", nil)
}

Index

• Constants
• Variables
• func AddServices(prefix string, opts opt.ServicesFuncArr, wss ...NS)
• func AuthFilter(code int, i ...*auth.Instance) restful.FilterFunction
• func Filter(f func(ctx box.Ctx)) restful.FilterFunction
• func FilterWithLogger(f func(ctx box.Ctx), logger log.ILogger) restful.FilterFunction
• func Handle(f func(ctx box.Ctx)) restful.RouteFunction
• func HandleWithLogger(f func(ctx box.Ctx), logger log.ILogger) restful.RouteFunction
• func ListenAndServe(srv *http.Server, addrChan chan<- string) error
• func LogFilter() restful.FilterFunction
• func NewSwaggerService(info SwaggerInfo) *restful.WebService
• func Run(addr string, opts ...opt.RunFunc)
• func WrapHandler(f func(ctx box.Ctx)) http.HandlerFunc
• type Container
  • func New(container ...*restful.Container) *Container
  • func (c *Container) AddServices(prefix string, opts opt.ServicesFuncArr, wss ...NS)
  • func (c *Container) FilterFunc(f func(ctx box.Ctx)) restful.FilterFunction
  • func (c *Container) Handle(f func(ctx box.Ctx)) restful.RouteFunction
  • func (c *Container) NewSwaggerService(info SwaggerInfo) *restful.WebService
  • func (c *Container) NewTestServer() *TestServer
  • func (c *Container) Run(addr string, opts ...opt.RunFunc)
• type CtlInterface
• type NS
• type SwaggerInfo
• type TestServer
  • func NewTestServer() *TestServer
  • func (s *TestServer) WithT(t *testing.T) *httpexpect.Expect
• type WS
  • func (ws WS) Route(builder *restful.RouteBuilder, opts ...opt.RouteFunc)

Examples

• Package

Constants

const (
	// MIME_HTML_FORM is application/x-www-form-urlencoded header
	MIME_HTML_FORM = "application/x-www-form-urlencoded"
	// MIME_FILE_FORM is multipart/form-data
	MIME_FILE_FORM = "multipart/form-data"
)

Variables

var AutoGenPathDoc = false

var DefaultContainer = New(restful.DefaultContainer)

Functions

func AddServices

func AddServices(prefix string, opts opt.ServicesFuncArr, wss ...NS)

AddServices adds services with namespace.

func AuthFilter

func AuthFilter(code int, i ...*auth.Instance) restful.FilterFunction

AuthFilter checks if request contains JWT, and sets UserID in Attribute if exists,

func Filter

func Filter(f func(ctx box.Ctx)) restful.FilterFunction

Filter transform a biu handler to a restful.FilterFunction

func FilterWithLogger

func FilterWithLogger(f func(ctx box.Ctx), logger log.ILogger) restful.FilterFunction

func Handle

func Handle(f func(ctx box.Ctx)) restful.RouteFunction

Handle transform a biu handler to a restful.RouteFunction.

func HandleWithLogger

func HandleWithLogger(f func(ctx box.Ctx), logger log.ILogger) restful.RouteFunction

func ListenAndServe

func ListenAndServe(srv *http.Server, addrChan chan<- string) error

ListenAndServe listens on the TCP network address srv.Addr and then calls Serve to handle requests on incoming connections. Accepted connections are configured to enable TCP keep-alives. If srv.Addr is blank, ":http" is used. ListenAndServe always returns a non-nil error.

func LogFilter

func LogFilter() restful.FilterFunction

LogFilter logs

{
	remote_addr,
	method,
	uri,
	proto,
	status_code,
	content_length,
}

for each request

func NewSwaggerService

func NewSwaggerService(info SwaggerInfo) *restful.WebService

NewSwaggerService creates a swagger webservice in /swagger

func Run

func Run(addr string, opts ...opt.RunFunc)

Run starts up a web server with default container.

func WrapHandler

func WrapHandler(f func(ctx box.Ctx)) http.HandlerFunc

WrapHandler wraps a biu handler to http.HandlerFunc

Types

type Container

type Container struct {
	*restful.Container
	// contains filtered or unexported fields
}

Container of restful

func New

func New(container ...*restful.Container) *Container

New creates a new restful container.

func (*Container) AddServices

func (c *Container) AddServices(prefix string, opts opt.ServicesFuncArr, wss ...NS)

AddServices adds services with namespace for container.

func (*Container) FilterFunc

func (c *Container) FilterFunc(f func(ctx box.Ctx)) restful.FilterFunction

Filter transform a biu handler to a restful.FilterFunction

func (*Container) Handle

func (c *Container) Handle(f func(ctx box.Ctx)) restful.RouteFunction

func (*Container) NewSwaggerService

func (c *Container) NewSwaggerService(info SwaggerInfo) *restful.WebService

NewSwaggerService creates a swagger webservice in /swagger

func (*Container) NewTestServer

func (c *Container) NewTestServer() *TestServer

NewTestServer returns a Test Server.

func (*Container) Run

func (c *Container) Run(addr string, opts ...opt.RunFunc)

Run starts up a web server for container.

type CtlInterface

type CtlInterface interface {
	WebService(WS)
}

CtlInterface is the interface of controllers

type NS

type NS struct {
	NameSpace    string       // url parent of controller
	Controller   CtlInterface // controller implement CtlInterface
	Desc         string       // description of controller of namespace
	ExternalDesc string       // external documentation of controller
	ExternalURL  string       // external url of ExternalDesc
}

NS contains configuration of a namespace

type SwaggerInfo

type SwaggerInfo struct {
	Title          string
	Description    string
	TermsOfService string
	ContactName    string
	ContactURL     string
	ContactEmail   string
	LicenseName    string
	LicenseURL     string
	Version        string
	WebServicesURL string
	DisableCORS    bool
	// swagger service will running under
	// http://<api>/<RoutePrefix>/<RouteSuffix>
	// by default the RouteSuffix is swagger
	RoutePrefix string
	RouteSuffix string
}

SwaggerInfo contains configuration of swagger documents.

type TestServer

type TestServer struct {
	*httptest.Server
}

TestServer wraps a httptest.Server

func NewTestServer

func NewTestServer() *TestServer

NewTestServer returns a Test Server.

func (*TestServer) WithT

func (s *TestServer) WithT(t *testing.T) *httpexpect.Expect

WithT accept testing.T and returns httpexpect.Expect

type WS

type WS struct {
	*restful.WebService
	Container *Container
	// contains filtered or unexported fields
}

WS extends *restful.WebService

func (WS) Route

func (ws WS) Route(builder *restful.RouteBuilder, opts ...opt.RouteFunc)

Route creates a new Route using the RouteBuilder and add to the ordered list of Routes.