API 參考

最後更新 2026-10-21

github.com/pardnchiu/go-jwt/core（package goJwt）所有匯出的函式、方法與型別。

函式

簽章	說明
`func New(c Config) (*JWTAuth, error)`	套用預設值、載入或產生金鑰、連線 Redis 並 `PING`，回傳實例
`func GetAuthDataFromGinContext(c gin.Context) (Auth, bool)`	讀取 `GinMiddleware` 存入的使用者資料
`func GetAuthDataFromHTTPRequest(r http.Request) (Auth, bool)`	讀取 `HTTPMiddleware` 存入 request context 的使用者資料

JWTAuth 方法

簽章	說明
`func (j JWTAuth) Create(w http.ResponseWriter, r http.Request, auth *Auth) JWTAuthResult`	簽發 Access Token 與 Refresh ID，寫入 Cookie 與 Redis；`auth` 為 `nil` 時回 `400 data_missing`
`func (j JWTAuth) Verify(w http.ResponseWriter, r http.Request) JWTAuthResult`	驗證請求，必要時透明刷新（見驗證流程）
`func (j JWTAuth) Revoke(w http.ResponseWriter, r http.Request) JWTAuthResult`	清除 Cookie、撤銷 Access Token、Refresh ID 5 秒後失效（見撤銷）
`func (j *JWTAuth) GinMiddleware() gin.HandlerFunc`	Gin 中介層（見中介層）
`func (j *JWTAuth) HTTPMiddleware(next http.Handler) http.Handler`	`net/http` 中介層
`func (j *JWTAuth) Close() error`	關閉 Redis 連線

JWTAuth 的欄位皆未匯出；同一個實例可在多個 goroutine 間共用。

設定型別

型別	說明
`Config`	頂層設定：`Redis`、`File`、`Option`、`Cookie`、`CheckAuth`
`Redis`	`Host`、`Port`、`Password`、`DB`
`File`	`PrivateKeyPath`、`PublicKeyPath`
`Option`	金鑰內容、有效期、Cookie 名稱、`MaxVersion`、`RefreshTTL`
`Cookie`	`Domain`、`Path`、`SameSite`、`Secure`、`HttpOnly`（皆為指標）

欄位與預設值見設定。

結果與資料型別

type Auth struct {
	ID        string   `json:"id"`
	Name      string   `json:"name"`
	Email     string   `json:"email"`
	Thumbnail string   `json:"thumbnail,omitempty"`
	Scope     []string `json:"scope,omitempty"`
	Role      string   `json:"role,omitempty"`
	Level     int      `json:"level,omitempty"`
}
type JWTAuthResult struct {
	StatusCode int          `json:"status_code"`
	Success    bool         `json:"success"`
	Data       *Auth        `json:"data,omitempty"`
	Token      *TokenResult `json:"token,omitempty"`
	Error      string       `json:"error,omitempty"`
	ErrorTag   string       `json:"error_tag,omitempty"`
}
type TokenResult struct {
	Token     string `json:"token"`
	RefreshId string `json:"refresh_id"`
}

型別	何時有值
`JWTAuthResult.Data`	`Create`、`Verify` 成功時
`JWTAuthResult.Token`	`Create` 成功時；`Verify` 觸發刷新並成功時
`JWTAuthResult.ErrorTag`	失敗時，值見狀態碼與錯誤標籤

內部狀態型別

這些型別有匯出，但呼叫端通常不需要直接使用：

型別	說明
`RefreshData`	Redis `refresh:<id>` 的內容：`Data`、`Version`、`Fingerprint`、`Exp`、`Iat`、`Jti`（見 Token 模型）
`RefreshId`	計算 Refresh ID 雜湊的輸入：`ID`、`Name`、`Email`、`Fingerprint`、`Iat`、`Jti`
`Pem`	解析後的 ECDSA 金鑰對；欄位 `private`、`public` 未匯出，無法從外部建立或讀取