# go-wasm **Repository Path**: wanquan9527/go-wasm ## Basic Information - **Project Name**: go-wasm - **Description**: 见本项目的readme文件 - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-02-03 - **Last Updated**: 2026-03-02 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # go-wasm Go WebAssembly 工具集 - 提供 WASM 模块开发、加载和调试的完整解决方案。 ## 功能特性 ### 核心 - 🚀 **WASM 模块加载器** (`internal/loader`) - 安全、高效的 WASM 模块加载和调用 - 🛠️ **插件系统** (`internal/plugin`) - 完整的 WASM 插件生命周期管理 - 🏗️ **应用框架** (`internal/app`) - 集成插件系统的应用程序框架 ### 工具 - 🔨 **模板生成器** (`cmd/wasm_build`) - 快速生成 WASM Go 模块模板 - 🔍 **模块浏览器** (`cmd/wasm_browser`) - 查看和分析 WASM 模块结构 ### 示例 - 📚 **完整示例** (`examples/`) - 插件服务器、科学计算、正则表达式等实用示例 ## 快速开始 ### 安装 ```bash git clone https://gitee.com/wanquan9527/go-wasm.git cd go-wasm go mod tidy ``` ### 安装命令行工具 ```bash # 安装 WASM 模板生成器 go install ./cmd/wasm_build # 安装 WASM 浏览器 go install ./cmd/wasm_browser ``` ### 创建第一个 WASM 模块 ```bash # 使用交互式引导创建 WASM 模板 wasm_build prompt # 或使用快速初始化 wasm_build init my-module -d "我的第一个WASM模块" ``` ### 编译 WASM 模块 ```bash cd my-module GOOS=wasip1 GOARCH=wasm go build -o module.wasm . ``` ### 在 Go 中加载和调用 ```go package main import ( "context" "fmt" "log" "gitee.com/wanquan9527/go-wasm/internal/loader" ) func main() { ctx := context.Background() config := loader.DefaultConfig() // 创建模块 module, err := loader.NewModule("my-module", ctx, config) if err != nil { log.Fatal(err) } // 加载 WASM 文件 if err := module.LoadFromFile("module.wasm"); err != nil { log.Fatal(err) } defer module.Close() // 调用函数 result, err := module.CallFunction("Add", 10, 20) if err != nil { log.Fatal(err) } fmt.Printf("结果: %d\n", result[0]) } ``` ## 项目结构 ``` go-wasm/ ├── cmd/ │ ├── wasm_build/ # WASM 模板生成器 │ │ ├── main.go │ │ ├── generate.go │ │ ├── prompt.go │ │ └── README.md │ └── wasm_browser/ # WASM 模块浏览器 │ ├── main.go │ ├── loader.go │ ├── info.go │ ├── list.go │ ├── call.go │ ├── memory.go │ ├── repl.go │ └── README.md ├── internal/ │ ├── loader/ # WASM 加载器核心 │ │ ├── module.go │ │ ├── memory.go │ │ ├── function.go │ │ ├── config.go │ │ ├── reflective_memory.go │ │ └── readme.md │ ├── plugin/ # 插件管理器 ⭐ NEW │ │ ├── manager.go │ │ └── README.md │ └── app/ # 应用框架 ⭐ NEW │ ├── app.go │ └── README.md ├── pkg/ │ ├── common/ # 公共包（返回值代码处理） │ │ ├── constants.go │ │ ├── types.go │ │ └── utils.go │ └── wasm/ # WASM 工具包 │ └── README.md ├── examples/ # 示例项目 │ ├── plugin-server/ # 插件服务器示例 ⭐ NEW │ │ ├── main.go │ │ ├── build.sh │ │ ├── run.sh │ │ └── README.md │ ├── math/ # 科学计算示例 │ ├── regex/ # 正则表达式示例 │ └── README.md ├── docs/ # 文档 │ ├── wasm-development-guide.md │ ├── Go WebAssembly memory.md │ └── plugin-development.md # 插件开发指南 ⭐ NEW ├── test/ # 测试代码 ├── echo/ # Echo 示例 └── README.md # 本文件 ``` ## 核心概念 ### 统一返回值机制 所有 WASM 导出函数返回单一 `int32` 返回值代码，格式如下： ``` | 31 | 30-29 | 28-16 | 15-0 | | 符号 | 类型 | 保留 | 长度/码 | - 符号位(31): 0=成功, 1=失败/错误 - 类型位(30-29): 00=定长数据, 01=不定长数据, 10=多级数据 - 长度/码(15-0): 定长数据=数据长度, 错误=错误码 ``` ### 内存布局 ``` 0x0000 - 0x0FFF: 系统保留区 0x1000 - 0x1FFF: 栈空间 0x2000 - 0x2FFF: 静态空间 0x3000 - 0x3FFF: 定长数据空间 0x4000 - 0xFFFF: 不定长数据空间 ``` ### 数据类型支持 加载器支持丰富的数据类型读写操作： - **基本类型**: int8, int16, int32, int64, uint8, uint16, uint32, uint64, float32, float64 - **复杂类型**: 字符串、数组、结构体、JSON - **定长/不定长数据**: 支持固定大小和可变长度的数据传递 ### JSON 数据类型优化 ⭐ NEW 为了提高性能，推荐插件返回 Slice、Struct、Array、Map 等类型时使用 JSON 序列化： ```go import "gitee.com/wanquan9527/go-wasm/pkg/tool" // 插件返回 JSON 数据 jsonData, _ := json.Marshal(result) writeMemory(outputPtr, jsonData) // 注意：dataTypePtr 指向 4 字节内存，必须使用 WriteInt32 写入 tool.WriteInt32(dataTypePtr, int32(tool.JSON)) // JSON 类型 ``` 前端会自动识别 JSON 类型并直接解析，无需额外的解码步骤，显著提升性能。 详见：[插件开发指南 - JSON 数据类型](docs/plugin-development.md#json-数据类型规范-new) ## 插件系统 ⭐ NEW 插件系统提供了完整的 WASM 插件生命周期管理功能。 ### 快速开始 ```go import "gitee.com/wanquan9527/go-wasm/internal/plugin" // 创建插件管理器 manager := plugin.NewManager(plugin.ManagerConfig{ PluginDir: "./plugins", MaxPlugins: 10, }) defer manager.Shutdown(10 * time.Second) // 从目录加载所有插件 if err := manager.LoadFromDirectory("./plugins"); err != nil { log.Fatal(err) } // 执行插件函数 result, err := manager.Execute("plugin@1.0.0", "Add", 10, 20) if err != nil { log.Fatal(err) } fmt.Printf("结果: %v\n", result) ``` ### 应用框架 应用框架提供了完整的应用程序框架，集成插件系统和 TCP 服务器。 ```go import "gitee.com/wanquan9527/go-wasm/internal/app" // 创建应用 application := app.New(app.DefaultConfig()) // 启动应用 if err := application.Start(); err != nil { log.Fatal(err) } // 等待结束 application.Wait() ``` 查看完整示例：`examples/plugin-server/` ## 文档 - [WASM 开发指南](docs/wasm-development-guide.md) - 完整的 WASM 模块开发教程 - [内存交互指南](docs/Go%20WebAssembly%20memory.md) - 内存操作详细说明 - [加载器设计](internal/loader/README.md) - 加载器架构设计文档 - [插件管理器](internal/plugin/README.md) - 插件系统详细说明 ⭐ NEW - [应用框架](internal/app/README.md) - 应用层详细说明 ⭐ NEW - [示例项目](examples/README.md) - 可运行的示例代码 - [wasm_build 使用文档](cmd/wasm_build/README.md) - WASM 模板生成器详细说明 - [wasm_browser 使用文档](cmd/wasm_browser/README.md) - WASM 模块浏览器详细说明 ## 工具使用 ### wasm_build - WASM 模板生成器 ```bash # 交互式引导 wasm_build prompt # 快速初始化 wasm_build init my-module -d "模块描述" # 使用声明文件 wasm_build statement init -n my-module -o config.json wasm_build statement generate -f config.json -o wasm.go # 查看帮助 wasm_build --help ``` ### wasm_browser - WASM 模块浏览器 ```bash # 查看模块信息 wasm_browser -f module.wasm info # 列出导出函数 wasm_browser -f module.wasm list # 查看内存 wasm_browser -f module.wasm memory # 调用函数 wasm_browser -f module.wasm call Add 10 20 # 交互式模式 wasm_browser -f module.wasm repl ``` ## 示例 ### 插件服务器示例 ⭐ NEW ```bash cd examples/plugin-server ./build.sh ./run.sh ``` 一个完整的插件服务器应用，展示如何使用应用框架和插件系统。 ### 科学计算示例 ```bash cd examples/math ./build.sh ./math-example ``` 示例包含：加减乘除、矩阵运算、三角函数、统计分析等函数。 ### 正则表达式示例 ```bash cd examples/regex ./build.sh ./regex-example ``` 示例包含：模式匹配、查找、替换、分割、邮箱/电话/URL 验证等函数。 ## 依赖 - Go 1.24.0+ - [wazero](https://github.com/tetratelabs/wazero) - 轻量级 WASM 运行时 - [cobra](https://github.com/spf13/cobra) - CLI 框架 ## 编译说明 ### 标准 Go 编译器（推荐） ```bash GOOS=wasip1 GOARCH=wasm go build -buildmode=c-shared -o module.wasm . ``` ### TinyGo（更小体积） ```bash tinygo build -o module.wasm -target=wasi -opt=z . ``` **注意**： - `wasip1` 平台使用普通构建模式 - 插件开发必须使用构建标签 `//go:build wasip1` ## 测试 项目包含多个测试用例： ```bash # 运行测试 go test ./... # 运行特定测试 cd test/build_test go run main.go ``` ## 贡献 欢迎提交 Issue 和 Pull Request！ ## 许可 本项目采用 Apache 2.0 许可证。