@hadoku/worker-utils

中文文档
1.7.24发布于 2026/11/15ISCES Module近 30 天下载 5393

Cloudflare工人的共享公用事业

中文使用文档
文档目录13 节
  1. 文件
  2. auth.ts (帮助)
  3. 口罩( t)
  4. 校验.ts
  5. 皮层
  6. 记录.ts
  7. 回应.ts
  8. 类型.ts
  9. 常见模式
  10. 最小工人
  11. 有验证
  12. 正在登录
  13. 另见

工人公用事业 - 快速参考

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

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


文件

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 选项).

// 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)

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

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 - 常见的敏感字段名称

实例:

maskKey('admin-secret-key-123'); // "admin-secre"
maskSessionId('1a2b3c4d5e6f7g8h9i0j'); // "1a2b3c4d5e6f7g8h"
maskEmail('[email protected]'); // "j***@example.com"

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

提取常见字段 :

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

验证请求数据 :

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 :

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

函数 :

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

预设 :

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

记录.ts

日志请求和错误 :

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 响应 :

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

导入类型 :

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';

常见模式

最小工人

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;

有验证

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 });
});

正在登录

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');
  }
});

另见

版本与发布记录

@hadoku/worker-utils 共发布 28 个版本,首次发布于 2026/10/31;过去 12 个月发布了 28 个版本。

版本发布日期距今
1.7.24latest2026/11/151 天前
1.7.232026/11/125 天前
1.7.222026/11/125 天前
1.7.212026/11/125 天前
1.7.202026/11/125 天前
1.7.192026/11/116 天前

关于 @hadoku/worker-utils 的常见问题

@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 和提交记录判断。