Laf 云数据库新增数据完全指南add 单条/批量插入与 MongoDB 原生写法详解【免费下载链接】lafLaf is a vibrant cloud development platform that provides essential tools like cloud functions, databases, and storage solutions. It enables developers to quickly unleash their creativity and bring innovative ideas to life with ease.项目地址: https://gitcode.com/GitHub_Trending/la/laf本文聚焦 Laf 云开发平台中「向云数据库写入新数据」这一核心操作系统讲解cloud.database()提供的add()单条插入、{ multi: true }批量插入以及通过cloud.mongo.db使用 MongoDB 原生insertOne()/insertMany()的两种写法。读完本文你将掌握 Laf 云数据库新增数据的所有姿势理解两种写法在_id生成策略上的本质差异并能结合源码看清数据从云函数到 MongoDB 的完整调用链路。云数据库新增数据Schema Free 与两种写入方式Laf 的云数据库基于 MongoDB 构建向集合中新增数据正规术语为插入文档非常简单只需获取集合引用后调用add方法即可。Laf 云数据库是Schema Free无模式的这意味着不需要预先定义表结构你可以向任意集合中插入任意的字段和数据类型集合也会在首次写入时被自动创建。在 Laf 云函数中向数据库写入新数据存在两条路径写法入口_id生成策略适用场景数据库 API 写法cloud.database().collection(...).add(...)由 Laf 自动生成_id类型为string无法自定义云函数内常规写入受 Laf 权限策略policy管控MongoDB 原生写法cloud.mongo.db.collection(...).insertOne/insertMany(...)可自定义_id也可自动生成类型为 MongoDB 的ObjectId需要精细控制_id、或复用 MongoDB 原生能力时下面分别展开这两种写法。使用 add 插入单个文档向user集合中添加一条记录代码如下import cloud from lafjs/cloud const db cloud.database() export default async function (ctx: FunctionContext) { // 向 user 集合中添加一条记录 const res await db.collection(user).add({ name: jack }) console.log(res) }要点说明cloud.database()返回数据库引用dbdb.collection(user)获取集合引用add(data)完成插入add的数据参数是普通对象即可例如{ name: jack }无需任何表结构定义调用发生在async function中需用await等待写入完成。从源码看add方法定义在 packages/database-ql/src/collection.ts 中它实际委托给DocumentReference.create()add(data: object, options?: { multi: boolean }) { const docRef new DocumentReference(this._db, this._coll, undefined) return docRef.create(data, options) }而create()实现位于 packages/database-ql/src/document.ts它会对数据做以下处理空数据校验如果传入null、非对象或空对象会直接抛出data cannot be empty object异常数据序列化通过serialize(data)将数据中的特殊类型如地理位置Geo、日期、正则、ObjectId、二进制等转换为可传输的 EJSON 格式序列化实现见 packages/database-ql/src/serializer/datatype.ts发送请求以ActionType.add动作、{ collectionName, data, multi }参数发送到数据库代理database-proxy默认multi: false返回结果成功时返回{ id, insertedCount, requestId, ok: true }。add的返回结构AddRes定义在 packages/database-ql/src/result-types.ts其中id是本次插入文档的_idinsertedCount是实际插入的文档数量。使用 add 批量新增文档批量添加多条记录时只需在add的第二个参数中传入{ multi: true }const list [ { name: jack }, { name: rose } ] // 向 user 集合中加入多条记录 const res await db.collection(user).add(list, { multi: true }) console.log(res)批量插入的两个关键点第一个参数从单个对象变为对象数组数组中的每个元素将被插入为一条独立文档第二个参数{ multi: true }告知 Laf 执行批量插入multi默认值为false由 packages/database-ql/src/document.ts 中的options?.multi ?? false控制因此单条插入时可以不传该参数。从底层看数据库代理database-proxy在 packages/database-proxy/src/accessor/mongo.ts 中根据multi分支处理// multi 表示单条或多条添加 if (!multi) { data._id this.generateDocId() result await coll.insertOne(data) } else { data data instanceof Array ? data : [data] data.forEach((ele: any) (ele._id this.generateDocId())) result await coll.insertMany(data) }单条走insertOne批量走insertMany返回的_id集合会原样回传给云函数。add 的 id 生成机制自动生成 string 类型的 _id使用cloud.database()的add方法新增数据时无法自定义 id——所有新增的数据都会由 Laf 自动生成_id且生成的 id 类型为string。背后的实现在 packages/database-proxy/src/accessor/mongo.tsprotected generateDocId(): string { const id new ObjectId() return id.toHexString() }即每次插入前生成一个新的 MongoDBObjectId并将其toHexString()得到的24 位十六进制字符串作为文档的_id随后由database-ql通过res.data._id || res.data[this._db.primaryKey]提取并返回见 packages/database-ql/src/document.ts。Db实例的主键默认为_id该配置定义在 packages/database-ql/src/index.ts。MongoDB 原生写法insertOne 与 insertMany如果你需要自定义_id或希望完全使用 MongoDB 原生能力可以直接通过cloud.mongo.db访问底层的 MongoDB 数据库实例。cloud.mongo在云函数运行时中由 runtimes/nodejs/src/support/cloud-sdk.ts 注入包含clientMongoDB 客户端和db数据库实例两个成员。import cloud from lafjs/cloud const db cloud.mongo.db export async function main(ctx: FunctionContext) { // 向 user 集合中插入单个文档 const result1 await db.collection(user).insertOne({ name: jack }) console.log(result1) // 向 user 集合中批量插入文档 const documents [ { name: Jane Doe, age: 25 }, { name: Bob Smith, age: 40 } ]; const result2 await db.collection(user).insertMany(documents); console.log(result2) }原生写法与add的核心差异对比项add数据库 APIinsertOne/insertMany原生是否可自定义_id不可以自动生成可以在数据对象中手动指定_id字段即可默认_id类型stringObjectId 的 hex 字符串ObjectIdMongoDB 原生类型返回结果统一的AddResidinsertedCountMongoDB 驱动原生返回insertedId/insertedIds等权限管控受 Laf 数据库访问策略policy管控云函数内直连数据库由云函数自身权限上下文决定需要注意两种写法面向同一份 MongoDB 数据插入的文档在集合中是共存的选择哪种写法取决于你是否需要掌控_id及是否需要 MongoDB 驱动的完整能力。深入原理一次 add 调用的完整链路从云函数代码到数据落库一次add调用经历了如下链路云函数入口import cloud from lafjs/cloudcloud.database()通过 runtimes/nodejs/src/support/cloud-sdk.ts 中的createCloudSdk()创建 SDKdatabase()返回database-proxy的getDb(DatabaseAgent.accessor)database-ql 层collection(user).add(data, options)经DocumentReference.create()完成校验、序列化并发送ActionType.add请求见 packages/database-ql/src/collection.ts 与 packages/database-ql/src/document.ts数据库代理层database-proxy的 accessor 根据multi标记分别执行insertOne或insertMany并在插入前统一调用generateDocId()生成_id见 packages/database-proxy/src/accessor/mongo.ts返回链路插入结果_id、insertedCount沿调用链回传最终以AddRes结构返回给云函数代码。此外database-proxy同时支持 MongoDB 与 MySQL 两类 accessor见 packages/database-proxy/src/accessor/mysql.tsADD动作是两者共有的标准动作。权限与常见注意点权限策略通过add写入数据时会经过 Laf 数据库访问策略policy的校验。ActionType.ADD对应写入权限需在访问策略中为该集合配置add权限权限名映射见 packages/database-proxy/src/policy/policy.ts否则写入会被拒绝空对象异常add({})或add(null)会抛出data cannot be empty object因此业务上需要先校验入参非空Schema Free 的边界虽然无需预定义表结构但推荐在业务层对写入字段做基本校验避免脏数据积累_id唯一性add自动生成的_id基于 MongoDBObjectId生成全局唯一若使用原生写法自定义_id需自行保证其唯一性否则会触发 MongoDB 的主键冲突错误。结合以上内容你可以在 Laf 云函数中自由选择add或 MongoDB 原生写法来新增数据常规业务推荐add自动管理_id、受策略保护需要精细控制文档主键或复用原生驱动能力时再选用insertOne/insertMany。【免费下载链接】lafLaf is a vibrant cloud development platform that provides essential tools like cloud functions, databases, and storage solutions. It enables developers to quickly unleash their creativity and bring innovative ideas to life with ease.项目地址: https://gitcode.com/GitHub_Trending/la/laf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
