更新记录

1.0.0(2026-11-15)

  • 新增 validate:Schema 参数校验,支持 required / type / enum / pattern / min / max / default / trim / custom,并拒绝 __proto__ 等危险键。
  • 新增 createRateLimiter:固定窗口限流,支持注入 store 与时钟。
  • 新增 sign / verifySign:HMAC-SHA256、稳定序列化、常量时间比较、时间戳偏移、nonce 防重放。
  • 新增 createIdempotency:pending / done 两态幂等控制。
  • 新增 redact:敏感键与敏感值脱敏,防循环引用与深度爆炸。
  • 新增 ok / fail / clientInfo / handle:统一返回体与一站式管线。
  • 新增 selfTest:34 项内置自检,云函数 action: 'selftest' 可一键复跑。
  • 提供阿里云、腾讯云两套 uniCloud-* 云函数目录。
  • 提供本地一键验证器(源码目录内),34/34 + 10/10 全通过。
  • 已在 readme.md 第 8 节如实列出内存 store 的分布式局限、验签默认关闭、加密运行时未真机验证等已知限制。

平台兼容性

云端兼容性

支付宝云 腾讯云 阿里云
× √ √

CloudShield · uniCloud 云函数请求防护模板

一句话:把每个 uniCloud 项目都要重写一遍的「参数校验 + 限流 + 验签 + 幂等 + 脱敏 + 统一返回」,收成一个零依赖、可复跑自检的云函数模板。

插件 ID:guardkit-cloudshield | 分类:uniCloud / 云函数模板 | 版本:1.0.0 | 作者:赛博麻薯


1. 它解决什么问题

写 uniCloud 云函数时,下面这些代码几乎每个项目都要重写一次,而且很容易写漏:

痛点 常见后果
参数没校验 / 校验散落在业务里 脏数据入库、类型错误 500、__proto__ 原型污染
没有限流 被刷接口、云函数并发与调用次数白白烧钱
签名校验各写各的 拼接规则不一致、时间戳没过期、nonce 可重放
重复提交没拦 重复下单、重复扣款
console.log(event) 直接打日志 手机号、token、密码明文进日志
每个云函数返回结构不同 前端要写 N 套错误处理

CloudShield 把这些做成一个纯 JS 核心 + 一个可改的云函数入口模板,全部在本地进程内完成,不联网、不写数据库、不引第三方 npm 包。


2. 功能清单

# 能力 说明
1 validate 参数校验 required / type(string·number·integer·boolean·array·object·any)/ enum / pattern / min·max / default / trim / custom;主动拒绝 __proto__ constructor prototype 键
2 createRateLimiter 限流 固定窗口算法,可注入 store、可注入时钟,返回 remaining / resetAt / retryAfterMs
3 sign / verifySign HMAC-SHA256,键名升序稳定序列化(嵌套对象也稳定),常量时间比较,秒级/毫秒级时间戳兼容,最大偏移可配,nonce 一次性防重放
4 createIdempotency 幂等 pending / done 两态,重复提交直接返回首次结果
5 redact 日志脱敏 敏感键整键打码;值内手机号 / 身份证 / 银行卡 / token=xxx 等片段打码;循环引用与深度截断保护
6 ok / fail 统一返回 {code, message, data, ts, meta/extra},异常不向客户端泄漏堆栈
7 handle 一站式管线 验签 → 校验 → 限流 → 幂等 → 业务 handler → 统一包装 → 异常兜底
8 selfTest 34 项内置自检 部署后调一次云函数即可复跑,无需装任何依赖

顺序说明(重要):验签在参数校验之前。因为 schema 会注入 default、执行 trim,若先校验再验签会改变签名原文导致验签永远失败。签名覆盖的是客户端原始参数。


3. 快速开始(3 步)

① 导入:把压缩包解压,将 uniCloud-aliyun(或 uniCloud-tcb)下的 cloudfunctions/guardkit-cloudshield 整个目录,拷到你的 uniCloud 项目对应目录下。

② 上传部署:HBuilderX 中右键该云函数目录 →「上传部署」。无需 npm install,dependencies 为空。

③ 调用:

const res = await uniCloud.callFunction({
  name: 'guardkit-cloudshield',
  data: { action: 'echo', text: 'hello', page: 1 }
});
// res.result = { code: 0, message: 'ok', data: { echo: 'hello', page: 1, clientIp: '...' }, ts: ..., meta: {} }

跑一次自检:

const res = await uniCloud.callFunction({ name: 'guardkit-cloudshield', data: { action: 'selftest' } });
// res.result.data.allPass === true,passed/total = 34/34

⚠️ action: 'selftest' 是给开发者验收用的分支,生产环境请移除或加管理员鉴权。


4. 改成你的业务(只改 index.js 的 ① 区)

const schema = {
  orderId:  { type: 'string',  required: true, min: 6, max: 32 },
  amount:   { type: 'number',  required: true, min: 0.01, max: 99999 },
  channel:  { type: 'string',  required: true, enum: ['weixin', 'alipay'] },
  page:     { type: 'integer', default: 1 }
};

async function businessHandler(params, ctx) {
  // 走到这里时:参数已校验、已限流、已验签、已去重
  return await createOrder(params, ctx.client.ip);
}

const CONFIG = {
  schema, store, rateLimit: { max: 20, windowMs: 60000 },
  idempotency: { ttlMs: 300000, keyOf: p => p.orderId },
  handler: businessHandler
};

handler(params, ctx) 的 ctx 含 client(ip / userAgent / platform / requestId / appId / spaceId)、event、context、stage。


5. 签名规则(要启用才生效)

默认不启用 —— 只有当云函数环境变量 GUARDKIT_SECRET 配置了值时,index.js 才会给 CONFIG 挂上 sign。 没配就是没有验签保护,请务必确认。

规则:

  1. 取除 sign / signature 外所有非 null、非 undefined 参数;
  2. 按键名升序排列,拼成 k=v&k2=v2;对象值按键名升序做稳定 JSON 序列化,布尔值转成 true/false;
  3. 以 GUARDKIT_SECRET 为密钥做 HMAC-SHA256,取 hex 小写 作为 sign;
  4. 额外必带 timestamp(秒级或毫秒级均可,默认允许 ±5 分钟)与 nonce(一次性随机串);
  5. 服务端常量时间比较签名,再用 nonceStore 拒绝重放。

Node 端生成签名:

const crypto = require('crypto');
function canonical(p) {
  return Object.keys(p).filter(k => k !== 'sign' && p[k] != null).sort()
    .map(k => k + '=' + (p[k] && typeof p[k] === 'object'
      ? JSON.stringify(p[k], Object.keys(p[k]).sort())
      : String(p[k]))).join('&');
}
const p = { action: 'echo', text: 'hi', timestamp: Math.floor(Date.now() / 1000), nonce: crypto.randomUUID() };
p.sign = crypto.createHmac('sha256', SECRET).update(canonical(p)).digest('hex');

前端(浏览器 / 小程序)请用 Web Crypto crypto.subtle 或后端下发签名,不要把密钥写进客户端代码。更完整的示例见 example/README.md。


6. 错误码

code 常量 含义
0 OK 成功
40001 PARAM_INVALID 参数校验未通过,extra.errors 含逐字段原因
40101 SIGN_INVALID 签名缺失 / 不匹配 / 缺时间戳 / 缺 nonce
40102 SIGN_EXPIRED 时间戳超出允许偏移
40103 REPLAY nonce 已使用(重放)
42901 RATE_LIMITED 触发限流,extra.retryAfterMs 给出重试等待
40901 DUPLICATE 幂等键处理中,重复提交
50001 INTERNAL 业务异常兜底,不向客户端返回错误堆栈

7. API 速查

方法 签名 返回
validate(params, schema) schema 为 {字段: 规则} {ok, errors, value}
createMemoryStore() — {get,set,del,size,clear}
createRateLimiter(store, opts) opts 可含 prefix / clock {limit(key, rule), reset(key)}
sign(params, secret) — hex 字符串
verifySign(params, secret, opts) opts 可含 maxSkewMs / nonceStore / clock / requireTimestamp {ok, code, reason}
createIdempotency(store, opts) — {check, complete, release}
redact(value, opts) opts 可含 mask / maxDepth / sensitiveKeys / keyPattern 脱敏副本
clientInfo(event, context) — ip / userAgent / platform / requestId 等
ok(data, meta) / fail(code, msg, extra) — 统一返回体
handle(event, config) 见第 4 节 Promise<统一返回体>
selfTest() — {total, passed, failed, allPass, cases}

keyOf 的签名是 (params, clientInfo) —— 第二个参数是 clientInfo 对象本身(直接用 .ip),不是 {client} 包装。


8. ⚠️ 生产环境必读(如实写清楚,别踩坑)

  1. 内置内存 store 不是分布式限流。它只在单个云函数实例存活期间有效:冷启动会清空,多实例之间不共享。用于本地验收、单实例低并发足够;生产多实例必须注入共享 store(Redis / 云数据库),且 get + set 要原子(用 INCR + EXPIRE 或等价实现),否则并发下会超额放行。
  2. 固定窗口有边界突刺。例如 60 次/分钟,在窗口交界处 1 秒内可能放行 120 次。需要更平滑请自行替换为滑动窗口/令牌桶(store 接口不变)。
  3. 未配置 GUARDKIT_SECRET = 不验签。这是模板为了避免「配了签名却因缺密钥全部 401」而做的显式选择,不是安全防护默认开启。
  4. selftest 分支是公开入口(只要能调云函数就能调),生产请移除或加鉴权。
  5. 日志脱敏是尽力而为:内置规则覆盖常见敏感键与手机号/身份证/银行卡/k=v 密钥片段,但不能保证覆盖你业务里自定义的敏感字段。请用 opts.sensitiveKeys / opts.keyPattern 补充,或干脆不要打印原始 event。
  6. 加密后的运行时未在本插件内做真机验证。插件作者只在本地 Node 环境跑通全部逻辑,未在真实 uniCloud 服务空间部署加密版本;购买前建议先用「试用」在你自己的服务空间跑一次 selftest。

9. 目录结构

guardkit-cloudshield/
├── package.json                 # 插件配置(含 dcloudext.sale / uni_modules.encrypt)
├── readme.md                    # 本文档
├── changelog.md
├── .npmignore
├── example/
│   └── README.md                # 客户端签名与调用示例
├── uniCloud-aliyun/
│   └── cloudfunctions/
│       └── guardkit-cloudshield/
│           ├── index.js         # 云函数入口(模板,改这里)
│           ├── package.json
│           └── common/
│               └── guardkit-core.js   # 核心逻辑(零依赖)
└── uniCloud-tcb/
    └── cloudfunctions/
        └── guardkit-cloudshield/      # 同上,腾讯云目录

压缩包第一层直接是 package.json + uniCloud-* 目录(没有顶层插件 ID 目录),这是 DCloud 网页端发布的格式要求;若要在 HBuilderX 里以 uni_modules 方式导入,请使用配套的 guardkit-cloudshield-unimodules.zip(带顶层 ID 目录、uniCloud 不带厂商后缀)。


10. 已验证证据

项 结果
语法检查 node --check 对 index.js / guardkit-core.js / 验证器全部通过
内置自检 34 / 34 通过
端到端管线 10 / 10 通过(正常、缺参、限流、正签、篡改、幂等、异常脱敏、无网络调用静态扫描)
静态扫描 剥离字符串字面量后,核心代码无 fetch / XMLHttpRequest / http(s) require / uniCloud.database 调用
运行环境 Node.js v22.22.2(本地);云函数目标 Node 18+ 语法兼容(未用 20+ 独有 API)
未验证 真实 uniCloud 服务空间部署、DCloud 加密后的运行时、多实例并发限流

作者没有把「本地跑通」写成「云端验证通过」。第 8 节第 6 条与本节「未验证」是同一件事,请按自己的服务空间复验。


11. 授权

本插件为付费插件,许可协议以 DCloud 插件市场标准协议为准,插件包内不附带自行拟定的 license 文件。

  • 普通授权版:获得加密后的云函数,绑定购买时的服务空间。
  • 源码授权版:获得完整源码,可自行二开。

结算遵循 DCloud 插件市场规则(平台抽成、月度账单、满 ¥100 可提现)。作者不提供私有部署支持、不承诺任何成交量或收益。


12. 更新日志

见 changelog.md。当前 1.0.0 为首个版本。

13. 反馈

插件页评论区,或 DCloud 站内私信。作者会优先修复可复现的 bug;请附上 selftest 的输出与你的 Node / HBuilderX 版本。

隐私、权限声明

1. 本插件需要申请的系统权限列表:

无

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

插件不采集任何数据。全部逻辑在本云函数进程内完成,不发起网络请求、不上传参数、不写入数据库;内置内存存储仅用于限流计数与 nonce 去重,进程结束即消失。示例 logger 仅向云函数控制台输出经脱敏处理的内容。

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

无

暂无用户评论。