Codama 101

Codama 是為 Solana 程式生成多語言和框架的類型安全客戶端、創建 CLI 工具以及為探索者提供豐富程式資訊的最快方式。

一切都始於 Codama IDL——一種標準化格式，用於描述任何 Solana 程式，並作為生成所有程式相關工具的基礎。

通過單一的 Codama IDL，您可以生成：

適用於 JavaScript、Rust、Python 等的類型安全客戶端
與您的程式互動的 CLI 工具
與您的代碼保持同步的文檔
理解您程式結構的探索器整合
瞭解您程式介面的測試工具

Codama 消除了在多語言和框架中維護客戶端的繁瑣工作。

您無需在每次程式更改時手動編寫和更新客戶端代碼，只需使用 Codama IDL 格式描述您的程式，應用任何必要的訪問器轉換，然後自動生成其他所有內容。

核心概念

Codama 的架構圍繞三個基本概念：節點、訪問器和渲染器。

節點

在 Codama 中，一切都表示為節點樹。節點是一個結構化的數據對象，用於描述您的 Solana 程式的一個特定方面。

您的整個程式將成為一個層次結構樹，頂部以 RootNode 開始。

有不同類型的節點：

結構節點 (RootNode, ProgramNode, AccountNode, InstructionNode, ...)：定義程式的骨架
類型節點 (NumberTypeNode, StringTypeNode, StructTypeNode, ArrayTypeNode)：描述數據結構和字段類型
值節點 (NumberValueNode, StringValueNode)：表示默認值和常量

每種節點類型都有其特定用途，並提供一致的介面來表示其數據。語言特定的訪問器可以遍歷並將這些節點轉換為適合不同目標語言的表示方式，讓您可以通過組合簡單的節點來構建複雜的程式描述。

訪問器

訪問器是遍歷您的節點樹以進行分析或轉換的函數。

它們通過“訪問”樹中的每個節點並對其執行操作來實現訪問器模式。

訪問器有兩種類型：

分析訪問器（只讀）：遍歷節點並使用codama.accept()返回信息
轉換訪問器：遍歷節點並使用codama.update()返回修改後的樹

訪問器將您的程式是什麼（節點）與您想對其執行的操作（操作）分開。這意味著您可以對任何 Codama IDL 應用相同的轉換，而不管它是如何創建的。

渲染器

渲染器是將您的 Codama IDL 轉換為特定程式語言的客戶端代碼的訪問器函數。

每個渲染器都會遍歷 IDL 節點並為其目標語言生成適當的代碼文件、類型和介面。

要使用渲染器，請提供生成文件應保存的基礎目錄，以及可選的配置來自定義輸出：

ts
import { createFromRoot, programNode, rootNode } from 'codama';
import { renderJavaScriptVisitor, renderRustVisitor } from '@codama/renderers';

// Create or import your Codama IDL.
const codama = createFromRoot(rootNode(programNode({ ... })));

// Render SDKs from your IDL.
codama.accept(renderJavaScriptVisitor('clients/js/src/generated', { ... }));
codama.accept(renderRustVisitor('clients/rust/src/generated', { ... }));

目前僅提供以下渲染器：renderJavaScriptVisitor（與@solana/kit兼容）、renderJavaScriptUmiVisitor（與@metaplex-foundation/umi和@solana/web3.js兼容）以及renderRustVisitor。

安裝

使用您偏好的套件管理器安裝核心 Codama 套件：

text
pnpm install codama

這包括@codama/visitors和@codama/nodes套件，提供了創建和操作 IDL 所需的一切。

如果你希望更細緻地控制依賴項，可以單獨安裝 @codama/visitors 和 @codama/nodes 等個別套件。

要生成客戶端代碼，你還需要 renderers 套件：

text
pnpm install codama @codama/renderers

renderers 套件是單獨分發的，因為它需要文件系統訪問，並且僅適用於 Node.js 環境，而核心的 Codama 庫則可以在任何地方運行（Node.js、瀏覽器等）。

Set up

Codama 提供了一個命令行界面 (CLI)，簡化了處理 IDL 和生成客戶端代碼的過程。CLI 負責配置管理和腳本執行，使設置自動化工作流程變得簡單。

安裝 CLI 套件並初始化你的項目：

text
pnpm install @codama/cli
pnpm codama init

init 命令會提示你輸入：

你的 IDL 文件路徑（支持 Codama 和 Anchor IDL）
你想使用的腳本預設（JavaScript、Rust 等）

這將創建一個配置文件，定義你的 IDL 來源和生成腳本，類似如下：

json
{
    "idl": "path/to/your/idl",
    "before": [
        "./custom-transforms.js",
        { "from": "@codama/visitors#removeTypes", "args": [["internal"]] }
    ],
    "scripts": {
        "js": [
            { "from": "@codama/renderers-js", "args": ["clients/js/src"] }
        ],
        "rust": [
            { "from": "@codama/renderers-rust", "args": ["clients/rust/src"] }
        ]
    }
}

before 包含在每個腳本執行前運行的 Visitors（用於轉換、清理等），而 scripts 則包含用於生成客戶端的 Renderers。

你可以使用 run 命令執行配置的腳本：

text
pnpm codama run              # Run preparation steps only
pnpm codama run js rust      # Run specific language generators
pnpm codama run --all        # Run all configured scripts

不使用 CLI

如果你不想使用 CLI，可以在你的倉庫中創建一個 codama.ts 文件，指定你的 Codama IDL 邏輯（imports、visitors 和 renderers），然後運行：

text
pnpx tsx codama.ts

使用Codama創建你的SDK

Codama 101

核心概念

節點

訪問器

渲染器

安裝

Set up

不使用 CLI