gin

package module
v0.2.0 Latest Latest
Warning

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

Go to latest
Published: Aug 19, 2026 License: MIT Imports: 4 Imported by: 0

Documentation

Overview

Package gin provides Gin middleware for JWT authentication.

用法:

auth, _ := jwtutil.New(jwtutil.Config{Secret: []byte("..."), ...})
r := gin.New()
r.Use(jwtingin.Middleware(auth, jwtingin.WithPublicPaths("/health", "/api/v1/auth/login")))
// 受保护的路由...
r.GET("/api/v1/me", jwtingin.RequireRole(auth, "admin"), h.GetMe)

i18n: 默认消息为英文。如需本地化,用 WithErrorHandler 配合 i18n manager:

r.Use(jwtingin.Middleware(auth,
    jwtingin.WithPublicPaths("/health"),
    jwtingin.WithErrorHandler(func(c *gin.Context, code int, msg string) {
        // 用 i18n key 替换默认消息
        respgin.FailI18n(c, jwtingin.ErrKeyFromMsg(msg), nil)
    }),
))

Index

Constants

View Source
const (
	MsgKeyMissingToken = "auth.missing_token"  // 缺少 Authorization 头
	MsgKeyInvalidToken = "auth.invalid_token"  // token 无效或已过期
	MsgKeyUnauthorized = "common.unauthorized" // 未授权(无 claims)
	MsgKeyForbidden    = "common.forbidden"    // 权限不足
)

i18n message key 常量。可在 WithErrorHandler 中用这些 key 配合 i18n.Manager 做本地化。

View Source
const ContextKeyClaims = "jwt_claims"

ContextKey 是 gin.Context 中存储 claims 的 key。

View Source
const ContextKeyUserID = "user_id"

Variables

This section is empty.

Functions

func ClaimsFromGin

func ClaimsFromGin(c *gin.Context) *jwtutil.Claims

ClaimsFromGin 从 gin.Context 中提取 claims。 必须在 Middleware 之后调用。

func ErrKeyFromMsg added in v0.2.0

func ErrKeyFromMsg(msg string) string

ErrKeyFromMsg 将默认英文消息转换为 i18n key。 在 WithErrorHandler 中使用:

jwtingin.WithErrorHandler(func(c *gin.Context, code int, msg string) {
    key := jwtingin.ErrKeyFromMsg(msg)
    // 用 key 做 i18n 翻译
})

func Middleware

func Middleware(auth *jwtutil.Auth, opts ...Option) gin.HandlerFunc

Middleware 返回 JWT 鉴权 Gin 中间件。 从 Authorization: Bearer <token> 提取 token,验证后将 claims 存入 context。 publicPaths 中的路径前缀自动跳过鉴权。

func RequirePermission

func RequirePermission(auth *jwtutil.Auth, perm string) gin.HandlerFunc

RequirePermission 返回一个要求指定权限的中间件。 必须在 Middleware 之后使用。

func RequireRole

func RequireRole(auth *jwtutil.Auth, role string) gin.HandlerFunc

RequireRole 返回一个要求指定角色的中间件。 必须在 Middleware 之后使用。

func UserIDFromGin

func UserIDFromGin(c *gin.Context) string

UserIDFromGin 从 gin.Context 中提取 user ID。 必须在 Middleware 之后调用。

Types

type Option

type Option func(*Options)

Option 是配置函数。

func WithErrorHandler

func WithErrorHandler(h func(c *gin.Context, code int, msg string)) Option

WithErrorHandler 设置自定义错误处理。 handler 的 message 参数是默认英文消息,可用 ErrKeyFromMsg 转换为 i18n key。

func WithPublicPaths

func WithPublicPaths(paths ...string) Option

WithPublicPaths 设置公开路径前缀列表。

type Options

type Options struct {
	// PublicPaths 是不需要鉴权的路径前缀列表。
	// 例如: ["/health", "/api/v1/auth/login", "/docs"]
	PublicPaths []string
	// ErrorHandler 自定义鉴权失败时的响应。如果为 nil,使用默认 JSON 响应。
	// message 参数是默认英文消息,可用 ErrKeyFromMsg 转换为 i18n key。
	ErrorHandler func(c *gin.Context, code int, message string)
}

Options 配置中间件行为。

Jump to

Keyboard shortcuts

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