更新记录
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。
没配就是没有验签保护,请务必确认。
规则:
- 取除
sign/signature外所有非 null、非 undefined 参数; - 按键名升序排列,拼成
k=v&k2=v2;对象值按键名升序做稳定 JSON 序列化,布尔值转成true/false; - 以
GUARDKIT_SECRET为密钥做HMAC-SHA256,取 hex 小写 作为sign; - 额外必带
timestamp(秒级或毫秒级均可,默认允许 ±5 分钟)与nonce(一次性随机串); - 服务端常量时间比较签名,再用
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. ⚠️ 生产环境必读(如实写清楚,别踩坑)
- 内置内存 store 不是分布式限流。它只在单个云函数实例存活期间有效:冷启动会清空,多实例之间不共享。用于本地验收、单实例低并发足够;生产多实例必须注入共享 store(Redis / 云数据库),且
get + set要原子(用INCR+EXPIRE或等价实现),否则并发下会超额放行。 - 固定窗口有边界突刺。例如 60 次/分钟,在窗口交界处 1 秒内可能放行 120 次。需要更平滑请自行替换为滑动窗口/令牌桶(store 接口不变)。
- 未配置
GUARDKIT_SECRET= 不验签。这是模板为了避免「配了签名却因缺密钥全部 401」而做的显式选择,不是安全防护默认开启。 selftest分支是公开入口(只要能调云函数就能调),生产请移除或加鉴权。- 日志脱敏是尽力而为:内置规则覆盖常见敏感键与手机号/身份证/银行卡/
k=v密钥片段,但不能保证覆盖你业务里自定义的敏感字段。请用opts.sensitiveKeys/opts.keyPattern补充,或干脆不要打印原始event。 - 加密后的运行时未在本插件内做真机验证。插件作者只在本地 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 版本。

收藏人数:
购买源码授权版(
导入插件并试用
赞赏(0)
下载 1
赞赏 0
下载 35302
赞赏 159
赞赏
京公网安备:11010802035340号