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异步调用，无需等待结果（无返回值）。

无修饰符异步调用，需等待结果（默认行为）。