ginext

package module
v0.0.0-...-b8a3b91 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 11, 2024 License: GPL-3.0 Imports: 6 Imported by: 1

README

Go Gin Extender package

Extends functionality for Gin - fast web framework

Usage

Automatic registration of complex controllers

Instead of registering many single handler function, use controller type and its methods to automatically create appropriate gin router paths using the below functionality

Controller type, its instance (object) and endpoint methods

Controller is an any type (and so its instance), which have at least one endpoint method. endpoint is a common type method (with Controller type receiver) of gin.HandlerFunc signature func (*gin.Context) and specific format of its name: EpMethodName = <HttpMethod><Endpoint>, where <HttpMethod> is one of RFC7231 http methods [Get Head Post Put Delete Connect Options Trace] and <Endpoint> is standard go method name CamelCase suffix, which will be final endpoint of full abs router path to this method, automagically converting from CamelCase to kebab-case, e.g.


type ControllerExample struct {}

func (c *ControllerExample) GetUserName(ctx *gin.Context) {
	ctx.String(http.StatusOK, "hello from GetUserName")
}

func main () {

	// ...

	r := gin.New()
	
	c := &ControllerExample{}
	
	ginext.EmbedController(r, c)
	
	// now after starting r listening on port 8080, 
	// you can request GET `http://localhost:8080/user-name` ==> "hello from GetUserName"
	
	// ...
}

If you want to attach Controller to source IRoute as base segment of endpoints set, use ginext.AttachController - kebab-case'd controller name without optional Controller prefix would be used as segment name:


type ControllerCommonSegment struct {}

func (c *ControllerCommonSegment) PostSaveData(ctx *gin.Context) {
	ctx.String(http.StatusOK, "hello from PostSaveData")
}

// can use empty name to register "" (index) endpoint
func (c *ControllerCommonSegment) Get(ctx *gin.Context) {
	ctx.String(http.StatusOK, "hello from Get - root [index] endpoint")
}


func main () {

	// ...

	r := gin.New()
	
	c := &ControllerCommonSegment{}
	
	ginext.AttachController(r, c)
	
	// now after starting r listening on port 8080, 
	// GET `http://localhost:8080/common-segment/` ==> "hello from Get - root [index] endpoint"
	// POST `http://localhost:8080/common-segment/save-data` ==> "hello from PostSaveData"
	
	// ...
}
Additional optional wrapper handlers

You may use special Controller's methods Init, Before and After for additional control:

type ControllerWithWrappers struct {}

func (c *ControllerWithWrappers) Init() error {
	fmt.Println("this is init")
	return nil
}

func (c *ControllerWithWrappers) Before(ctx *gin.Context) {
	fmt.Println("before")
}

func (c *ControllerWithWrappers) Get(ctx *gin.Context) {
	fmt.Println("get")
}

func (c *ControllerWithWrappers) After(ctx *gin.Context) {
	fmt.Println("after")
}

func main () {

	// ...

	r := gin.New()
	
	c := &ControllerWithWrappers{}
	
	ginext.AttachController(r, c) // immediately prints "this is init"
	
	// now after starting r listening on port 8080, 
	// you can request GET `http://localhost:8080/with-wrappers/` ==> prints "before" "get" "after", each on new line
	
	// ...
}

Init is special method of signature ControllerInitMethod = func() error, which is calling when controller starting register in router and may returns error, which immediately breaks registration and returns to a superior caller

Before and After is the common Gin HandlerFunc, which wrapped every registered explicit handler of the controller

Append trailing slashes to controller method endpoints on registration

Use ginext.AppendTrailingSlash(true) before registration by AttachController / EmbedController to enable automatic trailing slash append

type ControllerExample struct {}

func (c *ControllerExample) GetUserName(ctx *gin.Context) {
	ctx.String(http.StatusOK, "hello from GetUserName")
}

func main () {

	// ...

	r := gin.New()
	
	c := &ControllerExample{}
	
	ginext.AppendTrailingSlash(true) // before `ginext.EmbedController` 
	
	ginext.EmbedController(r, c)
	
	// now after starting r listening on port 8080, 
	// you can request GET `http://localhost:8080/user-name/` ==> "hello from GetUserName"
	
	// ...
}
Any Gin router type

AppendController and EmbedController use gin interface gin.IRoutes as router arg, so you may use either gin.Engine or gin.RouterGroup, including groups with attached middleware (e.g. auth and session mws) and path's prefix

Additional examples

See router_test.go

TODO
  • more tests required
  • implement endpoint ctx Params (the easiest way is to append CatchAll option to endpoints paths)

LICENSE

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.

Copyright © 2023 Illirgway

Documentation

Index

Constants

View Source
const (
	ControllerPrefix = "Controller"

	MethodActionPrefix = "Action"
)

Variables

This section is empty.

Functions

func AppendTrailingSlash

func AppendTrailingSlash(on bool)

func AttachController

func AttachController(rg RouterGroup, instance interface{}) error

func EmbedController

func EmbedController(rg RouterGroup, instance interface{}) error

Types

type ControllerInitMethod

type ControllerInitMethod = func() error

type HandlerFunc

type HandlerFunc = func(ctx *gin.Context)

type RouterGroup

type RouterGroup = gin.IRoutes

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL