github.com/darkit/gin 是一个以 gin-gonic/gin 为底座的增强版 Go Web 框架。 它保留 Gin 的高性能与生态兼容性，在其上增加了增强型 Context、可组合的 Engine 配置、认证子系统、丰富中间件、Chi 风格正则路由、自动注册路由，以及一组可直接复用的基础能力包。

这个模块适合希望继续使用 Gin 编程模型，但又希望获得更多“开箱即用”能力的项目：

• 兼容 Gin 心智模型：核心入口仍然是 Engine、Router、Context
• 增强 API 体验：通过扩展 Context 与 Router，减少样板代码
• 面向生产场景：内置认证、缓存、日志、优雅停机、限流、签名校验等能力
• 强调渐进式采用：可以只使用局部特性，不需要一次接入全部子模块

来自 engine.go 与 options.go 的核心能力：

• New(opts ...OptionFunc)：创建增强引擎
• Default(opts ...OptionFunc)：创建默认引擎，并自动挂载：
  • middleware.RequestID()
  • middleware.Recovery()
  • middleware.Logger()
• 内置默认组件：
  • logger.NewNoop()
  • cache.NewMemoryCache()
  • lifecycle.NewManager()
  • middleware.NewRegistry()
  • 默认上传配置
• 内置优雅启动/关闭：Run() / Shutdown()
• 通过 sync.Pool 复用增强型 Context

来自 context.go 及其同族文件：

• 统一参数获取：Param()、ParamInt()、ParamBool()、ParamTime()、ParamSlice() 等
• 带错误返回的参数解析：ParamIntE()、ParamFloatE() 等
• 快捷绑定与校验：BindAndValidate()、BindJSONOrAbort()、BindQueryOrAbort()
• 标准化响应：
  • Success() / Created() / Accepted() / NoContent()
  • BadRequest() / Unauthorized() / Forbidden() / NotFound()
  • ValidationError() / InternalError() / TooManyRequests() 等
• 分页辅助：ParsePagination()、PaginationParams()、Paginated()
• 请求信息辅助：GetIP()、GetUserAgent()、RequestID()、GetBearerToken()、IsSecure()
• Cookie / Header / Content negotiation 辅助
• 与 Engine 绑定的能力透出：Logger()、Cache()、Auth()

来自 router.go：

• 增强型处理器签名：type HandlerFunc func(*Context)
• 常规 HTTP 路由：GET / POST / PUT / PATCH / DELETE / HEAD / OPTIONS / Any
• 多方法注册：Match()
• 分组路由：Group()
• REST 资源路由：Resource() / CRUD()
• 版本化入口：Version() / VersionedAPI()
• 健康检查：HealthCheck()
• 静态资源支持：Static()、StaticFS()、StaticFile()、EmbedFS()、EmbedFile()
• 中间件智能适配：Use() 同时支持
  • 增强型 HandlerFunc
  • 原生 gin.HandlerFunc
  • func(http.Handler) http.Handler 形式的标准/Chi 风格中间件

来自 regex_router.go 与 engine.go：

• 通过 Engine.RegexRouter() 启用正则路由
• 支持 Chi 风格模式：
  • /users/{id:[0-9]+}
  • /posts/{slug}
  • /files/*
• 作为标准 Gin 路由的 fallback，集成到 NoRoute 链路中
• 支持正则路由分组与局部中间件
• 匹配参数通过 regex:<name> 写入上下文

来自 auto_register.go：

• 根据控制器方法名自动推断 HTTP 方法与路由路径
• 约定式命名：GetXxx、PostXxx、DeleteXxx 等
• 方法名以 Regex 结尾时自动注册到 RegexRouter
• 支持 WithPrefix()、WithMiddleware()、WithRegexPattern()
• 控制器可通过 RoutePrefix() 和 RegexPatterns() 定制行为

来自 auth/ 子模块与 context_auth.go：

• 通过 WithAuth(auth.AuthConfig) 将认证系统接入 Engine
• 在处理器中通过 c.Auth() 获取请求级认证上下文
• 提供 Manager、AuthContext、StpLogic 等核心抽象
• 支持内存与 Redis 存储
• 提供登录、权限、角色、Session、refresh token、OAuth2 等能力

来自 middleware/：

内置中间件覆盖常见 API 服务场景，包括：

• RequestID
• Recovery
• Logger
• CORS
• Secure
• Timeout
• Cache
• ETag
• Compress
• Idempotent
• RateLimit 及高级限流变体
• SignatureVerify
• Throttle
• URLFormat
• RealIP
• Maybe
• NoCache
• RouteHeaders
• ValidateParam
• Sunset

pkg/ 下提供与框架配套但可独立复用的能力包：

• cache：缓存抽象与实现
• circuitbreaker：熔断控制
• concurrency：并发工具
• diagnostic：诊断辅助
• export：导出能力
• image：图片处理
• lifecycle：生命周期管理
• logger：日志接口
• mail：邮件发送
• mask：数据脱敏
• retry：重试工具
• routes：路由辅助
• sms：短信/验证码能力
• static：静态资源相关能力
• swagger：Swagger/OpenAPI 生成
• validator：校验辅助
• websocket：WebSocket 能力

• Go 1.25+

go get github.com/darkit/gin@latest

package main

import (
	"log"

	gin "github.com/darkit/gin"
)

func main() {
	app := gin.Default()
	r := app.Router()

	r.GET("/ping", func(c *gin.Context) {
		c.Success(gin.H{
			"message":    "pong",
			"request_id": c.RequestID(),
		})
	})

	if err := app.Run(); err != nil {
		log.Fatal(err)
	}
}

默认行为：

• 监听地址默认为 :8080
• 已自动启用 RequestID、Recovery、Logger
• 处理器可直接使用增强型 *gin.Context

package main

import (
	"log"
	"time"

	gin "github.com/darkit/gin"
	"github.com/darkit/gin/middleware"
)

func main() {
	app := gin.New(
		gin.WithAddr(":9090"),
		gin.WithReadTimeout(10*time.Second),
		gin.WithWriteTimeout(10*time.Second),
		gin.WithGracefulShutdown(15*time.Second),
		gin.Production(),
	)

	r := app.Router()
	r.Use(
		middleware.CORS(),
		middleware.Secure(),
	)

	v1 := r.Version("1")
	v1.HealthCheck()
	v1.GET("/users/:id", func(c *gin.Context) {
		id, err := c.ParamIntE("id")
		if err != nil {
			c.BadRequest("invalid id")
			return
		}

		c.Success(gin.H{
			"id": id,
		})
	})

	if err := app.Run(); err != nil {
		log.Fatal(err)
	}
}

从代码结构看，根模块大致分为 5 层：

┌──────────────────────────────────────────────┐
│ Application Handlers / Controllers          │
├──────────────────────────────────────────────┤
│ Router / RegexRouter / AutoRegister         │
├──────────────────────────────────────────────┤
│ Enhanced Context                            │
├──────────────────────────────────────────────┤
│ Engine + OptionFunc + Middleware Registry   │
├──────────────────────────────────────────────┤
│ auth/* + middleware/* + pkg/*               │
└──────────────────────────────────────────────┘

Engine 是整个框架的聚合根，负责：

• 包装底层 *gin.Engine
• 保存运行配置与共享组件
• 初始化认证、缓存、日志、上传、Swagger、生命周期等能力
• 为每次请求分配与回收增强型 Context

增强型 Context 在保留原生 gin.Context 的同时，提供：

• 参数解析
• 标准响应
• 分页、绑定、校验
• 安全/请求元信息读取
• 对缓存、日志、认证等组件的便捷访问

Router 将增强型 Context 与路由注册串起来，负责：

• 把 func(*Context) 适配到底层 Gin
• 提供分组、版本化、资源路由等高级组织方式
• 聚合中间件并兼容多种中间件签名
• 为 Swagger 收集路由文档元信息

RegexRouter 是标准路由未命中时的增强匹配层：

• 使用 Chi 风格路径语法
• 通过 NoRoute 融入 Gin 请求流
• 保证标准路由优先，正则路由次之

• auth/：认证授权与会话能力
• middleware/：请求链横切能力
• pkg/：通用基础设施与工具包

.
├── engine.go            # Engine 聚合与运行入口
├── context.go           # 核心增强 Context
├── context_*.go         # Context 的分能力扩展（auth/upload/image/export/...）
├── router.go            # Router 增强与 Swagger 路由元信息
├── regex_router.go      # Chi 风格正则路由
├── auto_register.go     # 控制器自动注册
├── options.go           # OptionFunc 配置模式
├── auth/                # 认证子系统
├── middleware/          # 中间件生态
├── pkg/                 # 基础能力工具包
├── docs/                # 参考文档与扩展说明
└── examples/            # 可运行示例

路径	作用
auth/	认证、授权、会话、refresh token、OAuth2
middleware/	请求链横切关注点：恢复、限流、缓存、签名校验等
pkg/cache	缓存接口与实现
pkg/lifecycle	服务运行与优雅停机
pkg/logger	日志抽象
pkg/swagger	Swagger/OpenAPI 文档生成
pkg/mail	邮件能力
pkg/sms	短信/验证码能力
pkg/websocket	WebSocket 连接能力
examples/	框架能力示例

options.go 使用 OptionFunc 模式组织配置，便于在 New() / Default() 中组合。

app := gin.New(
	gin.WithAddr(":8080"),
	gin.WithReadTimeout(10*time.Second),
	gin.WithWriteTimeout(10*time.Second),
	gin.WithGracefulShutdown(30*time.Second),
)

app := gin.New(
	gin.Development(),
)

app = gin.New(
	gin.Production(),
)

根据 options.go：

• Development()：设置较宽松的 ReadTimeout
• Production()：设置 ReadTimeout、WriteTimeout 与优雅关闭超时

app := gin.New(
	gin.WithTrustedProxies([]string{"127.0.0.1", "10.0.0.0/8"}),
)

app := gin.New(
	gin.WithLogger(customLogger),
	gin.WithCache(customCache),
)

app := gin.New(
	gin.WithUploadDir("./uploads"),
	gin.WithMaxFileSize(10<<20),
	gin.WithMaxMultipartMemory(32<<20),
	gin.WithAllowedExts("jpg", "png", "pdf"),
)

app := gin.New(
	gin.WithMail(mailCfg),
	gin.WithSMS(smsCfg),
)

app := gin.New(
	gin.WithAuth(auth.AuthConfig{
		Secret:     "replace-me",
		Expiry:     24 * time.Hour,
		TokenStyle: auth.TokenStyleJWT,
	}),
)

启用后：

• Engine 会初始化内部 auth.Manager
• 请求中可通过 c.Auth() 获取认证上下文
• 若未显式指定存储，默认回退到内存存储

app := gin.New(
	gin.EnableSwagger(swagger.SwaggerConfig{
		Title:       "Example API",
		Description: "Generated by github.com/darkit/gin",
		Version:     "v1.0.0",
	}),
)

启用后默认注册：

• /swagger
• /swagger/doc.json

并可通过 Router.GET(...).Doc(...).Description(...).Param(...).Response(...).Tag(...) 追加路由文档元信息。

r.Resource("users", userController)

将注册：

• GET /users
• POST /users
• GET /users/:id
• PUT /users/:id
• PATCH /users/:id
• DELETE /users/:id

type UserController struct{}

func (u *UserController) GetProfile(c *gin.Context) {
	c.Success(gin.H{"ok": true})
}

func (u *UserController) GetOrderIDRegex(c *gin.Context) {
	c.Success(gin.H{"id": c.GetString("regex:id")})
}

func main() {
	app := gin.Default()
	r := app.Router()
	r.AutoRegister(&UserController{}, gin.WithPrefix("/api/users"))
}

rx := app.RegexRouter()
rx.GET("/orders/{id:[0-9]+}", func(c *gin.Context) {
	c.Success(gin.H{
		"order_id": c.GetString("regex:id"),
	})
})

该模块并不是替代 Gin 的“重写版”，而是基于 Gin 的增强层：

• 底层仍使用 github.com/gin-gonic/gin
• 路由匹配、HTTP 处理、上下文基础能力仍沿用 Gin
• 根模块在此基础上增加更适合业务项目的工程化能力

如果你已经熟悉 Gin，这个模块的上手成本会很低。

• 使用指南
• API 参考
• 缓存中间件说明
• Swagger 实现说明
• darkit-gin Skill 包
• 变更记录

• auth/README.md
• auth/DESIGN.md

• examples/basic/README.md
• examples/advanced/README.md
• examples/static/README.md
• examples/swagger-demo/README.md

• pkg/sms/README.md

推荐在以下场景使用：

• 希望保留 Gin 生态，但减少重复业务样板代码
• 需要增强版请求上下文与统一响应模型
• 需要认证、限流、缓存、签名校验等通用能力
• 需要约定式自动注册路由或正则路由能力
• 希望将缓存、日志、生命周期、邮件、短信等基础设施统一接入

• 若只是轻量 API，可直接从 gin.Default() + Router() 开始
• 若有认证需求，优先使用 WithAuth()，并在生产环境切换到 Redis 存储
• 若需要统一化运维能力，可优先组合 WithLogger()、WithCache()、Production() 与中间件栈
• 若需要复杂 URL 约束，优先使用 RegexRouter() 或 AutoRegister(..., WithRegexPattern(...))

仓库现有文档声明为 MIT 许可。若用于公开分发，建议在仓库根目录补充标准 LICENSE 文件以便自动识别。