使用Golang实现Branca令牌规范的插件库

Branca是一种安全的令牌格式，基于Fernet规范但使用更现代的加密算法(IETF XChaCha20-Poly1305 AEAD)。下面我将介绍如何在Go中使用branca库实现Branca令牌的创建和验证。

安装branca库

首先安装branca的Go实现库：

go get github.com/hako/branca

基本用法示例

package main

import (
	"fmt"
	"time"

	"github.com/hako/branca"
)

func main() {
	// 1. 创建Branca令牌
	// 密钥必须是32字节长
	key := "supersecretkeyyoushouldnotcommit" // 32字节
	b, err := branca.NewBranca(key)
	if err != nil {
		panic(err)
	}

	// 设置令牌的TTL(可选)
	b.SetTTL(3600) // 1小时过期

	// 编码/创建令牌
	payload := "{\"user_id\":12345,\"role\":\"admin\"}"
	token, err := b.EncodeToString(payload)
	if err != nil {
		panic(err)
	}
	fmt.Println("生成的Branca令牌:", token)

	// 2. 解码/验证令牌
	decodedPayload, err := b.DecodeToString(token)
	if err != nil {
		panic(err)
	}
	fmt.Println("解码后的内容:", decodedPayload)

	// 3. 处理过期令牌
	// 创建一个很快过期的令牌进行测试
	b.SetTTL(1) // 1秒过期
	expiringToken, err := b.EncodeToString(payload)
	if err != nil {
		panic(err)
	}

	time.Sleep(2 * time.Second) // 等待令牌过期

	_, err = b.DecodeToString(expiringToken)
	if err != nil {
		fmt.Println("令牌已过期:", err)
	}
}

高级用法

使用结构体作为payload

type UserClaims struct {
	UserID int    `json:"user_id"`
	Role   string `json:"role"`
	Email  string `json:"email"`
}

func main() {
	key := "supersecretkeyyoushouldnotcommit"
	b, _ := branca.NewBranca(key)

	// 编码结构体
	claims := UserClaims{
		UserID: 12345,
		Role:   "admin",
		Email:  "user@example.com",
	}

	token, err := b.Encode(claims) // 自动JSON编码
	if err != nil {
		panic(err)
	}

	// 解码到结构体
	var decodedClaims UserClaims
	err = b.Decode(token, &decodedClaims)
	if err != nil {
		panic(err)
	}
	fmt.Printf("解码后的结构体: %+v\n", decodedClaims)
}

自定义时间戳

func main() {
	key := "supersecretkeyyoushouldnotcommit"
	b, _ := branca.NewBranca(key)

	// 使用自定义时间戳(Unix时间)
	customTime := time.Now().Add(-30 * time.Minute).Unix()
	token, err := b.EncodeToStringWithTimestamp("payload", customTime)
	if err != nil {
		panic(err)
	}

	// 解码时会检查时间戳是否有效(根据TTL设置)
	_, err = b.DecodeToString(token)
	if err != nil {
		fmt.Println("可能已过期:", err)
	}
}

最佳实践

1. 密钥管理：永远不要将密钥硬编码在代码中，使用环境变量或密钥管理系统
2. TTL设置：根据使用场景设置合理的TTL(生存时间)
3. 错误处理：总是检查解码时的错误，可能的原因包括：
   • 令牌过期
   • 令牌被篡改
   • 密钥不匹配
4. payload大小：Branca令牌有大小限制，不适合存储大量数据

与其他库的比较

Branca相比JWT有以下优势：

• 更小的令牌体积
• 更简单的规范
• 默认使用更现代的加密算法(XChaCha20-Poly1305)
• 内置时间戳和过期处理

这个branca库是Go中最流行的Branca实现之一，API设计简洁，性能良好，适合大多数需要安全令牌的场景。