边缘安全加速平台 EO Node.js

一、优势

·丰富的 Node.js 生态：可以直接使用 npm 中的各类第三方库和工具，轻松集成数据库、AI、支付等服务，满足复杂业务需求。

·全栈开发体验：无需再将前后端项目分离，可在同一个项目中完成开发和部署，大幅提升协作效率。

·路由即服务：通过文件系统即可定义 API 路由，实现后端逻辑的快速开发与部署，将后端服务像前端页面一样便捷管理。

二、开发模式

Node.js 函数支持多种开发模式：

三、快速开始

在项目的 ./cloud-functions/api 目录下新建 hello.js，使用以下示例代码创建你的第一个 Node.js 函数：

// ./cloud-functions/api/hello.jsexport default function onRequest(context) { return new Response('Hello from Node.js!');}

我们建议你通过子目录来管理函数文件，如下示例在 ./cloud-functions/api 下创建 nodeinfo.js，用于返回 node 相关信息：

// ./cloud-functions/api/nodeinfo.jsimport * as os from 'node:os'import { randomUUID, createHash } from 'node:crypto'export const onRequestGet = async ({ request }) => { const info = { nodeVersion: process.version, pid: process.pid, platform: os.platform(), url: request.url, } return new Response(JSON.stringify(info), { status: 200, headers: { 'Content-Type': 'application/json; charset=UTF-8' }, })}

在 Node.js 函数中使用 Express/Koa 开发时需注意，框架的路由只需要集中在一个函数文件里面处理，无需额外启动 HTTP Server 且需导出框架的实例。如下示例在 ./cloud-functions/express 下创建 [[default]].js，用于处理 express 的业务逻辑：

// ./cloud-functions/express/[[default]].jsimport express from "express";const app = express();// 添加日志中间件app.use((req, res, next) => { console.log(`[${new Date().toISOString()}] ${req.method} ${req.url}`); next();});app.get("/", (req, res) => { res.json({ message: "Hello from Express on Node.js!" });});app.get("/users/:id", (req, res) => { const { id } = req.params; res.json({ userId: id, message: `Fetched user ${id}` });});// 导出 express 实例export default app;

四、路由

Node.js 函数基于 /cloud-functions 目录结构生成访问路由。你可在项目仓库 /cloud-functions 目录下创建任意层级的子目录，参考下述示例。

…cloud-functions├── index.js├── hello-pages.js├── helloworld.js├── api ├── users ├── list.js ├── geo.js ├── [id].js ├── visit ├── index.js ├── [[default]].js…

上述目录文件结构，经 EdgeOne Makers 平台构建后将生成以下路由。这些路由将 Makers URL 映射到 /cloud-functions 文件，当客户端访问 URL 时将触发对应的文件代码被运行：

注意：说明：

五、路由匹配优先级

路由按以下优先级进行匹配（从高到低）：

1. 静态路由：精确匹配的路径优先（如 /api/users/list）。

2. 单级动态路由：[param] 匹配单个路径段（如 /api/users/[id]）。

3. 多级动态路由（Catch-all）：[[param]] 匹配一个或多个路径段（如 /api/[[default]]）。

同级别路由中，路径越长（越具体）优先级越高。

六、入口文件识别

并非所有 .js / .ts 文件都会被注册为路由。只有导出了 Function Handlers 方法（如 onRequest、onRequestGet 等）或导出了框架实例（如 Express app）的文件才会生成路由。

不包含入口标识的 .js / .ts 文件将被视为辅助模块，会被复制到构建产物中供其他入口文件引用，但不会注册为独立路由。

七、动态路由

Node.js 函数支持动态路由，上述示例中一级动态路径 /cloud-functions/api/users/[id].js，多级动态路径 /cloud-functions/api/[[default]].js。参考下述用法：

八、动态路由参数获取

在 Handler 模式下，可通过 context.params 获取动态路由参数：

// ./cloud-functions/api/users/[id].jsexport function onRequestGet(context) { return new Response(`User id is ${context.params.id}`);}

九、框架内置路由

在涉及到 Express/Koa 框架的开发时，代码的编写与文件组织形式有几个要点需要注意。

注意：Express/Koa 框架：

例如，在目录 cloud-functions/express/* 下创建 express 应用，需以 [[default]].js 作为入口，且所有 express 相关路由都在 [[default]].js 里面：

cloud-functions └── express └── [[default]].js # express.js/koa.js 入口文件，包含框架内置路由定义

十、Function Handlers

使用 Function Handlers 可为 Makers 创建自定义请求处理程序，以及定义 RESTful API 实现全栈应用。支持下述的 Handlers 方法：

十一、基本用法

Handler 函数通过导出 onRequest 方法处理所有 HTTP 请求：

// ./cloud-functions/api/hello.jsexport default function onRequest(context) { return new Response('Hello, world!', { headers: { 'Content-Type': 'text/plain' }, });}

十二、处理多种请求方法

通过导出不同的 Handler 方法，可以分别处理不同类型的 HTTP 请求：

// ./cloud-functions/api/users/index.jsexport function onRequestGet(context) { return new Response(JSON.stringify({ users: [] }), { headers: { 'Content-Type': 'application/json' }, });}export function onRequestPost(context) { return context.request.json().then(data => { return new Response(JSON.stringify({ message: 'Created', data }), { status: 201, headers: { 'Content-Type': 'application/json' }, }); });}export function onRequestDelete(context) { return new Response(null, { status: 204 });}

十三、获取查询参数

// ./cloud-functions/api/search.jsexport function onRequestGet(context) { const url = new URL(context.request.url); const name = url.searchParams.get('name') || 'Guest'; return new Response(JSON.stringify({ hello: name }), { headers: { 'Content-Type': 'application/json' }, });}

EventContext 对象描述

context 是传递给 Function Handlers 方法的对象，包含下述属性：

·uuid：EO-LOG-UUID 代表了 EO 请求的唯一标识符。

·params：动态路由 /cloud-functions/api/users/[id].js 参数值。

export function onRequestGet(context) { return new Response(`User id is ${context.params.id}`);}

·env：Makers 环境变量。

·clientIp：客户端 IP 地址。

·server：

·region: 部署地的区域编码。

·requestId: 请求 ID，用于日志跟踪。

·geo：客户端地理位置信息。

Response 对象描述

函数必须返回一个 Response 对象，来响应客户端的 HTTP 请求，包含 headers，status，body 等属性。

十四、示例模板

连接 MySQL 第三方数据库：

预览地址

源码地址

使用 Express 框架：

预览地址

源码地址

使用 Koa 框架：

预览地址

源码地址