# @hadoku/worker-utils 中文文档

规范地址：https://npmcn.com/package/%40hadoku/worker-utils/

版本：1\.7\.24
npm 元数据更新时间：2026-11-15T15:34:43.982Z
中文译文更新时间：2026-11-17T06:59:17.347Z
软件包许可：ISC

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

原始 npm 页面：https://www.npmjs.com/package/%40hadoku/worker-utils
原文对照：https://npmcn.com/package/%40hadoku/worker-utils/?lang=original
项目主页：https://github.com/WolffM/hadoku_site#readme
源码仓库：https://github.com/WolffM/hadoku_site

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

- 包体积（解压后）：224 kB，35 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：2 个
- peer 依赖：hono ^4\.11\.4
- 首次发布：2026-10-31T04:03:06.691Z
- 最新版本发布：2026-11-15T15:34:43.786Z
- 近 30 天下载量：5393（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：28（近 12 个月 28 个）

## 中文简介

Cloudflare工人的共享公用事业

## 安装

```sh
npm install @hadoku/worker-utils
```

也可以使用：`pnpm add @hadoku/worker-utils`、`yarn add @hadoku/worker-utils`、`bun add @hadoku/worker-utils`

## README

# 工人公用事业 - 快速参考

为Cloudflare工人共享公用事业。 从生产工人那里提取的通用的、可重复使用的模式.

**导入 :** `import { ... } from '@wolffm/worker-utils'`

* * *

## 文件

```text
workers/shared/
├── types.ts        # TypeScript type definitions
├── auth.ts         # Authentication middleware
├── context.ts      # Request context extraction
├── validation.ts   # Input validation
├── cors.ts         # CORS configuration
├── logging.ts      # Structured logging
├── masking.ts      # Data masking for safe logging
├── responses.ts    # HTTP response helpers
└── index.ts        # Barrel export
```

* * *

## auth.ts (帮助)

**边缘验证认证 :**

工人不解决钥匙。 边缘路由器将调用者与其 KV 相对抗 密钥登记簿,然后是邮票 `X-Hadoku-Tier` 与一个 `X-Edge-Auth` 来源 页眉; `createEdgeAuth` 校对出处 `EDGE_AUTH_SECRET` 在信任等级之前 `public` 当它不验证. 分级优先级 : `admin > service > friend > public`。 。 。 . `service` 用于 工人与工人之间的交通.

> **在1.3.0中删除:** `createHadokuAuth`, (中文(简体) ), `HadokuAuthEnv`, (中文(简体) ), `parseKeysFromEnv`, (中文(简体) ), `parseKeysWithNames`, (中文(简体) ), `validateKeyAndGetType`他们读了 `ADMIN_KEYS` 编号 : `SERVICE_KEYS` 编号 : `FRIEND_KEYS` 已退役的env阵列 2026-07-26 - 所以他们已经停止认证任何人. `createEdgeAuth` 是一个 滴入( 相同的上下文形状, 相同) `extend` 选项).

```typescript
// Standard hadoku ecosystem auth:
import { createEdgeAuth } from '@wolffm/worker-utils';

app.use('*', createEdgeAuth());
//          ↑ verifies X-Edge-Auth, then trusts the edge-stamped X-Hadoku-Tier

// Generic helper (single-key-per-tier case only):
app.use(
  '*',
  createKeyAuth((env) => ({
    [env.SOME_SINGLE_KEY]: 'admin',
  }))
);
```

**函数 :**

-   `createKeyAuth(keyMap, options?)` - 简单的密钥 — 用户类型映射
-   `createAuthMiddleware(config)` - 自定义认证逻辑
-   `validateKeyAndGetType(key, adminKeys, friendKeys, serviceKeys?)` - 验证密钥返回用户Type( 4- arg 形式) `'service'` 等级)
-   `parseKeysFromEnv(jsonString)` - 解析自定义的密钥配置
-   `getAuthContext(c)` - 从上下文获取认证
-   `requireMinTier('friend')` - 在MINIMUM一级打开一条路线(`public < member < friend < service < wife < admin`);每个较高级别按级别录取
-   `tierAtLeast(auth, 'admin')` - 对一个已经解开的认证上下文进行相同的级别检查,用于手动分支。 永远不要比较 `auth.userType` 到字符串
-   `TIER_RANK` 编号 : `Tier` - 由边门和工人门共用的军衔表和等级联盟
-   ~`requireUserType([...])`~ - 说吧 **删除** 2026-07-25. (中文(简体) ). 翻译为 `requireMinTier(<lowest tier in the list>)`

**添加到上下文中 :** `c.get('authContext')` → `{ userType, isAdmin, isFriend, isPublic }`

* * *

## 口罩( t)

**用于记录的遮罩敏感数据 :**

```typescript
logRequest('POST', '/session/create', {
  sessionId: maskSessionId(sessionId), // "1a2b3c4d5e6f7g8h"
  key: maskKey(authKey), // "admin-secre" (50%)
});
```

**函数 :**

-   `maskKey(key, percentage?)` - 遮盖键(默认显示前50%,无后缀)
-   `maskSessionId(id)` - 遮罩会话ID(显示前16个字符,无后缀)
-   `maskEmail(email)` - 遮罩电子邮件(显示第一个字符+域名)
-   `redactFields(obj, fields)` - 从物体中调整敏感字段

**常数 :**

-   `MASKING.KEY_PERCENTAGE` - 要显示的密钥百分比(0.5=50%)
-   `MASKING.KEY_MIN_LENGTH` - 显示最小字符(4)
-   `MASKING.SESSION_ID_PREFIX_LENGTH` - 默认会话 ID 前缀( 16)
-   `SENSITIVE_FIELDS` - 常见的敏感字段名称

**实例:**

```typescript
maskKey('admin-secret-key-123'); // "admin-secre"
maskSessionId('1a2b3c4d5e6f7g8h9i0j'); // "1a2b3c4d5e6f7g8h"
maskEmail('john@example.com'); // "j***@example.com"

redactFields({ username: 'john', password: 'secret' }, ['password']);
// { username: 'john', password: '[REDACTED]' }
```

* * *

**提取常见字段 :**

```typescript
const { userId, sessionId } = extractUserContext(c);
const boardId = extractField(c, ['query:boardId', 'body:boardId'], 'main');
```

**函数 :**

-   `extractUserContext(c)` - 获取用户编号, 会话编号
-   `extractField(c, sources, default?, transform?)` - 多个来源的单一领域
-   `extractContext(c, config)` - 一次多块地
-   `extractPagination(c)` - 获取页面,限制,平移
-   `extractSorting(c)` - 排序By,排序命令
-   `getRequestMetadata(c)` - 获取IP,用户代理,国家等.

**资料来源格式 :** `'header:X-User-Id'`, (中文(简体) ), `'query:boardId'`, (中文(简体) ), `'body:title'`

* * *

## 校验.ts

**验证请求数据 :**

```typescript
const validation = validateFields(body, [
  { field: 'id', required: true, type: 'string' },
  { field: 'title', required: true, minLength: 1, maxLength: 200 },
]);
if (!validation.valid) return validationError(c, validation.errors);
```

**函数 :**

-   `validateFields(data, rules)` - 全面验证规则
-   `requireFields(data, ['id', 'title'])` - 所需的快速检查
-   `validateBody(rules)` - 自动验证的中间软件
-   `createValidator(rules)` - 可重复使用的验证器功能

**共同规则 :**

-   `CommonRules.id()` - UUID 验证
-   `CommonRules.title({ maxLength })` - 1 -200个字符
-   `CommonRules.email(required)` - 电子邮件模式
-   `CommonRules.url(required)` - URL图案
-   `CommonRules.enum('status', ['active', 'inactive'])` - Enum验证
-   `CommonRules.array('tags', options)` - 阵列验证
-   `CommonRules.number('age', { min, max, integer })` - 数量限制

* * *

## 皮层

**标准 Hadoku CORS :**

```typescript
app.use('*', createHadokuCors());
```

**函数 :**

-   `createHadokuCors(additionalOrigins?)` - Hadoku 默认 + 自定义
-   `createCorsMiddleware(config)` - 完全定制配置
-   `matchOrigin(origin, pattern)` - 通关卡匹配

**预设 :**

-   `CORSPresets.hadoku` - 生产出出自哈多库
-   `CORSPresets.development` - 包括当地东道主
-   `CORSPresets.production(origins)` - 定制生产
-   `CORSPresets.publicApi` - 公共API(所有来源)

* * *

## 记录.ts

**日志请求和错误 :**

```typescript
logRequest('GET', '/api/items', { userId, boardId });
logError('POST', '/api/items', 'Validation failed', { errors });
```

**函数 :**

-   `logRequest(method, path, context?, level?)` - 日志 HTTP 请求
-   `logError(method, path, error, context?)` - 日志错误
-   `createLogger(config)` - 自定义日志实例
-   `createRequestLogger(method, path, baseContext)` - 请求扫描器
-   `startTimer()` - 业绩时间(`timer.end(message, context)`(中文(简体) )
-   `redactFields(obj, fields)` - 删除敏感数据

**常数 :**

-   `SENSITIVE_FIELDS` - 常见的敏感字段名称(密码、 apiKey、 符号等)

* * *

## 回应.ts

**标准 HTTP 响应 :**

```typescript
return ok(c, { items });
return created(c, { item });
return badRequest(c, 'Missing field: id');
return notFound(c, 'Task');
```

**成功 :**

-   `ok(c, data, message?)` - 200块
-   `created(c, data, message?)` - 201号
-   `noContent(c)` - 204号

**错误 :**

-   `badRequest(c, message, details?)` - 400岁
-   `unauthorized(c, message?)` - 401号
-   `forbidden(c, message?)` - 403岁
-   `notFound(c, resource?)` - 404岁
-   `conflict(c, message, details?)` - 409号
-   `serverError(c, message, details?)` - 500块
-   `validationError(c, errors)` - 400个附有验证细节

**卫生和错误处理 :**

-   `healthCheck(c, service, checks?)` - 健康检查对策
-   `createHealthCheckHandler(service, config)` - 健康检查员工厂
-   `handleError(c, error, message)` - 通用错误处理器
-   `withErrorHandling(handler)` - 同步错误包装

* * *

## 类型.ts

**导入类型 :**

```typescript
import type {
  UserType, // 'admin' | 'service' | 'friend' | 'public'
  AuthContext, // { userType, userId?, isAdmin, isFriend, isPublic }
  ValidationRule, // { field, required?, type?, minLength?, ... }
  ValidationResult, // { valid, errors }
  LoggerConfig, // { prefix?, minLevel?, includeTimestamp? }
  CORSConfig, // { origins, methods, allowedHeaders, ... }
} from '@wolffm/worker-utils';
```

* * *

## 常见模式

### 最小工人

```typescript
import { Hono } from 'hono';
import {
  createKeyAuth,
  createHadokuCors,
  extractUserContext,
  ok,
} from '@wolffm/worker-utils';

const app = new Hono();

app.use('*', createHadokuCors());
app.use('*', createEdgeAuth());
//             ↑ verifies X-Edge-Auth, trusts the edge-stamped tier

app.get('/api/items', async (c) => {
  const { userId } = extractUserContext(c);
  const items = await getItems(userId);
  return ok(c, { items });
});

export default app;
```

### 有验证

```typescript
app.post('/api/items', async (c) => {
  const body = await c.req.json();

  const validation = validateFields(body, [
    CommonRules.id(),
    CommonRules.title({ maxLength: 200 }),
  ]);

  if (!validation.valid) {
    return validationError(c, validation.errors);
  }

  const item = await createItem(body);
  return created(c, { item });
});
```

### 正在登录

```typescript
app.post('/api/items', async (c) => {
  const { userId } = extractUserContext(c);
  logRequest('POST', '/api/items', { userId });

  try {
    const item = await createItem(body);
    return created(c, { item });
  } catch (error) {
    logError('POST', '/api/items', error.message, { userId });
    return serverError(c, 'Failed to create item');
  }
});
```

* * *

## 另见

-   **[工人(md)](https://npmcn.com/package/%40hadoku/WORKERS.md)** - 工人指数和设置指南
-   **[文件/儿童应用程序/NEW CHILD APP CHECKLIST.md](https://npmcn.com/package/docs/child-apps/NEW_CHILD_APP_CHECKLIST.md)** - 后端工人设置(见"可选:后端API"部分)
-   **[一般事务人员(其他职等)](https://npmcn.com/package/AGENTS.md)** - 工人调试和常见模式

## 常见问题

### @hadoku/worker-utils 是什么？

Cloudflare工人的共享公用事业

### 如何安装 @hadoku/worker-utils？

在项目目录运行 npm install @hadoku/worker-utils，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：hono（^4\.11\.4）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @hadoku/worker-utils 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/hadoku\_\_worker-utils 是否存在。

### @hadoku/worker-utils 支持 ESM 还是 CommonJS？

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

### @hadoku/worker-utils 可以商用吗？

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

### @hadoku/worker-utils 的下载量有多少？

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

### @hadoku/worker-utils 还在维护吗？

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

