构建 API 并部署数据库

创建好架构文件（.sfn）后，接下来就该把设计变成实际的服务了。打开 API 构建，每个表的创建、查询、修改、删除 API 都会准备就绪，还能在同一个界面中确认每个地址可以由谁使用。

如有需要，还可以将自己编写的查询 API、静态文件 API 和实时事件连接到同一个服务。

开始之前

• 所需权限：已被授予数据库使用权限的用户
• 事先准备：需要先创建架构文件（.sfn）。

打开 API 构建

选择架构界面上方的 API 构建 选项卡，即可查看按表自动生成的 API 列表。

自动生成的 API

每个表默认会自动生成以下 5 个 API。如有需要，也可以手动添加新的 API。

在 添加新 API（Custom Endpoint） 中，可以添加自定义了所需查询和响应形式的 API。使用 添加静态文件 API，可以按文件格式提供工作空间中的 JSON、XML、HTML、图片和二进制文件。

通过 API 提供静态文件或文件夹

1. 选择 添加静态文件 API。
2. 在 存储空间 中选择 团队空间 或 个人空间。
3. 在 公开对象 中选择 单个文件 或 文件夹列表 · 文件内容，然后通过 选择文件 或 选择文件夹 指定源。
4. 如果选择了文件夹，请设置 允许的扩展名 和 包含子文件夹。扩展名留空时，所有格式都将成为对象。
5. 在 响应方式 中选择是在浏览器中显示内容（在浏览器中直接显示），还是以文件形式接收（下载）。
6. 确认端点权限后部署架构。

单个文件会在设置的端点上响应其内容。文件夹则会同时生成文件列表 JSON 和通过列表项的 id 读取内容的地址。重命名或移动文件时，基于路径生成的 id 也会改变，因此客户端应使用从列表中获取的最新 id 或 viewUrl。

在功能端点中，可以设置实时套接字、文件和图片上传、AI 回复等整个服务通用功能的权限。

导入实时事件与 REST 捆绑包

在实时套接字的 事件定义 中，可以只编写事件，也可以导入包含事件所需的表和 REST 设置的 JSON 或 YAML 捆绑包。

1. 选择 粘贴 AI 回答 并粘贴捆绑包。自行准备的捆绑包也可以按相同格式粘贴。
2. 要保留现有事件，选择 按名称合并；要替换当前全部事件，选择 全部替换。
3. 在 应用预览 中确认将要添加、更改、删除的事件，以及将要添加的表、列和 REST 数量。
4. 确认与现有 REST 冲突或格式被自动整理、排除的项目。仅在需要更改现有 REST 时才选择 覆盖冲突的 REST 设置。
5. 确认服务器检查结果并修正错误后，选择 应用。

导入会更改当前正在编辑的架构。只有完成 部署 后才会反映到实际服务。即使在导入界面中已应用，部署时服务器仍会重新检查事件和 REST 规则，未通过时不会部署。

用自定义端点创建 CRUD 之外的 API

当自动生成的 5 个 API（list/view/create/update/delete）不够用时，点击 添加新 API（Custom Endpoint） 可以更加精细地定义行为。

操作种类

除基本的 5 个 CRUD 操作外，操作种类 下拉菜单中还有以下选项。

目标范围 可从 集合（针对整个表或多条记录，通常是不带 :id 的路径）、单个项目（特定的一条记录）、命令（不符合 CRUD 的自定义命令式端点）中选择。

权限与 REST API 相同，分为 3 级

自定义端点的权限设置方式与自动生成的 API 相同。界面上有直接的说明，不会造成混淆。

选择 成员 + 附加条件 后，可以组合应用等级、所属团队、是否为管理员、本人（owner）等条件。例如，“仅限等级 2 以上”、“仅限销售团队成员”之类的条件，可以用与 REST API 自动生成端点完全相同的方式应用到自定义端点上。

直接编写 SQL

处理流程 选项卡的 基础查询 中有一个编辑器，可直接编写此端点要执行的 SQL。在自动生成的 API 中，将 基础查询 切换为 手写 SQL 即可打开相同的编辑器。

REST API 列表的 处理 列中也会显示此端点使用手写查询的标记（SQL 徽章）。自动生成的 API 无法表达的条件——例如“如果该成员今天已创建 3 行以上则拒绝”这类基于聚合的条件——只能通过此 SQL 编辑器实现。

检查 SQL 和参数

输入 SQL 后，浏览器会检查语法以及当前架构中的表和列。如果错误或待确认项显示了行号和列号，选择该项即可跳转到编辑器中的相应位置。也可以从部署区域打开存在错误的 SQL。

这项检查不会在实际数据库中执行查询。部署后，请调用 API，确认数据库特有函数、访问权限以及实际数据下的结果。

参数列表显示 SQL 中使用的 :name 形式的参数。:id、:user_id、:nick 和 :now 是由服务器填充的保留值。其他值在读取请求中来自查询字符串，在写入请求中来自输入处理后的请求正文。缺少的值按 NULL 处理。

通过处理流程改变请求处理方式

即使不直接编写 SQL，也可以在 处理流程 选项卡中按顺序添加预先准备好的函数，来改变请求的处理流程。函数分为输入处理、DB 处理、输出处理三个阶段。

权限设置

可以为每个 API 单独设置访问权限。这里所说的成员就是工作空间的成员账户。无需另外构建登录和认证系统，工作空间中已有的成员、等级、团队体系会直接与 API 权限联动。

部署

按以下步骤输入部署信息。

1. 数据库标识符：用英文输入部署服务器上要使用的 DB 的逻辑名称。
2. 存储引擎模式：从 SQLite3、PostgreSQL、MySQL 或 MariaDB 中选择。外部 DB 还需额外输入 host、port、DB 名称、用户和密码。MySQL 和 MariaDB 使用基于 InnoDB 的配置。
3. 在 基本设置 和 高级设置 中确认以下项目。

在 API 列表下方的部署区域中选择 部署，设置项会展开。部署区域固定在编辑界面的最底部，即使滚动 API 列表也始终可见。仅第一次选择不会执行部署。确认设置后再次选择 部署，数据库和 API 就会准备就绪。如果指定了客户端部署路径，还会一并生成可用于测试 API 的示例界面。更改界面的方法请继续参阅查看前端示例。

API 调用示例

已部署的 API 按以下形式调用。（以表名 user_profile 为例）

GET  /api/web/{dbName}/user_profile/list
GET  /api/web/{dbName}/user_profile/view/{id}
POST /api/web/{dbName}/user_profile/create
PUT  /api/web/{dbName}/user_profile/update/{id}
DELETE /api/web/{dbName}/user_profile/delete/{id}

创建（POST）请求示例：

POST /api/web/{dbName}/user_profile/create
Content-Type: application/json

{
  "email": "user@example.com",
  "is_active": true
}

读取错误响应

如果请求失败，请同时确认 HTTP 状态和 code 或 errorCode。错误代码不会因语言而改变，因此登录请求、重试等操作应根据代码判断，而 message 用于在界面上显示。

Webspace 的默认错误提示支持韩语、英语、日语、简体中文和德语。优先使用已登录成员的语言设置；如果没有设置或是不支持的语言，则参考请求的 Accept-Language。两者都不匹配时，以英语提示。在外部 API 集成中，请勿直接比较显示文字本身。

例如，需要登录的请求会返回以下信息。

{
  "code": "WEBSPACE_LOGIN_REQUIRED",
  "errorCode": "WEBSPACE_LOGIN_REQUIRED",
  "message": "需要登录。"
}

这些是错误响应中需要确认的核心字段。完整的响应格式可能因 REST API、静态文件、管理 API 而有所不同。

• 输入值验证响应使用现有格式 ok: false 和 errors 列表。即使 HTTP 状态为 200 也请确认 ok，并通过各项的 field、code、message 提示问题。
• WebSocket 错误在 type: "error" 消息的 data 中确认。现有的分类用 key 会保留，code 和 errorCode 用于区分错误原因。
• 服务器的实际文件路径、SQL 和内部错误原文不会返回给用户。如果是需要运营者查看服务器日志的错误，请一并提供发生时间、请求路径、HTTP 状态和错误代码。

部署与覆盖

覆盖已有数据的架构的操作遵循服务器的部署策略。根据组织策略，可以禁止该操作，或限制为仅管理员或指定的部署管理人员可以执行。更改结构之前，请确认受影响的列和 API，以及备份与恢复流程。

注意事项

• API 基于 SetFN 登录会话进行认证。未认证的请求会被拒绝。（但权限设置为 所有人 的 API 除外。）
• 更改架构结构时，API 端点也会随之更新，请确认现有集成代码的兼容性。
• SQLite3 数据保存在该服务器的 WebSpace 存储中，外部引擎数据保存在管理员设置的 DB 中。
• 列表的筛选、排序和页面大小在服务器允许的查询范围内使用。
• 如果从外部站点调用，请同时确认管理员的允许 Origin 和 CSP 设置。

相关文档

• 创建架构文件（.sfn）
• 制作实时五子棋游戏
• 查看前端示例
• 性能与扩展
• 开始使用 Webspace 管理