# @effing/serde 中文文档

规范地址：https://npmcn.com/package/%40effing/serde/

版本：0\.48\.0
npm 元数据更新时间：2026-11-12T10:24:09.727Z
中文译文更新时间：2026-11-14T06:43:29.107Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40effing/serde
原文对照：https://npmcn.com/package/%40effing/serde/?lang=original
项目主页：https://github.com/builtbyfew/effing#readme
源码仓库：https://github.com/builtbyfew/effing

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：17.1 kB，6 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-01-20T18:56:27.078Z
- 最新版本发布：2026-11-12T10:24:09.286Z
- 近 30 天下载量：2223（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：119（近 12 个月 119 个）

## 中文简介

URL 安全序列化,并带有压缩和 HMAC 签名

## 安装

```sh
npm install @effing/serde
```

也可以使用：`pnpm add @effing/serde`、`yarn add @effing/serde`、`bun add @effing/serde`

## README

# @effing/serde (英语)

**URL-安全序列化,带有压缩和HMAC签名.**

> 部分 [**财源**](https://npmcn.com/package/README.md) 家庭——用TypeScript制作节目视频.

以自动压缩和加密签名的方式将JSON数据序列化为URL安全字符串. 与 Python 兼容 [危险](https://itsdangerous.palletsprojects.com/)。 。 。 .

## 安装

```bash
npm install @effing/serde
```

## 快速启动

```typescript
import { serialize, deserialize } from "@effing/serde";

const secret = process.env.SECRET_KEY!;
const data = { userId: 123, action: "view" };

// Signed (and sometimes compressed) URL segment
const segment = await serialize(data, secret);

// Verify signature (and decompress if needed)
const restored = await deserialize<typeof data>(segment, secret);
```

## 概念

### URL-安全基础64

标准基数64的使用 `+` 财务报告和审定财务报表 `/` 在 URL 有特殊含义。 此软件包使用 URL- safe Base64 :

-   `+` → `-`
-   `/` → `_`
-   无粘贴( N)`=`(中文(简体) )

### 签名序列化

序列化与 HMAC 签名( 默认 ): `sha1`),因此结果可以安全地被用在URL中而无需被篡改:

```typescript
// Server: create signed URL segment
const segment = await serialize(data, secret);

// Client: passes segment in URL
// Server: verify and deserialize
const data = await deserialize(segment, secret);
// Throws if signature is invalid.
```

### 压缩

有效载荷在节省空间时被gzip压缩. 压缩后的有效载荷有前缀 `"."` (比对) `itsdangerous`) (中文(简体) ).

## API 概览

#### `serialize(obj, secretKey, options?)`

将一个值序列化为 URL 安全字符串 .

```typescript
function serialize(
  obj: object,
  secretKey: string,
  options?: {
    /** Salt for key derivation (default: "itsdangerous") */
    salt?: string;
    /** Hash algorithm for HMAC (default: "sha1") */
    algorithm?: string;
  },
): Promise<string>;
```

#### `deserialize(segment, secretKey, options?)`

将 URL 段切回一个值 .

```typescript
function deserialize<T = Record<string, unknown>>(
  segment: string,
  secretKey: string,
  options?: {
    /** Salt for key derivation (default: "itsdangerous") */
    salt?: string;
    /** Hash algorithm for HMAC (default: "sha1") */
    algorithm?: string;
    /** Convert snake_case keys to camelCase (default: true) */
    convertKeysToCamel?: boolean;
  },
): Promise<T>;
```

**掷出 :**

-   `Error` - 如果签名验证失败

## 实例

### 在 URL 中传递道具

```typescript
import { serialize, deserialize } from "@effing/serde";

// Create URL with serialized props
const secret = process.env.SECRET_KEY!;
const props = { imageUrl: "https://example.com/image.png", duration: 5 };
const segment = await serialize(props, secret);
const url = `/render/${segment}`;

// In route handler
async function loader({ params }) {
  const props = await deserialize(params.segment, secret);
  // props = { imageUrl: "https://example.com/image.png", duration: 5 }
}
```

> \[注\] 这个 `convertKeysToCamel` 淡化选项(即 `true` 当 URL 在 Python (具有危险性) 中被构建,然后被 Effing 所消耗时,则有用 。 Python 一般使用 `snake_case` 键,而 TypeScript 偏好 `camelCase`。转换是递归性的——嵌入式物体内部的密钥和一系列物体也被转换.

### 安全键

```typescript
const SECRET = process.env.TOKEN_SECRET!;

// Create signed token
async function createToken(userId: number, expiresAt: number) {
  return serialize({ userId, expiresAt }, SECRET);
}

// Verify token
async function verifyToken(token: string) {
  try {
    const { userId, expiresAt } = await deserialize(token, SECRET);
    if (Date.now() > expiresAt) throw new Error("Token expired");
    return userId;
  } catch (e) {
    throw new Error("Invalid token");
  }
}
```

## 常见问题

### @effing/serde 是什么？

URL 安全序列化,并带有压缩和 HMAC 签名

### 如何安装 @effing/serde？

在项目目录运行 npm install @effing/serde，或使用 pnpm add / yarn add / bun add。

### @effing/serde 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @effing/serde 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @effing/serde 可以商用吗？

@effing/serde 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @effing/serde 的下载量有多少？

根据 npm 官方下载统计，@effing/serde 在 2026/10/13 – 2026/11/11 这 30 天内被下载 2,223 次，日均约 74 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @effing/serde 还在维护吗？

最新版本 0\.48\.0 发布于 2026/11/12（1 天前）；至今共发布 119 个版本，其中过去 12 个月发布了 119 个；首次发布于 2026/01/21。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。