开发 Blocklet
启动开发#
1. 在 blocklet.yml 中配置启动命令#
scripts:
dev: npm run startscripts.dev 可以配置为任意命令
如果 blocklet 是纯前端的，则无需设置 scripts.dev. 见 blocklet.yml: Types
2. 在项目根目录下执行 blocklet dev#
启动完成后，你将在终端中看到 blocklet 的访问地址
示例：
✔ Blocklet xxxxxxx@x.x.x was successfully started
ℹ You can access with the following URL
- http://xxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.did.abtnet.io"blocklet dev" 会先在 Server 中安装一个应用，然后将这个 blocklet 自动挂在到此应用中并启动。如果你希望将你的 blocklet 挂在到其他应用中开发，见 “将 Blocklet 挂在到应用中开发”
将 Blocklet 挂在到应用中开发#
将 Blocklet 挂在到应用中开发，要为 blocklet dev 命令添加 --app-did 和 可选的 --mount-point 参数
blocklet dev --app-did <app-did> --mount-point /xxx
或
BLOCKLET_DEV_APP_DID=<app-did> BLOCKLET_DEV_MOUNT_POINT=/xxx blocklet dev
或
- 在
.env中配置
BLOCKLET_DEV_APP_DID=<blocklet-app-did>
BLOCKLET_DEV_MOUNT_POINT=/xxxblocklet dev
--app-did 可在 blocklet 详情页中查看（使用 App DID 或 Permanent DID 均可）
--mount-point: 即 blocklet 在应用中的挂载点，比如 /, /path, /path/to
Blocklet 挂载点#
Blocklet 是应用中的组件，会挂载在站点的某个路径中 ( / 或 /xxx )。所以 Blocklet 需要关注和挂载路径有关的事项，包括 “获取挂载点”、“API”、“重定向”、“加载前端静态资源”
获取挂载点#
前端：引入 blocklet 运行时信息 后, 通过 window.blocklet.prefix 获取组件的挂载点
后端：在一次请求中, 通过请求 header 中的 x-path-prefix 获取组件的挂载点.
server.use((req, res) => {
const mountPoint = req.headers['x-path-prefix'];
});API#
Blocklet 自己的代码中，不需要 为 Web API 添加挂载点前缀，因为客户端的请求会先经过 Blocklet Service, 当组件收到请求时，已经去掉了请求的前缀
示例：
- 组件声明 API:
/api/foo - 组件挂载在
/child下 - 客户端请求
/child/api/foo - Blocklet Service 将请求转发给组件，并去掉前缀
/child - 组件收到请求
/api/foo
重定向#
我们需要支持在相对路径下后端的重定向可以正常工作
const prefix = req.headers['x-path-prefix'];
res.redirect(`${prefix}path/to`);我们需要支持在相对路径下前端的重定向可以正常工作
const prefix = window.blocklet.prefix;
window.location.href = `${prefix}path/to`;加载前端静态资源#
因为 Blocklet 的前端页面会在相对路径下被加载（比如 /child1/index.html），所以我们需要支持在相对路径下加载前端静态资源。
在构建应用时，将应用的前端静态资源前缀改为 /.blocklet/proxy/<blocklet did>
示例：
PUBLIC_URL='/.blocklet/proxy/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' npm run build
你通常不需要手动配置。当你使用 Create Blocklet 创建一个 Blocklet 项目时，已经为你配置好了一切。
停止开发#
启动开发后，在终端中按下 CTRL + C 停止开发
清空数据#
停止开发 blocklet 后，blocklet 的持久化数据并不会被自动清空。
你可以通过 blocklet dev clear 清空 blocklet 的所有数据
如果你将 blocklet 挂在到某个应用中，可通过 blocklet dev clear --app-did <app-did> 清空数据
获取配置#
blocklet 启动后，可通过 Blocklet SDK 获取 Blocklet 当前的运行环境和配置
获取运行环境：见 Blocklet SDK: Environment
获取配置：见 Blocklet SDK: Config
声明配置#
在 blocklet.yml 中声明配置：
environments:
- name: KEY_1
description: 'description for KEY_1'
default: ''
required: false
secure: false
shared: truename: 变量名description: 变量描述default: 默认值required: 是否必填shared: 对客户端和组件是否可见secure:secure为true的环境变量会被加密存储，且对被客户端和组件不可见
开发 blocklet 时，也可在项目根目录中的 .env 或 .env.development 文件中设置环境变量
注意：.env 或 .env.development 中只能设置 blocklet.yml 声明的环境变量
示例：
# .env
KEY_1=value1blocklet 安装后，使用者可以在 blocklet 管理面板中配置环境变量
在页面中获取 blocklet 运行环境#
你可以通过请求 blocklet 的 __blocklet__.js 接口获取 blocklet 运行环境
通过 Create Blocklet 创建的 blocklet 项目提供开箱即用的环境，你可以通过 window.blocklet 获取运行环境
// 应用 ID
window.blocklet.appId
// 应用版本
window.blocklet.version
// 应用名称
window.blocklet.appName
// 应用描述
window.blocklet.appDescription
// 应用 Url
window.blocklet.appUrl
// 共享的环境变量
window.blocklet.<shared env>Blocklet Scripts#
Blocklet Server 提供了 hook 功能用来在执行生命周期的过程中做一些事情。目前包含 pre-install, post-install, pre-start, post-start, pre-stop, pre-uninstall, pre-config 这几个 Hook.
在 blocklet 环境中运行脚本#
开发 blocklet 时, 有时我们想在 blocklet 环境下执行脚本（比如建立一些测试数据）。
可以通过执行 blocklet exec 实现，比如
blocklet exec mock/test.js
// mock/test.js
const { env } = require('@blocklet/sdk');
const { getWallet } = require('@blocklet/sdk');
console.log(env);
console.log(getWallet().address);Blocklet 组件间通信#
使用 Blocklet SDK 和应用中的其他 Blocklet 通信
const { component } = require('@blocklet/sdk');
(async () => {
await component.call(name, path, data);
})();如何在升级期间进行迁移#
当 blocklet 的持久化存储的数据结构发生不兼容改变时，我们可以使用 migration 脚本来完成自动数据迁移。
方法：
在 blocklet 根目录下创建 migration 目录
在 migration 目录中创建 migration 文件，文件名为 semver version, 比如 1.0.1.js
举例：
migration 目录中有 1.0.0.js, 1.0.1.js, 1.1.0.js 3 个文件
当 blocklet 从 1.0.0 升级至 1.2.0 时，会执行 1.0.1.js, 1.1.0.js 这两个 migration scripts
警告：需要将 migration 文件夹添加到 blocklet.yml 文件中的 files 字段中，如下所示：
files:
- ...
- migration