modify: 说明文档

README.md

@@ -1,29 +1,93 @@
 # chongming-jwt
 
-基于 Rust 和 PyO3 实现的 JWT 库，性能优越，支持 HS256/HS384/HS512/RS256/RS384/RS512。
+基于 **Rust + PyO3** 实现的 JWT 库，性能远超纯 Python 实现，支持多种签名算法。所有编解码操作在 Rust 层执行，不阻塞 Python 事件循环。
+
+---
 
 ## 安装
 
-通过 uv 自动编译（需 Rust 工具链）。
+```bash
+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` 类
 
 ```python
 from chongming_jwt import JWT
 
-jwt = JWT("your-secret-key", "HS256")
-
-# 编码
-token = jwt.encode('{"sub": "user"}', expires_in_seconds=3600)
-
-# 解码
-payload = jwt.decode(token)
-
-# 验证
-is_valid = jwt.validate(token)
+jwt = JWT(
+    secret="your-secret-key-change-in-production",
+    algorithm="HS256"
+)
 ```
 
-## 注意
+| 参数        | 类型  | 默认值    | 说明                             |
+| ----------- | ----- | --------- | -------------------------------- |
+| `secret`    | `str` | —         | 签名密钥（HS256 建议 ≥ 32 字节） |
+| `algorithm` | `str` | `"HS256"` | 签名算法                         |
 
-- 载荷必须包含 `sub` 字段
-- 密钥建议至少 32 字节（HS256）
+### 方法
+
+```python
+# 编码
+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` 抛出异常
+
+---
+
+## 手动编译
+
+```bash
+uv run maturin develop --release -m utils/jwt/Cargo.toml
+```
+
+---
+
+## 依赖 (Rust)
+
+- `jsonwebtoken` — JWT 编解码
+- `pyo3` — Python 绑定
+- `serde` / `serde_json` — JSON 序列化