starter-gin

基于github.com/gin-gonic/gin封装的http服务组件

功能说明

屏蔽其他原始框架细节，提供统一的http服务注册方法，用户只需要关心Request/Response即可

初始化

loader := parent.NewStarterLoader([]parent.Starter{
    &ginstarter.GinStarter{
        ListenAddress: ":8080",
        DebugModule:   true,
        Routers: []ginstarter.Router{
            &router.DemoRouter{},
            &router.ParamRouter{},
            &router.AbortRouter{},
            &router.BasicAuthRouter{},
            &router.MyRestRouter{},
        },
        InitFunc: func(instance *gin.Engine) {
            instance.GET("/ping", func(context *gin.Context) {
                context.String(http.StatusOK, "alive")
            })
            instance.GET("/err", func(context *gin.Context) {
                context.Status(500)
            })
        },
        DisabledDefaultIgnoreHttpStatusCode: true,
        DisableMethodNotAllowedError:        true,
        RecoverHandlerResponse: func(ctx *gin.Context, err any) ginstarter.Response {
            logger.Logrus().Errorln("Request catch exception", err)
            return ginstarter.RespTextPlain("something error", http.StatusOK)
        },
        DisableHttpStatusCodeHandler: true,
    },
})

err := loader.Start()
if err != nil {
    fmt.Printf("%+v\n", err)
    return
}

sys.ShutdownHolding()

注册路由

type RouterInfo struct {
    // GroupPath 路由分组路径
    GroupPath string

    // BasicAuthAccount 如果指定基于BasicAuth认证的账户，则该GroupPath下资源将需要权限认证
    BasicAuthAccount *BasicAuthAccount
}

然后在初始化时指定将自动完成注册

type AbortRouter struct { // 业务路由
}

func (a *AbortRouter) Info() *ginstarter.RouterInfo {
    return &ginstarter.RouterInfo{ // 配置路由信息
        GroupPath: "abort",        // 
    }
}

// Handlers 路由功能
func (a *AbortRouter) Handlers(router *ginstarter.RouterWrapper) {
    // 注册一个GET方法处理器
    router.GET("invoke", a.invoke())
}

func (a *AbortRouter) invoke() ginstarter.HandlerWrapper {
    return func(request *ginstarter.Request) (ginstarter.Response, error) {

        // TODO: 完成业务

        // 响应一个http状态码203
        return ginstarter.RespAbortWithStatus(203), nil
    }
}

请求框架已封装常用的参数获取方法，在Handler中直接通过request执行，以Must开始的方法将在参数不满足条件时直接触发Panic，快速实现验参数不通过中断请求

// HttpMethod 获取请求方法
HttpMethod() string

// FullPath 获取请求全路径
FullPath() string

// RawGinContext 获取原始Gin上下文
RawGinContext() *gin.Context

// RequestIP 尝试获取请求方客户端IP
RequestIP() string

// GetPathParam 获取path路径参数 /:id/
GetPathParam(name string) string

// GetPathParams 获取path路径参数 /:id/ 多个参数
GetPathParams(names ...string) map[string]string

// BindPathParams /:id/ 绑定结构体用于接收UriPath参数 结构体标签格式 `uri:""`
BindPathParams(object any) error

// MustBindPathParams /:id/ 绑定结构体用于接收UriPath参数 结构体标签格式 `uri:""`
// 任何错误将触发Panic流程中断
MustBindPathParams(object any)
...

响应框架已封装常用响应体方法，方法均以Resp开始

// RespJson 响应Json数据
func RespJson(data any, httpStatusCode ...int) Response

// RespXml 响应Xml数据
func RespXml(data any, httpStatusCode ...int) Response

// RespYaml 响应Yaml数据
func RespYaml(data any, httpStatusCode ...int) Response

// RespToml 响应Toml数据
func RespToml(data any, httpStatusCode ...int) Response

// RespTextPlain 响应Json数据
func RespTextPlain(data string, httpStatusCode ...int) Response

// RespRedirect 响应重定向
func RespRedirect(url string, httpStatusCode ...int) Response

特别的Rest响应，默认框架已定制一套Rest响应标准

// RestRespStatusStruct 框架默认的Rest请求状态结构
type RestRespStatusStruct struct {

    // 标识请求系统状态 200 标识网络请求层面的成功 见StatusCode
    StatusCode    StatusCode    `json:"statusCode"`
    StatusMessage StatusMessage `json:"statusMessage"`

    // 业务错误码 仅当StatusCode为200时进入业务错误判断
    BizErrorCode    *BizErrorCode    `json:"bizErrorCode"`
    BizErrorMessage *BizErrorMessage `json:"bizErrorMessage"`

    // 系统响应时间戳
    Timestamp int64 `json:"timestamp"`
}

// RestRespStruct 框架默认的Rest请求结构
type RestRespStruct struct {

    // 请求状态描述
    Status *RestRespStatusStruct `json:"status"`

    // 仅当StatusCode为200 无业务错误码BizErrorCode 响应成功数据
    Data any `json:"data"`
}

通过RespRest开始的方法名执行该结构体的Rest风格响应，如果需要在此基础上响应更多信息，则可以使用NewRespRest()创建Rest响应实例，设置head、cookie等其他信息

如果你要自定义Rest结构体响应风格

参考test/router/myrest.go

方法1 通过NewRespRest()实例，每次传输自定义的Rest结构体响应

ginstarter.NewRespRest().SetDataResponse(&RestStruct{
        Code: 200,
        Msg:  "success",
        Data: "invoke",
    })

方法2 实现Response接口，参照NewRespRest方法设计，定制并使用自定义Response数据响应

// 自实现Response响应数据
func (m *MyRestRouter) m3() ginstarter.HandlerWrapper {
    return func(request *ginstarter.Request) (ginstarter.Response, error) {
        response := &MyRestResponse{}
        response.setData("my rest impl")
        return response, nil
    }
}

type MyRestResponse struct {
    responseData *ginstarter.ResponseData
}

func (m *MyRestResponse) Data() *ginstarter.ResponseData {
    return m.responseData
}

func (m *MyRestResponse) setData(data any) {
    m.responseData = ginstarter.NewResponseData()
    m.responseData.SetData(json.ToJsonBytes(&RestStruct{
        Code: 200,
        Msg:  "success",
        Data: data,
    }))
}

高级用法

type GinStarter struct {
    ...
    // 模块组件在启动时执行初始化
    InitFunc func(instance *gin.Engine)

    // 自定义异常响应处理 如果不指定则使用默认方式
    RecoverHandlerResponse RecoverHandlerResponse

    // 禁用错误包装处理器 在出现非200响应码或者异常时，将自动进行转化
    DisableHttpStatusCodeHandler bool
    // 在启用非200响应码自动处理后，指定忽略需要自动包裹响应码
    IgnoreHttpStatusCode []int
    // 关闭系统内置的忽略的http状态码
    DisabledDefaultIgnoreHttpStatusCode bool
    // 在出现非200响应码或者异常时具体响应策略 如果不指定则使用默认处理器 仅在UseHttpStatusCodeHandler = true 生效
    HttpStatusCodeCodeHandlerResponse HttpStatusCodeCodeHandlerResponse

    // 响应数据的结构体解码器 默认为JSON方式解码
    // 在使用NewRespRest响应结构体数据时解码为[]byte数据的解码器
    // 如果自实现Response接口将不使用解码器
    ResponseDataStructDecoder ResponseDataStructDecoder

    // 关闭包裹405错误展示，使用404代替
    DisableMethodNotAllowedError bool

    // 禁用尝试获取真实IP
    DisableForwardedByClientIP bool
    ...
}

RecoverHandlerResponse

框架自动捕获Panic异常，并执行默认处理方案，如果你想替换默认处理逻辑，可以注册该方法的具体实现逻辑
DisableHttpStatusCodeHandler

默认情况，当遇到非200响应码时，会自动进行响应处理，如果你不想使用默认处理方案，可以禁用该功能。IgnoreHttpStatusCode允许配置非200的例外错误码，不触发此逻辑
HttpStatusCodeCodeHandlerResponse

在DisableHttpStatusCodeHandler为false时，如果你想替换默认的非200错误码响应处理方案，可以注册该方法的具体实现逻辑

golang-acexy / starter-gin

readme

starter-gin

功能说明

特别的Rest响应，默认框架已定制一套Rest响应标准

高级用法