chongming-utils-jwt/README.md

chongming-jwt

基于 Rust + PyO3 实现的 JWT 库，性能远超纯 Python 实现，支持多种签名算法。所有编解码操作在 Rust 层执行，不阻塞 Python 事件循环。

---

安装

uv pip install -e utils/jwt

需要 Rust 工具链，uv 自动通过 maturin 编译。

---

支持的算法

算法	类型	说明
HS256	HMAC-SHA256	对称签名（推荐）
HS384	HMAC-SHA384	对称签名
HS512	HMAC-SHA512	对称签名
RS256	RSA-SHA256	非对称签名
RS384	RSA-SHA384	非对称签名
RS512	RSA-SHA512	非对称签名

---

API

JWT 类

from chongming_jwt import JWT

jwt = JWT(
    secret="your-secret-key-change-in-production",
    algorithm="HS256"
)

参数	类型	默认值	说明
secret	str	—	签名密钥（HS256 建议 ≥ 32 字节）
algorithm	str	"HS256"	签名算法

方法

# 编码
token: str = jwt.encode(
    payload='{"sub": "user_id", "username": "john"}',
    expires_in_seconds=3600
)

# 解码（自动验证签名和过期时间）
claims: str = jwt.decode(token)

# 仅验证，不返回载荷
is_valid: bool = jwt.validate(token)

方法	签名	说明
encode	(payload: str, expires_in_seconds: int) -> str	编码 JSON 载荷为 JWT Token
decode	(token: str) -> str	解码并验证 Token，无效时抛出异常
validate	(token: str) -> bool	验证有效性，返回布尔值

---

注意事项

• payload 必须包含 sub 字段（JWT 规范）
• HS256 密钥建议 ≥ 32 字节
• RS256/384/512 需要 PEM 格式 RSA 密钥
• 超时后 decode 抛出异常

---

手动编译

uv run maturin develop --release -m utils/jwt/Cargo.toml

---

依赖 (Rust)

• jsonwebtoken — JWT 编解码
• pyo3 — Python 绑定
• serde / serde_json — JSON 序列化