Subscribe to Untitled
Subscribe to Untitled
<100 subscribers
<100 subscribers
Share Dialog
Share Dialog
Candid 是 Internet Computer (ICP) 生态中的 接口描述语言(Interface Description Language, IDL),用于定义 Canister(智能合约)的公共接口。通过 .did 文件(Candid 文件),开发者可以明确声明服务的方法、参数和返回类型,确保跨语言、跨 Canister 的互操作性。本文详细介绍 Candid 的核心用法和最佳实践。
1. Candid 的核心概念
1.1 作用
接口标准化:定义 Canister 的公共方法及其输入输出类型。
跨语言支持:自动生成 Motoko、Rust、JavaScript 等语言的客户端代码。
动态调用:支持 Canister 间的无需编译的交互(通过 ic.http 或 Agent 库)。
1.2 文件扩展名
.did:Candid 接口描述文件的标准扩展名。
2. Candid 文件结构
2.1 基本语法
// 注释以双斜杠开头
// 类型定义(可选)
type UserId = principal;
type Profile = record {
name: text;
age: nat;
};
// 服务接口定义
service : {
// 方法定义
get_profile: (UserId) -> (Profile) query;
update_profile: (UserId, Profile) -> ();
}
2.2 关键元素
type定义自定义类型(如结构体、别名)。
service定义 Canister 的公共接口。
query标记只读方法(不修改状态,快速响应)。
oneway标记无需返回值的异步方法。
async标记需要等待结果的异步方法。
3. 基础类型系统
Candid 支持以下基础类型:
nat非负整数123
int有符号整数-42
textUTF-8 字符串"Hello, Candid!"
bool布尔值
trueprincipalICP 身份标识"rrkah-fqaaa-aaaaa-aaaaq-cai"
null空值null
vec<T>数组vec { 1; 2; 3 }
opt<T>可选类型opt 42
4. 复杂类型定义
4.1 记录类型(Record)
类似结构体,定义字段集合:
type User = record {
id: principal;
name: text;
age: nat;
tags: vec<text>;
};
4.2 变体类型(Variant)
表示多选一的数据结构:
type Result = variant {
ok: text;
err: text;
};
4.3 函数类型(Function)
定义回调函数:
type Callback = func (text) -> (text);
4.4 递归类型
支持递归定义(如链表):
type ListNode = record {
value: nat;
next: opt<ListNode>;
};
5. 服务接口定义
5.1 方法定义语法
service : {
// 语法: 方法名: (参数类型) -> (返回类型) 修饰符;
get_user: (principal) -> (opt<User>) query;
add_user: (User) -> (Result);
delete_user: (principal) -> () oneway;
}
5.2 修饰符
query只读方法,不消耗 Cycles,响应快(通常 < 2 秒)。
oneway异步调用,无需等待结果(无返回值)。
无修饰符异步调用,需等待结果(默认行为)。
Candid 是 Internet Computer (ICP) 生态中的 接口描述语言(Interface Description Language, IDL),用于定义 Canister(智能合约)的公共接口。通过 .did 文件(Candid 文件),开发者可以明确声明服务的方法、参数和返回类型,确保跨语言、跨 Canister 的互操作性。本文详细介绍 Candid 的核心用法和最佳实践。
1. Candid 的核心概念
1.1 作用
接口标准化:定义 Canister 的公共方法及其输入输出类型。
跨语言支持:自动生成 Motoko、Rust、JavaScript 等语言的客户端代码。
动态调用:支持 Canister 间的无需编译的交互(通过 ic.http 或 Agent 库)。
1.2 文件扩展名
.did:Candid 接口描述文件的标准扩展名。
2. Candid 文件结构
2.1 基本语法
// 注释以双斜杠开头
// 类型定义(可选)
type UserId = principal;
type Profile = record {
name: text;
age: nat;
};
// 服务接口定义
service : {
// 方法定义
get_profile: (UserId) -> (Profile) query;
update_profile: (UserId, Profile) -> ();
}
2.2 关键元素
type定义自定义类型(如结构体、别名)。
service定义 Canister 的公共接口。
query标记只读方法(不修改状态,快速响应)。
oneway标记无需返回值的异步方法。
async标记需要等待结果的异步方法。
3. 基础类型系统
Candid 支持以下基础类型:
nat非负整数123
int有符号整数-42
textUTF-8 字符串"Hello, Candid!"
bool布尔值
trueprincipalICP 身份标识"rrkah-fqaaa-aaaaa-aaaaq-cai"
null空值null
vec<T>数组vec { 1; 2; 3 }
opt<T>可选类型opt 42
4. 复杂类型定义
4.1 记录类型(Record)
类似结构体,定义字段集合:
type User = record {
id: principal;
name: text;
age: nat;
tags: vec<text>;
};
4.2 变体类型(Variant)
表示多选一的数据结构:
type Result = variant {
ok: text;
err: text;
};
4.3 函数类型(Function)
定义回调函数:
type Callback = func (text) -> (text);
4.4 递归类型
支持递归定义(如链表):
type ListNode = record {
value: nat;
next: opt<ListNode>;
};
5. 服务接口定义
5.1 方法定义语法
service : {
// 语法: 方法名: (参数类型) -> (返回类型) 修饰符;
get_user: (principal) -> (opt<User>) query;
add_user: (User) -> (Result);
delete_user: (principal) -> () oneway;
}
5.2 修饰符
query只读方法,不消耗 Cycles,响应快(通常 < 2 秒)。
oneway异步调用,无需等待结果(无返回值)。
无修饰符异步调用,需等待结果(默认行为)。
No activity yet