跳到主要内容
版本：0.4.x(Latest)

基本介绍​

Assets()是源码插件的资源声明入口，通过UseEmbeddedFiles()绑定插件的嵌入文件系统。嵌入文件系统包含插件的清单文件、前端页面、SQL迁移脚本和i18n国际化资源，宿主在启动时加载这些资源完成插件集成。动态插件通过WASM自定义段嵌入资源，不需要显式绑定。

能力阶段：声明期

类型支持：仅源码插件

能力设计​

资源目录结构​

插件的标准目录结构如下：

apps/lina-plugins/<plugin-id>/
├── plugin.yaml              # 插件清单                    [嵌入]
├── backend/                 # 后端Go代码                  [编译，不嵌入]
│   ├── plugin.go            # 注册入口
│   └── internal/            # 业务逻辑
├── frontend/                # 前端资源                    [嵌入]
│   └── dist/                # 构建产物
└── manifest/                # 清单资源                    [嵌入]
    ├── sql/                 # SQL迁移脚本
    │   ├── install.sql      # 安装脚本
    │   ├── uninstall.sql    # 卸载脚本
    │   └── mock.sql         # 模拟数据脚本
    ├── i18n/                # 国际化资源
    │   ├── zh-Hans.yaml
    │   └── en.yaml
    └── config/              # 配置模板
        ├── config.yaml      # 默认配置
        └── config.example.yaml  # 配置示例

嵌入文件系统绑定​

源码插件通过UseEmbeddedFiles()将静态资源嵌入到二进制文件中。嵌入范围仅包含清单文件、前端资源和manifest/目录下的运维资源，不包含后端Go源代码：

资源类型​

资源类型目录说明
清单文件plugin.yaml插件身份、依赖、菜单、权限等声明
前端资源frontend/dist/前端构建产物，由宿主托管在/x-assets/{plugin-id}/{version}/
SQL迁移manifest/sql/安装、卸载和模拟数据脚本，必须是幂等的
国际化资源manifest/i18n/多语言翻译文件
配置模板manifest/config/插件默认配置和配置示例

前端资源托管​

宿主将插件的前端资源托管在/x-assets/{plugin-id}/{version}/路径下。插件通过plugin.yaml的public_assets字段声明需要托管的目录：

public_assets:
  - source: frontend/dist
    mount: /
    index: index.html
字段说明
source插件内的源目录路径
mount挂载路径
index默认索引文件

SQL迁移脚本​

SQL迁移脚本位于manifest/sql/目录下，宿主在插件安装和卸载时执行：

脚本执行时机说明
install.sql插件安装创建表结构、初始化数据
uninstall.sql插件卸载清理表结构和数据
mock.sql开发环境插入模拟数据

SQL脚本必须是幂等的，使用IF NOT EXISTS或IF EXISTS确保重复执行不会出错。多租户插件的表需要包含tenant_id列。

国际化资源​

国际化资源位于manifest/i18n/目录下，使用YAML格式：

# manifest/i18n/zh-Hans.yaml
menu:
  dashboard: 仪表盘
  reports: 报表
  settings: 设置

messages:
  welcome: 欢迎使用
  error.notFound: 未找到资源
# manifest/i18n/en.yaml
menu:
  dashboard: Dashboard
  reports: Reports
  settings: Settings

messages:
  welcome: Welcome
  error.notFound: Resource not found

宿主在插件启用时加载国际化资源，供运行时翻译使用。

接口定义​

源码插件接口​

源码插件通过Assets()声明嵌入文件系统：

方法说明
UseEmbeddedFiles绑定插件的嵌入文件系统

AssetDeclarations接口定义：

type AssetDeclarations interface {
    UseEmbeddedFiles(fileSystem fs.FS)
}

动态插件资源管理​

动态插件通过WASM自定义段嵌入资源，不需要显式绑定。构建工具自动将以下资源嵌入.wasm产物：

自定义段内容
lina.plugin.manifest插件身份清单
lina.plugin.frontend.assets前端资源
lina.plugin.i18n.assets国际化资源
lina.plugin.apidoc.i18n.assets接口文档国际化资源
lina.plugin.install.sql安装SQL脚本
lina.plugin.uninstall.sql卸载SQL脚本
lina.plugin.mock.sql模拟数据SQL脚本
lina.plugin.manifest.resources清单资源文件

能力使用​

源码插件使用​

源码插件在init()中通过Assets()绑定嵌入文件系统：

package main

import (
    "embed"

    "lina-core/pkg/plugin/pluginhost"
)

//go:embed plugin.yaml all:manifest all:frontend/dist
var pluginFS embed.FS

func init() {
    plugin := pluginhost.NewDeclarations("my-author-my-domain-my-cap")
    plugin.Assets().UseEmbeddedFiles(pluginFS)

    if err := pluginhost.RegisterSourcePlugin(plugin); err != nil {
        panic(err)
    }
}

嵌入文件系统访问​

宿主通过SourcePluginDefinition.GetEmbeddedFiles()访问插件的嵌入文件系统：

// 读取插件清单
manifestData, err := fs.ReadFile(embeddedFS, "plugin.yaml")

// 读取SQL脚本
installSQL, err := fs.ReadFile(embeddedFS, "manifest/sql/install.sql")

// 读取国际化资源
i18nData, err := fs.ReadFile(embeddedFS, "manifest/i18n/zh-Hans.yaml")

动态插件资源管理​

动态插件的资源在构建时自动嵌入.wasm产物。构建工具扫描插件目录并生成对应的自定义段：

# 构建动态插件
make wasm p=my-plugin

构建工具会自动：

  1. 读取plugin.yaml并嵌入lina.plugin.manifest段
  2. 扫描frontend/dist/并嵌入lina.plugin.frontend.assets段
  3. 扫描manifest/i18n/并嵌入lina.plugin.i18n.assets段
  4. 扫描manifest/sql/并嵌入对应的SQL段
  5. 扫描manifest/resources/并嵌入lina.plugin.manifest.resources段

设计约束​

  • Assets()仅限源码插件。 动态插件通过WASM自定义段嵌入资源，不需要显式绑定。
  • 嵌入文件系统是只读的。 插件不能在运行时修改嵌入的资源。
  • SQL脚本必须是幂等的。 使用IF NOT EXISTS或IF EXISTS确保重复执行不会出错。
  • 多租户表需要tenant_id列。 宿主会检查租户感知插件的表结构。
  • 前端资源由宿主托管。 插件不应自行托管静态资源，应通过public_assets声明。
  • 国际化资源使用YAML格式。 宿主统一解析YAML格式的国际化文件。

相关文档​