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
- func ClaimsFromGin(c *gin.Context) *jwtutil.Claims
- func ErrKeyFromMsg(msg string) string
- func Middleware(auth *jwtutil.Auth, opts ...Option) gin.HandlerFunc
- func RequirePermission(auth *jwtutil.Auth, perm string) gin.HandlerFunc
- func RequireRole(auth *jwtutil.Auth, role string) gin.HandlerFunc
- func UserIDFromGin(c *gin.Context) string
- type Option
- type Options
Constants ¶
const ( MsgKeyMissingToken = "auth.missing_token" // 缺少 Authorization 头 MsgKeyInvalidToken = "auth.invalid_token" // token 无效或已过期 MsgKeyForbidden = "common.forbidden" // 权限不足 )
i18n message key 常量。可在 WithErrorHandler 中用这些 key 配合 i18n.Manager 做本地化。
const ContextKeyClaims = "jwt_claims"
ContextKey 是 gin.Context 中存储 claims 的 key。
const ContextKeyUserID = "user_id"
Variables ¶
This section is empty.
Functions ¶
func ClaimsFromGin ¶
ClaimsFromGin 从 gin.Context 中提取 claims。 必须在 Middleware 之后调用。
func ErrKeyFromMsg ¶ added in v0.2.0
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 ¶
UserIDFromGin 从 gin.Context 中提取 user ID。 必须在 Middleware 之后调用。
Types ¶
type Option ¶
type Option func(*Options)
Option 是配置函数。
func WithErrorHandler ¶
WithErrorHandler 设置自定义错误处理。 handler 的 message 参数是默认英文消息,可用 ErrKeyFromMsg 转换为 i18n key。
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 配置中间件行为。