包函数

New

func New(cfg Config) (*Processor, error)

创建新的 JWT Processor。使用 DefaultConfig() 获取默认配置，修改必要字段后传入。

参数

参数	类型	说明
cfg	Config	配置项

返回值

返回	类型	说明
processor	*Processor	JWT 处理器
err	error	配置验证失败时返回错误

示例

package main

import (
	"fmt"

	"github.com/cybergodev/jwt"
)

func main() {
	cfg := jwt.DefaultConfig()
	cfg.SecretKey = "hmac-key-that-has-at-least-32-bytes!"

	processor, err := jwt.New(cfg)
	if err != nil {
		panic(err)
	}
	defer processor.Close()

	fmt.Println("Processor created successfully")
}

错误

错误	触发条件
ErrInvalidConfig	配置项不合法
ErrInvalidSecretKey	密钥缺失、不足 32 字节、弱密钥、类型错误或 ECDSA 曲线不匹配
ErrInvalidSigningMethod	不支持的签名算法

---

DefaultConfig

func DefaultConfig() Config

返回带有合理默认值的配置。

返回值

返回	类型	说明
config	Config	默认配置

默认值

字段	默认值
AccessTokenTTL	15 * time.Minute
RefreshTokenTTL	7 * 24 * time.Hour
Issuer	"jwt-service"
SigningMethod	SigningMethodHS256
RateLimitRate	100
RateLimitWindow	time.Minute
Blacklist	DefaultBlacklistConfig()

示例

cfg := jwt.DefaultConfig()
cfg.SecretKey = "hmac-key-that-has-at-least-32-bytes!"
// 根据需要修改其他字段

---

DefaultBlacklistConfig

func DefaultBlacklistConfig() BlacklistConfig

返回带有合理默认值的黑名单配置。DefaultBlacklistConfig 是自定义黑名单参数的推荐起点：先取默认值，再覆盖需要调整的字段，最后赋给 Config.Blacklist。

返回值

返回	类型	说明
config	BlacklistConfig	默认黑名单配置

默认值

字段	默认值
CleanupInterval	5 * time.Minute
MaxSize	100000
EnableAutoCleanup	true

示例

package main

import (
	"fmt"
	"time"

	"github.com/cybergodev/jwt"
)

func main() {
	blacklist := jwt.DefaultBlacklistConfig()
	blacklist.CleanupInterval = time.Minute // 覆盖需要调整的字段，其余保留默认值

	fmt.Println(blacklist.CleanupInterval)   // 输出：1m0s
	fmt.Println(blacklist.MaxSize)           // 输出：100000
	fmt.Println(blacklist.EnableAutoCleanup) // 输出：true
}

---

NewNumericDate

func NewNumericDate(t time.Time) NumericDate

从 time.Time 创建 NumericDate。NewNumericDate 常用于显式构造 RegisteredClaims 的时间声明字段（如 ExpiresAt、NotBefore）。

参数

参数	类型	说明
t	time.Time	时间值

返回值

返回	类型	说明
date	NumericDate	JWT 数字日期

示例

package main

import (
	"fmt"
	"time"

	"github.com/cybergodev/jwt"
)

func main() {
	date := jwt.NewNumericDate(time.Unix(1700000000, 0))

	b, err := date.MarshalJSON()
	if err != nil {
		panic(err)
	}
	fmt.Println(string(b)) // 输出：1700000000
}

---

NewRateLimiter

func NewRateLimiter(maxRate int, window time.Duration) *RateLimiter

创建令牌桶限流器。

参数

参数	类型	说明
maxRate	int	窗口内最大请求数（≤0 时默认 100）
window	time.Duration	时间窗口（≤0 时默认 1 分钟）

返回值

返回	类型	说明
limiter	*RateLimiter	限流器实例