编辑:Blockpunk
社区:果壳宇宙(ID:DfinityFun)
前言
DFINITY Canister 软件开发工具包(SDK)提供了工具、示例代码和文档,帮助您创建在互联网计算机副本节点上运行的程序。
通过开发在互联网计算机上运行的程序,您可以部署高安全、防篡改的应用程序来提供 web 的服务,没有中心化技术栈的限制与高昂费用,没有管理和维护数据库的复杂性,没有运行企业级软件所需的硬件成本。
可以查看我们之前的资料汇总,了解更多关于互联网计算机的信息。
下图表示了本 SDK 使用教程的基本操作流程:
准备工作
安装当前版本的 SDK 之前,请验证以下内容
已链接互联网,并可以访问 macOS 或 Linux 本地的 shell 终端;如果想在项目前端开发中使用 SDK 的模板文件,请安装 node.js
下载、安装并检验 DFINITY SDK
相关操作可以查看:快速开始 dfinity 开发
安装 Motoko 语言编辑器插件
如果计划使用 Motoko 语言写程序并以 Visual Studio Code 为编辑器,则可以安装 VSCode的 Motoko 语言插件,它提供了语法突出显示、类型信息和自动补全等功能。
安装插件:
1. 下载并安装 Visual Studio。
2. 单击“View”,然后选择“Extensions”。
3. 搜索 “motoko”
4. 选择 DFINITY Foundation 发布的 Motoko 语言插件,然后选择“Install”。
如果您的程序有依赖项,还可以安装 Motoko 的软件包管理器,有关说明,请参阅https://github.com/kritzcreek/vessel。
创建新项目
这里创建一个示例,请执行以下操作:
1. 为互联网计算机示例项目创建文件夹
mkdir ~/ic-projects
2. 进入示例项目文件夹
cd ~/ic-projects
3. 为应用程序创建项目目录
dfx new hello_world
该命令创建了一个 hello_world 项目,其中包含默认项目目录、一些模板文件和项目的 Git 存储库。如果在本地安装了 node.js ,则创建新项目时还会添加一些前段模板代码和依赖项。
为了确保在 JavaScript、Motoko 和其他上下文中有效地使用项目名称,应该只使用字母数字字符和下划线命名。
创建成功的输出如下:
Fetching manifest https://sdk.dfinity.org/manifest.json
Creating new project \”hello_world\”…
CREATE hello_world/src/hello_world/main.mo (107B)…
CREATE hello_world/dfx.json (320B)…
CREATE hello_world/.gitignore (189B)…
CREATE hello_world/README.md (1.01KB)…
CREATE hello_world/src/hello_world/public/index.js (155B)…
CREATE hello_world/package.json (263B)…
CREATE hello_world/webpack.config.js (1.76KB)…
4. 查看默认目录结构
ls -l hello_world
默认情况下,项目目录至少包含一个子目录、一个模板自述文件 README.md 和默认配置文件 dfx.json 。项目目录可能包含以下部分或全部文件:
hello_world/
├── README.md # default project documentation
├── dfx.json # project configuration file
├── node_modules # libraries for front-end development
├── package-lock.json├── package.json
├── src # source files directory
| └── hello_world
│ ├── main.mo│ └── public
│ └── index.js
└── webpack.config.js
默认的项目目录下必须包含以下文件:
README.md 默认的项目文档;dfx.json 配置文件,用于为您的项目设置可配置选项;应用程序所需的所有源文件的默认 src 目录。src 目录包含一个模板 main.mo 可以修改或替换来写入你的核心编程逻辑
因为本教程主要介绍入门的基本知识,所以您只需操作用 main.mo 。如果安装了 node.js ,项目目录会包含可用于定义应用程序前端接口的其他文件和目录。稍后将介绍 public 文件夹下的前端的开发与模板文件。
查看模板示范文件
默认情况下,创建一个新项目会将一些模板文件添加到您的项目目录中。您可以编辑这些模板文件来写入您自己的代码,进而加快开发周期。这里使用默认的模板文件创建一个简单的程序,让它通过 Motoko 代码去打印文本字符串。
1. 在 Shell 中进入项目目录
cd hello_world
2. 在文本编辑器中打开 dfx.json 查看默认配置,以下是结果
{
\”canisters\”: {
\”hello_world\”: {
\”frontend\”: {
\”entrypoint\”: \”src/hello_world/public/index.js\”
},
\”main\”: \”src/hello_world/main.mo\”
}
},
\”defaults\”: {
\”build\”: {
\”output\”: \”canisters/\”
},
\”start\”: {
\”address\”: \”127.0.0.1\”,
\”port\”: 8000,
\”serve_root\”: \”canisters/hello_world/assets\”
}
},
\”dfx\”: \”0.5.4\”,
\”version\”: 1
}
3. 进入 src/hello_world 目录
cd src/hello_world
4. 打开 main.mo 查看代码
actor {
public func greet(name : Text) : async Text {
return \”Hello, \” # name # \”!\”;
};
};
您可能会注意到,这个示例代码没有定义大部分编程语言所需的主函数。对于 Motoko 来说,主函数隐含在文件本身中。隐式主函数在脚本语言(如 Python 和 Perl)中比较常见。
传统程序在 “Hello, World!” 教程中通常告诉大家如何使用 print 或 println 函数打印字符串,但传统的程序并不能代表在互联网计算机上运行的 Motoko 程序。稍后我们将进一步探索使用 actor 对象和异步消息处理的代码。
编译程序
现在可以将默认程序编译为可执行的 WebAssembly 模块。
1. 进入 hello_world项目的根目录
cd ~/ic-projects/hello_world
请注意,此步骤是必需的,因为必须在项目目录结构中才能执行 dfx build 命令。
2. 生成可运行的软件容器(canister)
dfx build
如果安装了 node.js ,指令成功后可以看到以下输出:
Building canisters hello_world
Building frontend
Bundling frontend assets in the canister
3. 验证由 build 命令创建的 canisters/hello_world 目录下包含的 WASM 与相关的文件
ls -l canisters/hello_world/
可以看到以下输出:
total 144
-rw-r–r– 1 pubs staff 8 Jan 28 13:30 _canister.id
drwxr-xr-x 4 pubs staff 128 Jan 28 13:30 assets
-rw-r–r– 1 pubs staff 43 Jan 28 13:30 main.did
-rw-r–r– 1 pubs staff 117 Jan 28 13:30 main.did.js
-rw-r–r– 1 pubs staff 155 Jan 28 13:30 main.js
-rw-r–r– 1 pubs staff 53420 Jan 28 13:30 main.wasm
canisters/hello_world 目录包含以下关键文件:
_canister.id 为已编译程序随机生成的标识符;main.did 程序的接口描述;main.js 程序接口的 JavaScript 表示;main.wasm 程序编译后的 WebAssembly。
canisters/hello_world 目录还包含了一个 assets 子目录存放 JavaScript 前端、自定义 CSS 和 HTML 文件。除此之外,dfx build 命令还会创建一个 +idl_ 目录,该目录的接口描述文件带有您的容器标识符(例如,文件名带有随机生成的标识符,类似于81DDA04F69F40FEEAC.did)。
启动本地网络并部署
现在您有了一个可以部署在本地副本网络上的程序。
1. 在 shell 终端上进入项目目录
2. 在本地启动互联网计算机网络
dfx start
如果系统提示您选择“允许或拒绝传入的网络连接”,请单击“允许”。启动本地网络后,会看到互联网计算机副本启动的消息以及当前网络配置的详细信息。
您可以使用 –background选项在后台运行互联网计算机的副本,无需在本地另外打开一个 shell 终端。
3. 在网络中部署程序
dfx canister install hello_world
dfx canister install 命令后指定项目需要与 dfx.json 配置文件中的容器名称 canister_name 相匹配。
会显示以下输出:
Installing code for canister hello_world, with canister_id ic:81DDA04F69F40FEEAC
4. 使用软件容器中定义 greet 函数
dfx canister call hello_world greet \”there\” –type string
这里使用了 dfx canister call 命令将“there”作为 string 类型的参数传递给 greet 函数。
5. greet 方法输出返回值 (Hello, there!) :
(\”Hello, there!\”)
使用默认前端
如果开发环境中安装了 node.js,创建项目后目录下会包括一个简单的前端示例,该示例包含 index.js 和 index.html ,让用户可以在浏览器中访问 hello_world 程序。
1. 进入 hello_world 项目目录
2. 在文本编辑器中打开src/hello_world/public/index.js
import hello_world from \’ic:canisters/hello_world\’;
hello_world.greet(window.prompt(\”Enter your name:\”)).then(greeting => {
window.alert(greeting);
});
这个 index.js 文件使用文档对象模型(DOM)来描述 Web 文档的结构和内容。这个示例文件导入了我们创建的软件容器,并在提示窗口中调用 greet 函数。
3. 查看在 canisters 目录下创建的静态资源
ls -l canisters/hello_world/assets/
输出一下内容:
total 24
-rw-r–r– 1 pubs staff 1191 Jan 28 13:30 index.js
-rw-r–r– 1 pubs staff 5524 Jan 28 13:30 index.js.map
这些文件是由 dfx build 命令使用节点模块和 index.js 模板自动生成的。
4. 启动互联网计算机网络
dfx start
5. 打开浏览器,进入 dfx.json 配置文件中指定的地址和端口号
127.0.0.1:8000
默认情况下,使用本地的 8000 端口作为 URL 就能导航到 hello_world 程序的前端。除了主机和端口之外,您指定的 URL 还需要通过canisterId参数,以指定您希望使用的容器。要指定容器,请使用以下语法附加标:
http://localhost:8000/?canisterId=ic:81DDA04F69F40FEEAC
6. 在前端使用容器提供的服务
7. 返回值