API 參考
套件 goJwt(github.com/pardnchiu/go-jwt/core)的匯出型別與方法。
New
func New(c Config) (*JWTAuth, error)
初始化 JWTAuth、連線 Redis,並載入或產生 ECDSA 金鑰。
Close
func (j *JWTAuth) Close() error
關閉 Redis 用戶端。
Create
func (j *JWTAuth) Create(w http.ResponseWriter, r *http.Request, auth *Auth) JWTAuthResult
簽署 Access Token、建立 Refresh ID、寫入 Cookie,並將狀態存入 Redis。
Verify
func (j *JWTAuth) Verify(w http.ResponseWriter, r *http.Request) JWTAuthResult
驗證 Access Token;過期或缺失時自動走刷新流程,並檢查撤銷與裝置指紋。
Revoke
func (j *JWTAuth) Revoke(w http.ResponseWriter, r *http.Request) JWTAuthResult
清除 Cookie,將 Access Token 標記為已撤銷,並縮短 Refresh ID 存活時間。
GinMiddleware
func (j *JWTAuth) GinMiddleware() gin.HandlerFunc
Gin 中介層:驗證後將 *Auth 寫入 context 鍵 user。
HTTPMiddleware
func (j *JWTAuth) HTTPMiddleware(next http.Handler) http.Handler
標準 net/http 中介層:驗證後將 *Auth 寫入 request context。
GetAuthDataFromGinContext
func GetAuthDataFromGinContext(c *gin.Context) (*Auth, bool)
從 Gin context 取出驗證後的使用者。
GetAuthDataFromHTTPRequest
func GetAuthDataFromHTTPRequest(r *http.Request) (*Auth, bool)
從 HTTP request context 取出驗證後的使用者。
Auth
| 欄位 | 型別 | 說明 |
|---|---|---|
ID |
string |
使用者 ID |
Name |
string |
顯示名稱 |
Email |
string |
|
Thumbnail |
string |
頭像 URL |
Scope |
[]string |
權限範圍 |
Role |
string |
角色 |
Level |
int |
等級 |
JWTAuthResult
| 欄位 | 型別 | 說明 |
|---|---|---|
StatusCode |
int |
HTTP 狀態碼 |
Success |
bool |
操作是否成功 |
Data |
*Auth |
驗證後的使用者資料 |
Token |
*TokenResult |
簽發的 Token 配對 |
Error |
string |
錯誤訊息 |
ErrorTag |
string |
機器可讀錯誤標籤 |
TokenResult
| 欄位 | 型別 | 說明 |
|---|---|---|
Token |
string |
Access Token |
RefreshId |
string |
Refresh ID |
標頭
| 標頭 | 方向 | 說明 |
|---|---|---|
Authorization: Bearer <token> |
請求 | Access Token(Cookie 替代) |
X-Refresh-ID |
請求 | Refresh ID(Cookie 替代) |
X-Device-FP |
請求 | 覆寫裝置指紋 |
X-Device-ID |
請求 | 穩定裝置 ID |
X-New-Access-Token |
回應 | 刷新後的新 Access Token |
X-New-Refresh-ID |
回應 | 完整重建後的新 Refresh ID |
錯誤標籤
| 標籤 | 意義 |
|---|---|
data_missing |
缺少必要 auth/refresh 資料 |
data_invalid |
Token 解析或 claim 驗證失敗 |
unauthorized |
未登入或工作階段無效 |
revoked |
Access Token 已標記撤銷 |
not_found |
找不到 Refresh 資料 |
not_matched |
指紋或 claim 不符 |
failed_to_update |
Redis 更新失敗 |
failed_to_create |
建立流程失敗 |
failed_to_sign |
JWT 簽署失敗 |
failed_to_store |
Redis 寫入失敗 |
failed_to_get |
Redis 讀取失敗 |