# 云函数与 Snippet (/docs/use/serverless)

Snippet 是 Mix Space 的扩展机制。每个 Snippet 是一段可配置的代码片段，可以为你的站点添加自定义数据接口、动态路由、前端脚本注入等能力。

## 功能总览

| 类型 | 说明 | 典型用途 |
|------|------|----------|
| **JSON / JSON5** | 结构化数据片段 | 配置数据、映射表 |
| **Text** | 纯文本片段 | 公告、自定义 HTML |
| **YAML** | YAML 数据片段 | 结构化配置 |
| **Function** | 可执行函数 | 云函数 API、自定义路由 |
| **Skill** | 技能包 | 以 markdown 形式下发给 AI 代理的技能包 |

<Callout type="info">
Function 类型的 Snippet 就是你常听到的「云函数」。它是 Snippet 系统的一个子集，拥有最强大的扩展能力。
</Callout>

## 管理云函数 / Snippet

登录后台，进入后台的「代码片段」页面页面。

### 导入社区云函数

<Steps>
<Step>
### 点击「下载拓展包」

在页面右上方点击「下载拓展包」按钮，弹出社区云函数列表。
</Step>

<Step>
### 选择并导入

在弹窗中找到对应主题的云函数代码，点击「导入」。
</Step>

<Step>
### 确认启用

导入后在管理页面确认 Snippet 已启用。Function 类型的 Snippet 需要手动开启「启用」开关。
</Step>
</Steps>

社区收录的云函数 Snippets 可以在 GitHub 查看：

<ToGithub repo="mx-space/snippets" />

### 手动创建 Snippet

1. 点击右上角「+」新建
2. 填写以下信息：

| 字段 | 说明 |
|------|------|
| **名称** | Snippet 名称（英文、数字、下划线，不超过 30 字符） |
| **类型** | JSON / JSON5 / Text / YAML / Function / Skill |
| **分组** | 用于组织 Snippet（Reference 字段） |
| **内容** | Snippet 的实际代码 |
| **备注** | 可选，备注说明 |
| **私有** | 勾选后仅管理员可访问 |

Function 类型额外支持：

| 字段 | 说明 |
|------|------|
| **自定义路径** | 绑定一个 URL 路径，如 `my-api` → `/s/my-api` |
| **HTTP 方法** | GET / POST / PUT / DELETE / PATCH / ALL |
| **启用** | 是否启用此函数 |
| **密钥** | 加密的配置项（如 API Key），存储时自动加密 |

### 分组管理

Snippet 按分组（Reference）组织。管理页面左侧显示分组列表，点击分组展开查看其中的 Snippet。你可以：
- 展开折叠分组
- 按 Reference 筛选
- 查看每个分组的 Snippet 数量

## Function 类型（云函数）

Function 类型是最强大的 Snippet，它是一段可以在服务器端执行的 JavaScript 函数。

### 自定义路由

设置「自定义路径」后，你可以通过 `/s/{自定义路径}` 访问此函数的执行结果。例如：

- 自定义路径 `bili-followings` → 访问 `/s/bili-followings` 获取哔哩哔哩关注列表
- 自定义路径 `bangumi` → 访问 `/s/bangumi` 获取追番数据

函数支持指定 HTTP 方法（GET、POST 等），也可以选择 ALL 匹配所有方法。

<Callout type="warn">
Function 类型 Snippet 有请求限流，高频调用场景请注意缓存（具体阈值见下方「限流」）。
</Callout>

### 函数日志

Function 类型 Snippet 的执行日志可以在管理页面查看。点击「日志」按钮可以查看函数的运行输出，方便调试。

### 安装依赖

Function 类型支持安装 npm 依赖包。在管理页面中：
- 点击「安装依赖」按钮添加需要的 npm 包
- 点击「更新依赖」更新已安装的包

### 密钥管理

函数中可能需要用到 API Key 等敏感信息。使用「密钥」字段存储，系统会自动加密。在函数代码中可以通过注入的上下文访问。

## 访问方式

| 类型 | URL 格式 | 说明 |
|------|----------|------|
| 数据类 Snippet | `/api/v3/s/{customPath}` | 需要设置自定义路径；公开读取走这个入口 |
| 云函数 | `/api/v3/fn/{reference}/{name}` | 别名 `/api/v3/serverless/{reference}/{name}` |

<Callout type="info">
`/api/v3/snippets/*` 是**后台管理接口**，所有路由都需要登录鉴权，不是给前端消费的公开地址。
</Callout>

- **公开（Public）** Snippet 所有人可访问
- **私有（Private）** Snippet 仅管理员登录后可访问

## 内置云函数

服务端自带 5 个开箱可用的云函数，无需自己编写：

| 函数 | 用途 |
| --- | --- |
| `ipQuery` | IP 查询 |
| `geocode_location` | 地理位置查询 |
| `geocode_search` | 地点搜索 |
| `stock_quote` | 股票实时行情 |
| `stock_bars` | 股票历史行情 |

内置函数可以通过管理页面的重置操作恢复到出厂状态。

## 函数可用能力

除「密钥」外，函数的 `context` 还提供：

- `context.storage.cache` —— 基于 Redis 的 KV 存储
- `context.storage.db` —— PostgreSQL 存储（`serverless_storages` 表，按 namespace 隔离）
- `context.writeAsset` / `context.readAsset` —— 读写二进制资源

## 限流

`/api/v3/s/*` 的限流是每 5 秒 100 次。云函数带额外路径段的通配路由（`/:reference/:name/*`）放宽到每 5 秒 1000 次。

## 前端主题集成

许多前端主题依赖 Snippet 提供数据。常见用法：

- Shiro 主题使用云函数提供哔哩哔哩追番、最近听歌等模块
- 自定义 CSS/JS 注入到前端页面
- 提供导航栏配置、社交链接等结构化数据

具体需要导入哪些 Snippet，请参考你使用的前端主题文档。

## 开发者文档

如需编写自定义 Function 类型 Snippet，请参考完整的开发者文档：

<ToGithub repo="mx-space/core/blob/master/apps/core/src/modules/serverless/serverless.readme.md" />