The highest tagged major version is
README
¶
sgin
这是一个 gin 的封装版本，旨在提供更加智能、简洁的 API 开发体验。它通过增强的 Handler 签名、统一的参数绑定和自动化的 OpenAPI 文档生成，让开发者专注于业务逻辑。
安装
go get github.com/baagod/sgin
快速开始
package main
import (
"github.com/baagod/sgin"
"github.com/baagod/sgin/oa"
)
func main() {
// 1. 初始化引擎 (可选配置)
r := sgin.New(sgin.Config{
// 开启 OpenAPI 文档支持 (测试功能)
OpenAPI: oa.New(oa.Config{}),
})
// 2. 定义路由
r.GET("/", func(c *sgin.Ctx) string {
return "Hello sgin!"
})
// 3. 启动服务
r.Run(":8080")
}
核心特性
1. 智能 Handler
sgin 支持多种灵活的 Handler 签名，自动处理参数绑定和响应发送。
支持的签名示例：
func(*gin.Context)兼容 ginfunc(*sgin.Ctx) errorfunc(*sgin.Ctx) (any, error)func(*sgin.Ctx, input Struct) (any, error)func(*sgin.Ctx, input Struct) (any)
请求参数绑定
只需在 Handler 的第二个参数定义结构体，sgin 会自动将 URI、Header、Query、Form 和 Body (JSON/XML) 的数据绑定到该结构体上。
type UserReq struct {
ID int `uri:"id" binding:"required"`
Name string `form:"name" binding:"required" failtip:"姓名不能为空"`
Age int `form:"age" default:"18"`
Token string `header:"Authorization"`
}
r.POST("/users/:id", func(c *sgin.Ctx, req UserReq) (map[string]any, error) {
// req 已自动绑定并校验通过
return map[string]any{
"id": req.ID,
"name": req.Name,
"age": req.Age,
}, nil
})
统一响应处理
Handler 的返回值会被自动处理：
error: 自动调用配置的ErrorHandler。data: 自动根据请求头Accept格式化为 JSON, XML 或 Text。
你也可以使用 c.Send() 手动发送：
c.Send("Hello") // Text
c.Send(User{}, sgin.FormatJSON) // JSON
c.Send(User{}, sgin.FormatXML) // 或者手动指定格式
c.Send(err) // Error
2. 增强的 Context (sgin.Ctx)
sgin.Ctx 封装了 gin.Context，提供了更便捷的方法：
- 参数获取:
Values()方法统一获取所有来源的参数（Query, Form, JSON Body 等）。 - 类型转换:
ValueInt("age"),ValueBool("is_admin")等。 - 文件处理:
ValueFile("file")获取上传文件。 - 响应控制:
Status(200),SetHeader("Key", "Val")。 - TraceID: 自动生成或传递
X-Request-ID。 - Gin: 返回
*gin.Context。
func(c *sgin.Ctx) {
id := c.ValueInt("id", 0) // 获取参数，默认值为 0
ip := c.IP()
traceID := c.TraceID()
}
3. OpenAPI 文档 (测试版)
sgin 可以通过分析 Handler 的输入输出结构体，自动生成 OpenAPI 3.1 文档。
启用方法:
在 sgin.Config 中配置 OpenAPI 字段。
文档自定义:
在路由定义的第一个参数传入 func(*oa.Operation) 来补充文档信息。
type LoginReq struct {
Username string `json:"username" doc:"用户名"`
Password string `json:"password" doc:"密码"`
}
// 注册路由时添加文档描述
r.POST("/login", func(op *oa.Operation) {
op.Summary = "用户登录"
op.Tags = []string{"Auth"}
}, func(c *sgin.Ctx, req LoginReq) (string, error) {
return "token-xxx", nil
})
启动后访问 /openapi.yaml 查看生成的规范。
4. 强力 Panic 恢复与日志
sgin 内置了一个增强的 Recovery 中间件，相比原生 gin，它提供了更强大的调试能力：
- 多级调用栈追溯：自动定位业务代码中的错误位置，跳过框架和标准库的干扰。
- 源码上下文展示：在控制台直接打印报错行及其前后的源代码片段，并高亮显示。
- 路径自动简化：智能缩短文件路径（如简化
GOROOT、GOPATH或项目根目录路径）。 - 双流输出：同时提供美观的控制台日志和结构化的 JSON 日志，方便接入日志系统。
配置示例：
r := sgin.New(sgin.Config{
// Panic 恢复回调
Recovery: func(c *sgin.Ctx, logStr, jsonStr string) {
// 1. 控制台打印美观的彩色日志 (推荐开发环境)
fmt.Print(logStr)
// 2. 将结构化 JSON 日志写入文件 (推荐生产环境)
// 包含时间、请求信息、完整堆栈和源码上下文
f, _ := os.OpenFile("panic.log", os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0666)
defer f.Close()
f.WriteString(jsonStr + "\n")
},
})
配置
conf := sgin.Config{
Mode: gin.ReleaseMode, // 运行模式
// 自定义错误处理
ErrorHandler: func(c *sgin.Ctx, err error) error {
return c.Status(500).Send(map[string]any{"error": err.Error()})
},
// 自定义日志
Logger: func(c *sgin.Ctx, msg string, jsonMsg string) bool {
// 返回 true 使用默认日志输出，false 拦截
return true
},
}
Documentation
¶
Index ¶
- Constants
- func DefaultErrorHandler(c *Ctx, err error) error
- func Logger(c *Ctx)
- func Recovery(c *Ctx)
- type Config
- type Ctx
- func (c *Ctx) Content(value string) *Ctx
- func (c *Ctx) Cookie(name string) (string, error)
- func (c *Ctx) Get(key string, value ...any) any
- func (c *Ctx) Gin() *gin.Context
- func (c *Ctx) Header(key string, value ...string) string
- func (c *Ctx) IP() string
- func (c *Ctx) Method() string
- func (c *Ctx) Next() error
- func (c *Ctx) Param(key string) string
- func (c *Ctx) Path(full ...bool) string
- func (c *Ctx) RawBody() (body []byte)
- func (c *Ctx) SaveFile(file *multipart.FileHeader, dst string) error
- func (c *Ctx) Send(body any, format ...string) error
- func (c *Ctx) SendHTML(name string, data any) error
- func (c *Ctx) SetCookie(name, value string, maxAge int, path, domain string, secure, httpOnly bool)
- func (c *Ctx) SetHeader(key string, value string) *Ctx
- func (c *Ctx) Status(code int) *Ctx
- func (c *Ctx) StatusCode() int
- func (c *Ctx) TraceID() string
- func (c *Ctx) Value(key string, def ...string) string
- func (c *Ctx) ValueAny(key string, def ...any) any
- func (c *Ctx) ValueBool(key string, def ...any) bool
- func (c *Ctx) ValueFile(key string) (*multipart.FileHeader, error)
- func (c *Ctx) ValueFloat64(key string, def ...any) float64
- func (c *Ctx) ValueInt(key string, def ...any) int
- func (c *Ctx) ValueInt64(key string, def ...any) int64
- func (c *Ctx) Values() map[string]any
- type Engine
- type Error
- func ErrBadGateway(msg ...string) *Error
- func ErrBadRequest(msg ...string) *Error
- func ErrConflict(msg ...string) *Error
- func ErrEntityTooLarge(msg ...string) *Error
- func ErrExpectationFailed(msg ...string) *Error
- func ErrFailedDependency(msg ...string) *Error
- func ErrForbidden(msg ...string) *Error
- func ErrGatewayTimeout(msg ...string) *Error
- func ErrGone(msg ...string) *Error
- func ErrHTTPVersionNotSupported(msg ...string) *Error
- func ErrHeaderFieldsTooLarge(msg ...string) *Error
- func ErrInsufficientStorage(msg ...string) *Error
- func ErrInternalServerError(msg ...string) *Error
- func ErrLengthRequired(msg ...string) *Error
- func ErrLocked(msg ...string) *Error
- func ErrLoopDetected(msg ...string) *Error
- func ErrMethodNotAllowed(msg ...string) *Error
- func ErrMisdirectedRequest(msg ...string) *Error
- func ErrNetworkAuthenticationRequired(msg ...string) *Error
- func ErrNotAcceptable(msg ...string) *Error
- func ErrNotExtended(msg ...string) *Error
- func ErrNotFound(msg ...string) *Error
- func ErrNotImplemented(msg ...string) *Error
- func ErrPaymentRequired(msg ...string) *Error
- func ErrPreconditionFailed(msg ...string) *Error
- func ErrPreconditionRequired(msg ...string) *Error
- func ErrProxyAuthRequired(msg ...string) *Error
- func ErrRangeNotSatisfiable(msg ...string) *Error
- func ErrServiceUnavailable(msg ...string) *Error
- func ErrTeapot(msg ...string) *Error
- func ErrTimeout(msg ...string) *Error
- func ErrTooEarly(msg ...string) *Error
- func ErrTooManyRequests(msg ...string) *Error
- func ErrURITooLong(msg ...string) *Error
- func ErrUnauthorized(msg ...string) *Error
- func ErrUnavailableForLegalReasons(msg ...string) *Error
- func ErrUnprocessableEntity(msg ...string) *Error
- func ErrUnsupportedMediaType(msg ...string) *Error
- func ErrUpgradeRequired(msg ...string) *Error
- func ErrVariantAlsoNegotiates(msg ...string) *Error
- func NewError(code int, msg ...string) *Error
- func NotModified(msg ...string) *Error
- type Handler
- type IRouter
- type RecoverInfo
- type Response
- func (r *Response) Failed(data ...any) *Response
- func (r *Response) OK(data ...any) *Response
- func (r *Response) SetCode(code any) *Response
- func (r *Response) SetEvent(event string) *Response
- func (r *Response) SetMessage(msg any) *Response
- func (r *Response) SetStatus(status any, code ...any) *Response
- type Router
- func (r *Router) DELETE(path string, handlers ...Handler) IRouter
- func (r *Router) GET(path string, handlers ...Handler) IRouter
- func (r *Router) Group(path string, handlers ...Handler) IRouter
- func (r *Router) Handle(method, path string, handlers ...Handler) IRouter
- func (r *Router) POST(path string, handlers ...Handler) IRouter
- func (r *Router) PUT(path string, handlers ...Handler) IRouter
- func (r *Router) Static(path, root string) IRouter
- func (r *Router) Use(args ...Handler) IRouter
- type Stack
Constants ¶
View Source
const ( FormatXML = "XML" FormatJSON = "JSON" FormatText = "Text" FormatUpload = "Upload" FormatDownload = "Download" )
View Source
const ( MIMETextXML = "text/xml" MIMETextHTML = "text/html" MIMETextPlain = "text/plain" MIMETextJavaScript = "text/javascript" MIMETextCSS = "text/css" MIMETextYAML = "text/yaml" MIMEXML = "application/xml" MIMEJSON = "application/json" MIMEJavaScript = "application/javascript" MIMECBOR = "application/cbor" MIMEForm = "application/x-www-form-urlencoded" MIMEOctetStream = "application/octet-stream" MIMEMultipartForm = "multipart/form-data" MIMEMsgPack = "application/vnd.msgpack" MIMETextXMLUTF8 = "text/xml; charset=utf-8" MIMETextHTMLUTF8 = "text/html; charset=utf-8" MIMETextPlainUTF8 = "text/plain; charset=utf-8" MIMETextJavaScriptUTF8 = "text/javascript; charset=utf-8" MIMETextCSSUTF8 = "text/css; charset=utf-8" MIMETextYAMLUTF8 = "text/yaml; charset=utf-8" MIMEXMLUTF8 = "application/xml; charset=utf-8" MIMEJSONUTF8 = "application/json; charset=utf-8" )
MIME types that are commonly used
View Source
const ( HeaderAuthorization = "Authorization" HeaderProxyAuthenticate = "Proxy-Authenticate" HeaderProxyAuthorization = "Proxy-Authorization" HeaderWWWAuthenticate = "WWW-Authenticate" HeaderAge = "Age" HeaderCacheControl = "Cache-Control" HeaderClearSiteData = "Clear-Site-Data" HeaderExpires = "Expires" HeaderPragma = "Pragma" HeaderWarning = "Warning" HeaderAcceptCH = "Accept-CH" HeaderAcceptCHLifetime = "Accept-CH-Lifetime" HeaderContentDPR = "Content-DPR" HeaderDPR = "DPR" HeaderEarlyData = "Early-Data" HeaderSaveData = "Save-Data" HeaderViewportWidth = "Viewport-Width" HeaderWidth = "Width" HeaderETag = "ETag" HeaderIfMatch = "If-Match" HeaderIfModifiedSince = "If-Modified-Since" HeaderIfNoneMatch = "If-None-Match" HeaderIfUnmodifiedSince = "If-Unmodified-Since" HeaderLastModified = "Last-Modified" HeaderVary = "Vary" HeaderConnection = "Connection" HeaderKeepAlive = "Keep-Alive" HeaderAccept = "Accept" HeaderAcceptCharset = "Accept-Charset" HeaderAcceptEncoding = "Accept-Encoding" HeaderAcceptLanguage = "Accept-Language" HeaderCookie = "Cookie" HeaderExpect = "Expect" HeaderMaxForwards = "Max-Forwards" HeaderSetCookie = "Set-Cookie" HeaderAccessControlAllowCredentials = "Access-Control-Allow-Credentials" HeaderAccessControlAllowHeaders = "Access-Control-Allow-Headers" HeaderAccessControlAllowMethods = "Access-Control-Allow-Methods" HeaderAccessControlAllowOrigin = "Access-Control-Allow-Origin" HeaderAccessControlExposeHeaders = "Access-Control-Expose-Headers" HeaderAccessControlMaxAge = "Access-Control-Max-Age" HeaderAccessControlRequestHeaders = "Access-Control-Request-Headers" HeaderAccessControlRequestMethod = "Access-Control-Request-Method" HeaderOrigin = "Origin" HeaderTimingAllowOrigin = "Timing-Allow-Origin" HeaderXPermittedCrossDomainPolicies = "X-Permitted-Cross-Domain-Policies" HeaderDNT = "DNT" HeaderTk = "Tk" HeaderContentDisposition = "Content-Disposition" HeaderContentEncoding = "Content-Encoding" HeaderContentLanguage = "Content-Language" HeaderContentLength = "Content-Length" HeaderContentLocation = "Content-Location" HeaderContentType = "Content-Type" HeaderForwarded = "Forwarded" HeaderVia = "Via" HeaderXForwardedFor = "X-Forwarded-For" HeaderXForwardedHost = "X-Forwarded-Host" HeaderXForwardedProto = "X-Forwarded-Proto" HeaderXForwardedProtocol = "X-Forwarded-Protocol" HeaderXForwardedSsl = "X-Forwarded-Ssl" HeaderXUrlScheme = "X-Url-Scheme" HeaderLocation = "Location" HeaderFrom = "From" HeaderHost = "Host" HeaderReferer = "Referer" HeaderReferrerPolicy = "Referrer-Policy" HeaderUserAgent = "User-Agent" HeaderAllow = "Allow" HeaderServer = "Server" HeaderAcceptRanges = "Accept-Ranges" HeaderContentRange = "Content-Range" HeaderIfRange = "If-Range" HeaderRange = "Range" HeaderContentSecurityPolicy = "Content-Security-Policy" HeaderContentSecurityPolicyReportOnly = "Content-Security-Policy-Report-Only" HeaderCrossOriginResourcePolicy = "Cross-Origin-Resource-Policy" HeaderExpectCT = "Expect-CT" HeaderPermissionsPolicy = "Permissions-Policy" HeaderPublicKeyPins = "Public-Key-Pins" HeaderPublicKeyPinsReportOnly = "Public-Key-Pins-Report-Only" HeaderStrictTransportSecurity = "Strict-Transport-Security" HeaderUpgradeInsecureRequests = "Upgrade-Insecure-Requests" HeaderXContentTypeOptions = "X-Content-Type-Options" HeaderXDownloadOptions = "X-Download-Options" HeaderXFrameOptions = "X-Frame-Options" HeaderXPoweredBy = "X-Powered-By" HeaderXXSSProtection = "X-XSS-Protection" HeaderLastEventID = "Last-Event-ID" HeaderNEL = "NEL" HeaderPingFrom = "Ping-From" HeaderPingTo = "Ping-To" HeaderReportTo = "Report-To" HeaderTE = "TE" HeaderTrailer = "Trailer" HeaderTransferEncoding = "Transfer-Encoding" HeaderSecWebSocketAccept = "Sec-WebSocket-Accept" HeaderSecWebSocketExtensions = "Sec-WebSocket-Extensions" HeaderSecWebSocketKey = "Sec-WebSocket-Key" HeaderSecWebSocketProtocol = "Sec-WebSocket-Protocol" HeaderSecWebSocketVersion = "Sec-WebSocket-Version" HeaderAcceptPatch = "Accept-Patch" HeaderAcceptPushPolicy = "Accept-Push-Policy" HeaderAcceptSignature = "Accept-Signature" HeaderAltSvc = "Alt-Svc" HeaderDate = "Date" HeaderIndex = "Index" HeaderLargeAllocation = "Large-Allocation" HeaderLink = "Link" HeaderPushPolicy = "Push-Policy" HeaderRetryAfter = "Retry-After" HeaderServerTiming = "Server-Timing" HeaderSignature = "Signature" HeaderSignedHeaders = "Signed-Headers" HeaderSourceMap = "SourceMap" HeaderUpgrade = "Upgrade" HeaderXDNSPrefetchControl = "X-DNS-Prefetch-Control" HeaderXPingback = "X-Pingback" HeaderXRequestID = "X-Request-ID" HeaderXRequestedWith = "X-Requested-With" HeaderXRobotsTag = "X-Robots-Tag" HeaderXUACompatible = "X-UA-Compatible" HeaderAccessControlAllowPrivateNetwork = "Access-Control-Allow-Private-Network" HeaderAccessControlRequestPrivateNetwork = "Access-Control-Request-Private-Network" )
HTTP Headers were copied from net/http.
View Source
const CtxKey = "_baa/sgin/ctxkey"
Variables ¶
This section is empty.
Functions ¶
func DefaultErrorHandler ¶
DefaultErrorHandler 默认的错误处理器
Types ¶
type Config ¶
type Config struct {
Mode string // gin.DebugMode | gin.ReleaseMode | gin.TestMode
TrustedProxies []string // gin.SetTrustedProxies
Recovery func(c *Ctx, out, s string) // 回调 [带颜色的输出] 和 [结构化日志]
ErrorHandler func(c *Ctx, err error) error
// 回调 [纯文本] 和 [JSON] 日志，返回 true 输出默认日志。
Logger func(c *Ctx, text string, s string) bool
OpenAPI *oa.OpenAPI
}
type Ctx ¶
type Ctx struct {
Request *http.Request
Writer gin.ResponseWriter
Params gin.Params
Keys map[string]any
// contains filtered or unexported fields
}
func (*Ctx) StatusCode ¶
func (*Ctx) ValueFile ¶ added in v0.0.7
func (c *Ctx) ValueFile(key string) (*multipart.FileHeader, error)
ValueFile 获取上传的文件
func (*Ctx) ValueFloat64 ¶ added in v0.0.7
type Engine ¶
type Engine struct {
Router
// contains filtered or unexported fields
}
type Error ¶
Error 是 APIError 的默认实现
func ErrEntityTooLarge ¶ added in v0.0.8
ErrEntityTooLarge 413
func ErrExpectationFailed ¶
ErrExpectationFailed 417
func ErrHTTPVersionNotSupported ¶
ErrHTTPVersionNotSupported 505
func ErrHeaderFieldsTooLarge ¶ added in v0.0.8
ErrHeaderFieldsTooLarge 431
func ErrInsufficientStorage ¶
ErrInsufficientStorage 507
func ErrInternalServerError ¶
ErrInternalServerError 500
func ErrMisdirectedRequest ¶
ErrMisdirectedRequest 421
func ErrNetworkAuthenticationRequired ¶
ErrNetworkAuthenticationRequired 511
func ErrPreconditionFailed ¶
ErrPreconditionFailed 412
func ErrPreconditionRequired ¶
ErrPreconditionRequired 428
func ErrProxyAuthRequired ¶
ErrProxyAuthRequired 407
func ErrRangeNotSatisfiable ¶ added in v0.0.8
ErrRangeNotSatisfiable 416
func ErrServiceUnavailable ¶
ErrServiceUnavailable 503
func ErrUnavailableForLegalReasons ¶
ErrUnavailableForLegalReasons 451
func ErrUnprocessableEntity ¶
ErrUnprocessableEntity 422
func ErrUnsupportedMediaType ¶
ErrUnsupportedMediaType 415
func ErrVariantAlsoNegotiates ¶
ErrVariantAlsoNegotiates 506
type IRouter ¶ added in v0.0.7
type IRouter interface {
Use(...Handler) IRouter
GET(string, ...Handler) IRouter
POST(string, ...Handler) IRouter
PUT(string, ...Handler) IRouter
DELETE(string, ...Handler) IRouter
Group(string, ...Handler) IRouter
Handle(method, path string, handlers ...Handler) IRouter
Static(path, root string) IRouter
}
type RecoverInfo ¶ added in v0.0.9
type RecoverInfo struct {
Time string `json:"time"`
Method string `json:"method"`
Host string `json:"host"`
Path string `json:"path"`
ContentType string `json:"content"`
IP string `json:"ip"`
Traceid string `json:"traceid"`
Error string `json:"error"`
Sources []*Stack `json:"stack"`
}
func (*RecoverInfo) JSON ¶ added in v0.0.9
func (r *RecoverInfo) JSON() string
func (*RecoverInfo) String ¶ added in v0.0.9
func (r *RecoverInfo) String() string
type Response ¶
type Response struct {
Event string `json:"event"`
Status int `json:"status"`
Code int `json:"code"`
Count int `json:"count"`
Message string `json:"msg"`
Data any `json:"data"`
}
Source Files
¶
Directories
Click to show internal directories.
Click to hide internal directories.