token

Documentation

Overview

Package token 传统令牌的验证方式

Index

• func DefaultBuildResponse(access, refresh string, ae, re int) any
• func SecurityScheme(id string, desc web.LocaleStringer) *openapi.SecurityScheme
• type BuildResponseFunc
• type Item
• type Response
• type Store
  • func NewCacheStore[T UserData](c web.Cache) Store[T]
• type Token
  • func New[T UserData](s web.Server, store Store[T], accessExp, refreshExp time.Duration, ...) *Token[T]
  • func (t *Token[T]) Delete(u T) error
  • func (t *Token[T]) GetInfo(ctx *web.Context) (T, bool)
  • func (t *Token[T]) Logout(ctx *web.Context) error
  • func (t *Token[T]) Middleware(next web.HandlerFunc, method, _, _ string) web.HandlerFunc
  • func (t *Token[T]) New(ctx *web.Context, v T, status int, headers ...string) web.Responser
  • func (t *Token[T]) Refresh(ctx *web.Context, status int, headers ...string) web.Responser
• type UserData

Functions

func DefaultBuildResponse

func DefaultBuildResponse(access, refresh string, ae, re int) any

DefaultBuildResponse BuildResponseFunc 的默认实现

func SecurityScheme

func SecurityScheme(id string, desc web.LocaleStringer) *openapi.SecurityScheme

SecurityScheme 声明支持 openapi 的 openapi.SecurityScheme 对象

Types

type BuildResponseFunc

type BuildResponseFunc = func(access, refresh string, accessExp, refreshExp int) any

BuildResponseFunc 构建将令牌返回给客户的结构体

access 访问令牌是必须的； refresh 刷新令牌； accessExp 表示访问令牌的过期时间； refreshExp 表示刷新令牌的过期时间；

NOTE: 之所以定义此方法，主要是用于让部分未内置在框架中的 mimetype 也可以方便处理。

type Item

type Item[V UserData] struct {
	Access   string // 如果是刷新令牌，此值关联着访问令牌，否则为空。
	UserData V      // 令牌关联的数据
}

Item 令牌关联的数据

type Response

type Response struct {
	XMLName      struct{} `json:"-" cbor:"-" xml:"token" yaml:"-"`
	AccessToken  string   `json:"access_token" xml:"access_token" cbor:"access_token" comment:"access token"`            // 访问令牌
	RefreshToken string   `json:"refresh_token" xml:"refresh_token" cbor:"refresh_token" comment:"refresh token"`        // 刷新令牌
	AccessExp    int      `json:"access_exp" xml:"access_exp,attr" cbor:"access_exp" comment:"access token expired"`     // 访问令牌的有效时长，单位为秒
	RefreshExp   int      `json:"refresh_exp" xml:"refresh_exp,attr" cbor:"refresh_exp" comment:"refresh token expired"` // 刷新令牌的有效时长，单位为秒
}

Response 申请令牌时返回的对象

type Store

type Store[V UserData] interface {
	// 保存数据
	//
	// token 令牌的值；
	// data 与令牌关联的数据；
	// ttl 过期时间；
	Save(token string, data Item[V], ttl time.Duration) error

	// 通过令牌删除关联数据
	DeleteToken(token string) error

	// 通过 [UserData.GetUID] 删除关联数据
	DeleteUID(uid string) error

	// 获取与令牌 token 关联的数据
	//
	// 如果不存在，应该返回 nil
	Get(token string) (Item[V], bool, error)
}

Store 令牌的存储接口

func NewCacheStore

func NewCacheStore[T UserData](c web.Cache) Store[T]

NewCacheStore 声明基于 web.Cache 的 Store 实现

type Token

type Token[T UserData] struct {
	// contains filtered or unexported fields
}

Token 传统的令牌管理

每次产生两个令牌： 访问令牌可用于普通的中间件验证； 刷新令牌也可以用于验证，但是是一次性的，验证完，刷新令牌和关联的访问令牌都将失效果， 所以刷新令牌一般只能用于申请下一次的令牌；

T 为每次登录之后需要与令牌关联的数据，在登录失效之前，Store 将一直保留该数据，不会再次访问数据系统。

func New

func New[T UserData](
	s web.Server,
	store Store[T],
	accessExp, refreshExp time.Duration,
	invalidTokenProblemID string,
	br BuildResponseFunc,
) *Token[T]

New 声明 Token 对象

accessExp，refreshExp 表示访问令牌和刷新令牌的有效时长，refreshExp 必须大于 accessExp； invalidTokenProblemID 令牌无效时返回的错误代码。比如将访问令牌当刷新令牌使用等； br 用于生成向客户端反馈令牌信息的结构体方法，默认为 DefaultBuildResponse；

func (*Token[T]) Delete

func (t *Token[T]) Delete(u T) error

Delete 根据指定的用户数据

func (*Token[T]) GetInfo

func (t *Token[T]) GetInfo(ctx *web.Context) (T, bool)

func (*Token[T]) Logout

func (t *Token[T]) Logout(ctx *web.Context) error

func (*Token[T]) Middleware

func (t *Token[T]) Middleware(next web.HandlerFunc, method, _, _ string) web.HandlerFunc

func (*Token[T]) New

func (t *Token[T]) New(ctx *web.Context, v T, status int, headers ...string) web.Responser

New 根据给定的参数 v 创建新的令牌

v 为新令牌需要关联的值； status 为输出的状态码； headers 报头列表，第一个元素为报头，第二个元素为对应的值，依次类推；

func (*Token[T]) Refresh

func (t *Token[T]) Refresh(ctx *web.Context, status int, headers ...string) web.Responser

Refresh 刷新令牌

type UserData

type UserData interface {
	// GetUID 获取当前数据的关联用户 ID
	GetUID() string
}

UserData 作为用户数据存储时需要实现的接口