开发 Blocklet
启动开发#
1. 在 blocklet.yml
中配置启动命令#
scripts:
dev: npm run start
scripts.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=/xxx
blocklet 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: true
name
: 变量名description
: 变量描述default
: 默认值required
: 是否必填shared
: 对客户端和组件是否可见secure
:secure
为true
的环境变量会被加密存储,且对被客户端和组件不可见
开发 blocklet 时,也可在项目根目录中的 .env
或 .env.development
文件中设置环境变量
注意:.env
或 .env.development
中只能设置 blocklet.yml 声明的环境变量
示例:
# .env
KEY_1=value1
blocklet 安装后,使用者可以在 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