Laf 云函数快速入门从零写一个可调试、可连库、可发请求的云函数【免费下载链接】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一个提供云函数、云数据库、云存储的云开发平台官方文档中的云函数快速入门为主线通过 Hello World、请求参数获取、JSON 响应、数据库访问、HTTP 请求五个递进示例带你在最短时间内掌握云函数的基本写法与运行方式并结合 Node.js 运行时源码runtimes/nodejs/目录解释FunctionContext是如何被组装、云函数主入口如何被识别和调用以及cloud.mongo.db背后的数据库连接机制帮助读者写出可直接部署、可复制运行的云函数代码。云函数的执行链路你的代码到底怎么被调用的在写第一行云函数之前先建立整体认知Laf 的 Node.js 云函数运行时本质上是一个 Express 应用所有到达云函数运行时的 HTTP 请求都会被路由到一个“万能路由”再由执行器找到你的函数代码并调用其默认导出。从源码结构看整条链路如下路由层router.ts 中注册了router.all(*, ...)任意路径、任意方法的请求都会进入云函数调用逻辑。路由会把路径首段作为函数名req.params[name]并限制函数名长度不超过 256 字符同时该路由挂载了uploader.any()基于 multer 的磁盘存储意味着请求体中的文件会被自动落盘这就是ctx.files的来源。上下文组装invoke.ts 的handleInvokeFunction将 Express 的请求信息装配成一个FunctionContext下文简称ctx对象包含query、body、headers、method、files、user、request/response等字段。执行器executor.ts 中的FunctionExecutor.invoke()会取出函数模块的mod.default || mod.main作为入口函数这就是为什么示例统一使用export default async function写法调用它并统计耗时若函数抛错或声明了拦截器返回拒绝则由 invoke.ts 统一转换为 500 / 403 响应。此外还有两个容易忽略的细节默认函数回退如果按路径名找不到同名函数运行时会回退查找名为__default__的默认函数见 invoke.ts两者都不存在才返回 404Function Not Found方法不匹配则返回 405。调试模式携带x-laf-develop-token请求头的请求会进入invokeDebug分支见 invoke.ts通过x-laf-debug-data请求头传入经过 gzip 压缩再 Base64 编码的函数源码无需发布即可在线调试运行日志会经x-laf-debug-logs响应头返回给调试端。这也是 Laf 控制台/CLI 中“保存后在线运行”的底层机制。FunctionContext的完整字段定义见 global.d.ts核心字段说明如下字段类型说明queryanyJSON 对象URL 查询参数bodyany请求体JSON / 表单 / rawheadersIncomingHttpHeadersHTTP 请求头filesFile[]上传的文件对象数组paramsany路由参数user对象从 JWT Token Payload 解析出的用户信息requestIdstring本次请求的唯一 ID便于日志排查methodstringHTTP 方法request/responseExpress 对象原始请求/响应可用于流式或 WebSocket 场景__function_namestring当前云函数名称Hello World最小可运行云函数官方文档给出的第一个示例是最简单的一条日志 一个返回值export default async function (ctx: FunctionContext) { console.log(Hello World) return hi, laf }这个函数做两件事打印一条日志Hello World返回字符串hi, laf作为响应内容——通过浏览器访问该云函数的地址即可看到hi, laf。结合源码可以补充几点实践要点入口约定执行器只认mod.default || mod.main即export default或 CommonJS 的module.exports.default/exports.main导出的函数函数不存在或非函数会抛出FunctionExecutionError见 executor.ts。日志去向console.log由运行时的Console封装捕获并进入云函数日志系统可在控制台查看调试模式下则通过响应头回传给调试界面。返回值即响应你return的值会被直接作为 HTTP 响应体发送ctx.response.send(data)其中纯数字会被转成字符串以避免响应异常见 invoke.ts。官方文档提示你可以在 Laf 线上平台创建一个应用再在其中创建函数就能直接调试本文的全部示例代码。获取请求参数ctx能给你什么第二个示例演示如何读取 URL 查询参数和客户端 IPexport default async function (ctx: FunctionContext) { // 获取请求参数 console.log(ctx.query) // 获取客户端的 IP 地址 const ip ctx.headers[x-forwarded-for] return 你的 IP 地址是${ip} }这里ctx.query是运行时把 URL 查询串解析后的 JSON 对象x-forwarded-for是网关/反向代理转发时写入的原始客户端 IP 头。需要说明的是请求在到达 Express 之前还经过了一层中间件若请求头中缺少x-real-ip运行时会用GetClientIPFromRequest解析出的真实 IP 补上见 index.ts因此你还可以通过ctx.headers[x-real-ip]拿到网关补充后的地址。在query之外ctx还提供完整的请求上下文字段表见前文ctx.body对应 POST 请求体运行时已通过express.json/express.urlencoded/express.raw解析大小受REQUEST_LIMIT_SIZE配置限制另支持 XML 解析ctx.user在请求携带有效 JWT 时由运行时解析填充ctx.files对应 multipart 上传的文件。也就是说绝大多数 Web 场景下你都不需要直接接触ctx.request原始对象。响应 JSON 对象第三个示例展示最常见的结构化返回export default async function (ctx: FunctionContext) { // ... return { code: success, message: 操作成功, data: [] } }函数直接返回对象Express 的response.send会自动将其序列化为 JSON 并设置Content-Type: application/json。这一约定让云函数的响应风格与 RESTful API 保持一致return什么客户端收到什么。两个源码级细节值得注意如果返回的是数字运行时会先Number(...).toString()再发送规避了res.send(number)的歧义行为见 invoke.ts。如果你已经在函数内通过ctx.response自行写完了响应例如流式输出、WebSocket 场景ctx.response.writableEnded true运行时不会再发送返回值。这意味着“直接操作 response”和“return 返回值”两种模式可以共存但不要在响应已结束后重复 return 大对象。访问数据库cloud.mongo.db与连接机制第四个示例演示云函数访问 Laf 云数据库底层为 MongoDBimport cloud from lafjs/cloud const db cloud.mongo.db export default async function (ctx: FunctionContext) { // 新增数据 await db.collection(users).insertOne({ username: laf, created_at: new Date() }) // 查询数据 const users await db.collection(users) .find() .toArray() return users }lafjs/cloud包导出的cloud是一个单例见 index.ts其mongo字段直接暴露MongoDB 官方 Node.js 驱动的client与db实例类型定义在 cloud.interface.ts。因此示例中的db.collection(users).insertOne / find().toArray()就是标准 MongoDB Driver API索引、聚合、事务都能直接使用。官方接口注释中给出了两类高频用法// 事务操作 const session mongo.client.startSession() try { await session.withTransaction(async () { await mongo.db.collection(xxx).updateOne({}, { session }) await mongo.db.collection(yyy).deleteMany({}, { session }) }) } finally { await session.endSession() } // 索引操作 await mongo.db.collection(users).createIndex(username, { unique: true })那么cloud.mongo.db是怎么来的从源码结构看运行时启动时db.ts 中的DatabaseAgent.initialize()使用Config.DB_URI创建MongoClient并连接连接失败时按指数退避重试初始 1s最长 30s失败持续则重置回 1s 继续重试保证数据库短暂不可用不会拖垮运行时。cloud-sdk.ts 的createCloudSdk()把DatabaseAgent.client和DatabaseAgent.db挂到cloud.mongo上并通过DatabaseAgent.ready异步保证连接就绪后再更新引用。运行时通过globalThis.createCloudSdk createCloudSdk注入到全局见 index.ts这样用户代码里import cloud from lafjs/cloud时SDK 内部能拿到运行时创建的实例。两点使用注意接口中旧的cloud.database()返回 database-ql 查询构造器与cloud.env均已标记deprecated推荐改用cloud.mongo.db和process.env读取环境变量见 cloud.interface.ts。除mongo外cloud还暴露getToken/parseTokenJWT 签发与解析、sockets当前 WebSocket 连接集合、appid当前应用 ID、storage云存储实例与shared跨请求共享内存官方注释建议仅少量缓存热数据等能力可配合函数引用与环境变量章节使用。发起 HTTP 请求第五个示例演示云函数内部调用外部 HTTP 接口export default async function (ctx: FunctionContext) { const res await fetch(https://laf.run/v1/regions) const obj await res.json() return obj }这里直接使用了 Node.js 18 提供的原生fetchWHATWG Fetch 标准 API无需引入任何第三方依赖。值得注意的是lafjs/cloud早期提供的cloud.fetchAxios 实例已被标记为废弃官方注释明确建议改用全局fetch()见 cloud.interface.ts上例即官方推荐写法。由此云函数形成了一个闭环能力它能读取请求ctx、操作数据cloud.mongo、调用外部服务fetch并把结果结构化返回——这正是 BaaS 场景下“前后端合并、函数即 API”的典型形态。进阶提示拦截器与多函数路由结合本次研究到的源码还有两个快速入门阶段容易踩坑、进阶必知的机制函数名即路径由于路由是router.all(*, ...)且按路径取函数名同一应用内的多个云函数通过各自函数名访问函数名超过 256 字符会被直接拒绝function name is too long见 router.ts。__interceptor__拦截器若应用中存在名为__interceptor__的云函数运行时会在每个函数执行前调用它且新版签名要求接收第二个参数next用于中间件式放行旧版“返回false即拒绝”的写法已被标记废弃见 executor.ts拦截器返回拒绝时客户端会收到 403Forbidden。下一步按官方文档的引导完成本篇入门后可以沿以下主题继续深入均为仓库内文档HTTP 请求完整理解ctx各字段与请求处理HTTP 响应状态码、响应头与流式输出HTTP 认证ctx.user与 JWT 鉴权处理文件上传ctx.files的上传处理发起网络请求出站请求的完整用法云数据库集合、查询与数据模型云存储文件上传、下载与托管函数引用云函数之间的直接调用环境变量process.env配置管理至此你已具备在 Laf 上编写、调试和部署基础云函数的完整能力以export default函数为入口用ctx读取请求用cloud.mongo.db操作数据库用原生fetch访问外部服务并通过控制台调试模式或正式发布让代码上线。【免费下载链接】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），仅供参考