更新记录

1.0.0(2026-11-15)

  • 新增安全查询编译:字段/操作符双白名单,编译期拒绝 NoSQL 注入与原型污染,支持 12 种操作符
  • 新增分页、排序、字段投影,pageSize 上限 200
  • 新增乐观锁(version)、软删除与恢复、批量更新/批量删除(1..100 条)
  • 新增操作审计:只记录 before/after 差异字段,且经过脱敏
  • 新增 CSV 导出:UTF-8 BOM、公式注入防护、超 200 行直接拒绝不静默截断
  • 新增日志脱敏:敏感键、手机号、身份证、token=xxx 片段,防循环引用
  • 新增统一错误码与异常兜底,异常不向客户端泄漏堆栈
  • 新增 45 项内置自检,云函数 action:'selftest' 可一键复跑
  • 提供阿里云、腾讯云两套 uniCloud 云函数目录,纯 JS 零第三方依赖
  • 已在说明文档如实登记:内存适配器仅供验收、异步数据库需改造 await、默认不鉴权、加密运行时未真机验证

平台兼容性

云端兼容性

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

DataKit · uniCloud 通用后台数据 API 模板

一套云函数侧的后台数据接口,不是单个工具函数。 每个管理后台都要重写一遍的那堆东西 —— 分页、筛选、排序、字段投影、乐观锁、软删除、批量操作、操作审计、CSV 导出、脱敏、统一错误码 —— 这里已经写成一条可替换适配器的管线。

  • 插件 ID:datakit-crud | 分类:uniCloud / 云函数模板 | 版本 1.0.0
  • 纯 JS、零第三方依赖;同时提供 uniCloud-aliyun 与 uniCloud-tcb 两套目录
  • 内置自检 45/45,端到端管线测试 24/24,action:'selftest' 可一键复跑
  • 核心零网络调用、零数据库调用;持久化由你注入适配器

1. 它解决什么

写 uniCloud 后台列表接口时,下面这些坑几乎每次都会踩:

坑 后果
把前端传来的 where 直接丢给数据库 NoSQL 注入、$where 任意表达式
字段名、排序字段不做白名单 越权读敏感列、按未索引字段排序
忘了挡 __proto__ / constructor 原型污染
直接 update 覆盖整条记录 并发下后写覆盖先写,静默丢数据
delete 物理删除 误删不可恢复
console.log(doc) 手机号、token 明文进日志
CSV 直接拼字符串 =1+1 变成 Excel 公式(CSV 注入)
导出不限制行数 大表把云函数内存打爆

DataKit 把这些收成一条固定管线:

鉴权钩子 → 参数校验 → 安全查询编译 → 适配器执行 → 审计 diff → 统一返回 → 异常兜底

2. 快速开始(3 步)

  1. 解压后把 uniCloud-aliyun(或 uniCloud-tcb)下 cloudfunctions/datakit-crud 整个目录拷进你的 uniCloud 项目。
  2. HBuilderX 右键该云函数目录 → 上传部署(无需 npm install,dependencies 为空)。
  3. 客户端调用:
const res = await uniCloud.callFunction({
  name: 'datakit-crud',
  data: {
    action: 'list',
    where: { status: { $eq: 'on' }, score: { $gte: 60 } },
    sortBy: 'score', sortOrder: 'desc',
    page: 1, pageSize: 20,
    fields: ['_id', 'title', 'status', 'score']
  }
});
// res.result = { code:0, msg:'ok', data:{ list, total, page, pageSize, hasMore, pages }, meta:{...} }

跑自检:

await uniCloud.callFunction({ name: 'datakit-crud', data: { action: 'selftest' } });
// 返回 data.allPass === true / 45 项通过

⚠️ 默认适配器是内存适配器,只用于验收。不换真实适配器就部署到生产,冷启动会丢数据。见第 4 节。


3. 全部 action

action 主要参数 返回
list where / sortBy / sortOrder / page / pageSize / fields { list, total, page, pageSize, hasMore, pages }
get id 单条(已脱敏),不存在 40401
create doc 新记录(含 _id / version)
update id / patch / version(可选) 更新后记录;版本不符 40901
remove id / version(可选) 软删除,可 restore
restore id 恢复
batchUpdate ids[1..100] / patch { changed, failed }
batchRemove ids[1..100] { removed, failed }
export where / columns { csv, total, columns },超过 200 行直接拒绝,不静默截断
selftest — 45 项内置自检结果

查询条件(where)支持 12 个操作符,全部在编译期校验:

$eq $ne $gt $gte $lt $lte $in $nin $like $between $exists $isnull

where: {
  status: 'on',                       // 简写等价于 { $eq: 'on' }
  score: { $between: [60, 100] },
  title: { $like: 'report' },         // 大小写不敏感的包含匹配
  deletedAt: { $isnull: true }
}

字段名必须出现在 ALLOWED_FIELDS 白名单里,排序字段同样受限;pageSize 上限 200。 任何未知操作符、白名单外字段、原型链键都返回 40002,不会进入数据库层。

统一返回体:{ code, msg, data, meta },失败时带 extra.errors 或 extra.stage。 错误码:0 成功 / 40001 参数 / 40002 查询不安全 / 40301 无权限 / 40401 不存在 / 40901 版本冲突 / 50001 内部错误。 异常一律返回「服务内部错误」,不向客户端泄漏堆栈、适配器细节或数据库信息。


4. 生产环境必读:适配器契约

核心只依赖一个可替换的适配器对象。实现下面 9 个成员即可接真实 uniCloud.database():

成员 契约
name 字符串,出现在返回 meta.adapter
list() 未删除的全部文档数组
get(id) 单条;已删除返回 null
getRaw(id) 单条(含已删除,用于审计 before)
create(doc) 新增,返回含 _id / version 的文档
update(id, patch, ver) ver 不匹配返回 false;不存在返回 null
softRemove(id, ver) 同上
restore(id) 无可恢复返回 null
count() 未删除条数

改造位置只有 index.js 的 createAdapter(),核心不用动。

⚠️ 核心目前按同步方式调用适配器(为了能在本地 Node 一键自检)。 如果你接的是 async 的真实数据库,请把 handle() 的 execute 段改成 await,或让适配器方法返回已 resolve 的值再包装 —— 这一步没有在本插件里替你做完,属于你的业务改造。

⚠️ 乐观锁在真实数据库里必须是原子的(条件更新 where version = expected),否则并发下仍会丢写。模板里的内存实现只是演示语义。


5. 六条安全设计(都是可复跑验证过的,不是口号)

  1. 查询编译期校验:字段白名单 + 操作符白名单 + 拒绝 $where 等任意表达式,24 项端到端测试里有专门两条打注入。
  2. 原型污染防护:__proto__ / prototype / constructor 在 clone 之前就被拒绝,且 clone() 主动丢弃危险键。
  3. CSV 公式注入防护:= + - @ \t \r 开头的单元格前置单引号,另做逗号/引号/换行转义,输出带 UTF-8 BOM。
  4. 日志与返回脱敏:结构化敏感键整键打码,正文里的手机号 / 身份证 / token=xxx 片段另做模式脱敏;redact 有深度上限,循环引用不会打爆栈。
  5. 异常兜底:统一错误码,堆栈只进经脱敏的 logger,不回客户端。
  6. 审计只记 diff:before/after 变化字段才记录,且经过脱敏,不落敏感值原文。

6. 自检与验证边界

已验证(本机 Node v22) 结果
node --check × 3 个 JS 通过
内置 selfTest() 45 / 45
端到端 handle 管线 24 / 24(含注入、乐观锁、软删恢复、批量、导出超限、鉴权、审计、异常不泄漏)
静态扫描(剥离字符串与注释后) 核心无 fetch / XMLHttpRequest / http(s) require / uniCloud.database
zip 结构 / encrypt 路径 / CRC / sale 格式 构建器逐项断言

未验证,别当成已支持:

  • ❌ 未在真实 uniCloud 服务空间部署过(本机没有已绑定服务空间)。
  • ❌ 未验证 DCloud 服务端加密后的运行时行为:require('./common/datakit-core.js') 在加密版下能否正常加载,只有平台侧能确认。建议先用「导入插件并试用」在自己的空间跑一次 action:'selftest' 再决定购买。
  • ❌ 未验证真实异步数据库适配器(见第 4 节,需你改 await)。
  • ❌ 未验证多实例并发:内存适配器不共享,这是设计限制,不是 bug。
  • ❌ 未配置鉴权时默认不鉴权;action:'selftest' 是公开分支,生产应移除或加鉴权。

7. 定价与授权

档位 价格 交付
普通授权版 ¥9.90 加密后的云函数,绑定购买时的服务空间
源码授权版 ¥49.00 完整源码,可自行二开

定价依据来自 DCloud 未登录公开页的一手价格锚(2026-11-15 抓取):同类 vk-uni-pay 普通版 ¥8.89、统一支付业务模块 ¥88、阿里 OSS 上传 ¥1,168。 本插件是新作者、零评价、零下载的试水价,不是收益预期,也没有任何成交数据支撑。

许可协议:DCloud 插件市场标准协议(付费插件包内不放 license.md)。


8. 与同作者其它插件的关系

  • id=30740 guardkit-precheck:uni-app 项目提交前的离线配置预检(免费)。
  • id=30759 CloudShield:云函数请求入口的防护管线(校验 / 限流 / 验签 / 幂等 / 脱敏,¥19)。
  • 本插件 datakit-crud:请求进到业务数据层之后的一整套 CRUD API。

三者不重叠,可组合使用:CloudShield 管「谁能进来、进几次」,DataKit 管「进来之后怎么安全地读写数据」。 但请注意:组合使用也没有在真实项目里联调过,不要假设它们开箱即兼容。


9. 更新记录

1.0.0 首个版本。详见 changelog.md。

作者不承诺免费技术支持响应时间;提问请走插件页评论。 本文档刻意写出所有未验证项 —— 宁可少卖一份,也不想让你买回去才发现跑不起来。

隐私、权限声明

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

无

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

插件核心不采集、不上传任何数据;纯 JS 逻辑零网络调用、零数据库调用,全部运算在云函数进程内完成。内置的 createMemoryAdapter 仅用于本地验收与自检,进程结束即消失。买家按 readme 第 4 节接入自己的 uniCloud 服务空间后,数据只存放在买家自己的数据库中,插件作者无法访问。示例 logger 仅向云函数控制台输出经脱敏处理的内容。

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

无

暂无用户评论。