Jamie-BitFlight/data-transformation

使用 Dasel v3 進行資料轉換

<when_to_use>

在以下情況啟用此技能：

• 修改組態檔中的值（YAML、TOML、JSON、XML、HCL、INI）
• 在資料格式之間轉換（JSON 轉 YAML、TOML 轉 JSON 等）
• 批次更新陣列元素（價格、版本、旗標）
• 新增、移除或重塑資料結構
• 合併物件或從現有資料建構新結構

</when_to_use>

安全規則

永遠不要將輸出直接重導向到同一個輸入檔案。 這會在 dasel 讀取檔案前將其截斷，導致資料遺失：

# 錯誤 — 會破壞輸入
cat config.yaml | dasel -i yaml --root 'port = 9090' > config.yaml

# 正確 — 先寫入暫存檔，再重新命名
cat config.yaml | dasel -i yaml --root 'port = 9090' > config_tmp.yaml && mv config_tmp.yaml config.yaml

永遠在覆寫前先驗證。 先預覽轉換結果，再進行重導向：

# 預覽
cat config.yaml | dasel -i yaml --root 'server.port = 9090'
# 套用
cat config.yaml | dasel -i yaml --root 'server.port = 9090' > config_tmp.yaml && mv config_tmp.yaml config.yaml

核心修改語法

在 dasel v3 中，不存在 put 和 delete 子命令。所有修改都使用賦值表達式搭配 --root 來輸出完整文件。

設定值

# 輸出完整文件，僅變更一個欄位
cat config.yaml | dasel -i yaml --root 'server.port = 9090'

# 數值、布林值和字串賦值
echo '{"count": 1}' | dasel -i json --root 'count = 42'
echo '{"enabled": false}' | dasel -i json --root 'enabled = true'
echo '{"name": "old"}' | dasel -i json --root 'name = "new"'

設定巢狀值

cat config.yaml | dasel -i yaml --root 'database.connection.host = "db.example.com"'
cat config.yaml | dasel -i yaml --root 'database.connection.port = 5432'

原地修改（安全模式）

# 單一欄位更新
cat config.yaml | dasel -i yaml --root 'server.port = 9090' > config_tmp.yaml && mv config_tmp.yaml config.yaml

# 多個欄位 — 使用分號串聯
cat config.yaml | dasel -i yaml --root 'server.port = 9090; server.host = "0.0.0.0"' > config_tmp.yaml && mv config_tmp.yaml config.yaml

格式轉換

透過 dasel 使用不同的輸入/輸出格式旗標進行管線處理：

# JSON 轉 YAML
cat data.json | dasel -i json -o yaml > data.yaml

# YAML 轉 TOML
cat config.yaml | dasel -i yaml -o toml > config.toml

# JSON 轉 XML
cat data.json | dasel -i json -o xml > data.xml

# TOML 轉 JSON
cat config.toml | dasel -i toml -o json > config.json

# CSV 轉 JSON
cat data.csv | dasel -i csv -o json > data.json

陣列操作

附加到陣列

# 在陣列末尾新增元素
echo '[1,2,3]' | dasel -i json --root '[$this..., 4]'
# 輸出: [1, 2, 3, 4]

# 在陣列中附加物件
cat data.json | dasel -i json --root 'items = [$root.items..., {"name": "new", "value": 42}]'

使用 each 進行批次更新

# 將所有價格乘以 1.1（增加 10%）
cat data.json | dasel -i json --root 'items.each(price = price * 1.1)'

# 對所有元素設定旗標
cat data.json | dasel -i json --root 'users.each(active = true)'

# 遞增所有值
echo '[1,2,3]' | dasel -i json --root 'each($this = $this + 1)'

篩選後轉換

# 只取得活躍使用者，然後擷取名稱
cat data.json | dasel -i json 'users.filter(active == true).map(name)'

物件操作

透過展開合併

# 在現有物件中新增鍵
cat base.json | dasel -i json --root '{ $root..., "newKey": "value" }'

# 合併兩個物件
cat base.json | dasel -i json --root '{ $root..., "extra": true, "version": 2 }'

透過重建刪除欄位

由於 v3 沒有 delete 命令，請透過建構只包含所需鍵的新物件來移除欄位：

# 只保留 "name" 和 "email"，其餘全部拋棄
echo '{"name":"a","email":"b","password":"c"}' | dasel -i json --root '{ name, email }'

透過重建重新命名欄位

echo '{"old_name": "value"}' | dasel -i json --root '{ "new_name": old_name }'

多步驟轉換

使用變數賦值和分號進行複雜操作：

# 將中間結果存入變數，再進行轉換
cat data.json | dasel -i json '$active = users.filter(active == true); $active.map(name)'

# 多個變數
cat data.json | dasel -i json '$a = items.filter(price > 100); $b = $a.map(name); $b'

條件式轉換

# 根據條件設定值
cat data.json | dasel -i json --root 'if(count > 5) { status = "many" } else { status = "few" }'

轉換模式

如需針對特定使用情境的詳細轉換模式（組態更新、批次處理、格式遷移、資料重塑、錯誤處理），請參閱 轉換模式。

參考資料

• Dasel v3 文件（擷取於 2026-02-19）
• Dasel 展開運算子（擷取於 2026-02-19）
• Dasel each() 函式（擷取於 2026-02-19）
• Dasel filter() 函式（擷取於 2026-02-19）
• Dasel CHANGELOG（擷取於 2026-02-19）