330
Docker --format 格式化輸出概要操作說明
Docker CLI 的 --format 參數提供了基於 Go模板 的日誌格式化輸出輔助功能，並提供了一些內置的增強函數。 本文結合 docker 日誌輸出格式化的具體操作示例，先簡要介紹 Go模板的常用語法，再介紹 Docker 內置增強函數的使用。
什麼是模板
上圖是大家熟悉的 MVC 框架（Model View Controller）： Model（模型，通常在服務端）用於處理數據、View（視圖，客戶端代碼）用於展現結果、Controller（控製器）用於控製數據流，確保 M 和 V 的同步，即一旦 M 改變，V 也應該同步更新。
而對於 View 端的處理，在很多動態語言中是通過在靜態 HTML 代碼中插入動態數據來實現的。例如 JSP 的 <%=....=%> 和 PHP 的 <?php.....?> 語法。
由於最終展示給用戶的信息大部分是靜態不變的，隻有少部分數據會根據用戶的不同而動態生成。比如，對於 docker ls 的輸出信息會根據附加參數的不同而不同，但其表頭信息是固定的。所以，將靜態信息固化為模板可以複用代碼，提高展示效率。
Go語言提供了簡單靈活的模板支持，而基於 Go 開發的 Docker 繼承了該強大能力，使其可以脫離 Shell 的相關操作，直接對結果進行格式化輸出。所有支持 --format 擴展的 Docker CLI 指令均支持該操作。
Go模板常用語法
注釋
-
格式：
{{/*注釋內容*/}} -
示例：
docker network inspect --format='{{/*查看容器的默認網關*/}}{{range .IPAM.Config}}{{.Gateway}}{{end}}' $INSTANCE_ID
變量
係統變量 {{.}}
點號表示當前對象及上下文，和 Java、C++ 中的 this 類似。可以直接通過{{.}}獲取當前對象。
另外，如果返回結果也是一個 Struct 對象（Json 中以花括號/大括號包含），則可以直接通過點號級聯調用，獲取子對象的指定屬性值。
示例代碼：
#可以通過級聯調用直接讀取子對象 State 的 Status 屬性，以獲取容器的狀態信息：
docker inspect --format '{{/讀取容器狀態/}}{{.State.Status}}' $INSTANCE_ID
注意： 如果需要獲取的屬性名稱包含點號（比如下列示例數據）或者以數字開頭，則不能直接通過級聯調用獲取信息。因為屬性名稱中的點號會被解析成級聯信息，進而導致返回錯誤結果。即便使用引號將其包含也會提示語法格式錯誤。此時，需要通過 index 來讀取指定屬性信息。
"Options": {
"com.docker.network.bridge.default_bridge": "true",
"com.docker.network.bridge.enable_icc": "true",
"com.docker.network.bridge.enable_ip_masquerade": "true",
"com.docker.network.bridge.host_binding_ipv4": "0.0.0.0",
"com.docker.network.bridge.name": "docker0",
"com.docker.network.driver.mtu": "1500"
},
示例操作：
# 直接級聯調用會提示找不到數據：
docker inspect --format '{{.Options.com.docker.network.driver.mtu}}' bridge
<no value>
# 用引號括起來會提示語法錯誤：
docker inspect --format '{{.Options."com.docker.network.driver.mtu"}}' bridge
Template parsing error: template: :1: bad character U+0022 '"'
# 正確的用法，必須用 index 讀取指定屬性名稱的屬性值：
docker inspect --format '{{/讀取網絡在hosts上的名稱/}}{{index .Options "com.docker.network.bridge.name"}}' bridge
docker0
自定義變量
可以在處理過程中設置自定義變量，然後結合自定義變量做更複雜的處理。 如果自定義變量的返回值是對象，則可以通過點號進一步級聯訪問其屬性。比如 {{$Myvar.Field1}}。
示例操作：
# 結合變量的使用，對輸出結果進行組裝展現，以輸出容器的所有綁定端口列表：
docker inspect --format '{{/通過變量組合展示容器綁定端口列表/}}已綁定端口列表：{{println}}{{range $p,$conf := .NetworkSettings.Ports}}{{$p}} -> {{(index $conf 0).HostPort}}{{println}}{{end}}' Web_web_1
# 示例輸出信息
已綁定端口列表：
80/tcp -> 32770
8081/tcp -> 8081
遍曆（循環）：range
格式：
{{range pipeline}}{{.}}{{end}}
{{range pipeline}}{{.}}{{else}}{{.}}{{end}}
range 用於遍曆結構內返回值的所有數據。支持的類型包括 array, slice, map 和 channel。使用要點：
- 對應的值長度為 0 時，range 不會執行。
- 結構內部如要使用外部的變量，需要在前麵加 $ 引用，比如 $Var2。
- range 也支持 else 操作。效果是：當返回值為空或長度為 0 時執行 else 內的內容。
示例操作：
# 查看容器網絡下已掛載的所有容器名稱，如果沒有掛載任何容器，則輸出 "With No Containers"
docker inspect --format '{{range .Containers}}{{.Name}}{{println}}{{else}}With No Containers{{end}}' bridge
brtest
peaceful_brown
test
docker inspect --format '{{range .Containers}}{{.Name}}{{println}}{{else}}With No Containers{{end}}' none
With No Containers
索引： index
如果返回結果是一個 map, slice, array 或 string，則可以使用 index 加索引序號（從零開始計數）來讀取屬性值。
示例代碼：
# docker inspect $INSTANCE_ID 查看容器綁定的端口信息，其 Config 屬性就是一個 Map，包含了所有子網信息。
...
"IPAM": {
"Driver": "default",
"Options": null,
"Config": [
{
"Subnet": "172.31.254.1/24",
"Gateway": "172.31.254.1"
}
]
},
...
示例操作：
# 通過索引序號讀取默認網關
docker inspect bridge --format '{{/查看網絡的默認網關/}}{{(index .IPAM.Config 0).Gateway}}'
判斷：if … else … end
基本判斷
-
not
返回單一參數的布爾否定值，即返回輸入參數的否定值。
示例：
# 如果容器的 restarting 設置為 false，則返回信息“容器沒有配置重啟策略” docker inspect --format '{{if not .State.Restarting}}容器沒有配置重啟策略{{end}}' $(docker ps -q) -
or:
- {{or x y}}: 表示如果 x 為真返回 x，否則返回 y。
- {{or x y z}}：後麵跟多個參數時會逐一判斷每個參數，並返回第一個非空的參數。如果都為 false，則返回最後一個參數。
- 除了 null（空）和 false 被識別為 false，其它值（字符串、數字、對象等）均被識別為 true。
示例：
docker inspect --format '{{or .State.Status .State.Restarting}}' $INSTANCE_ID
判斷條件
判斷語句通常需要結合判斷條件一起使用，使用格式基本相同：
{{if 判斷條件 .Var1 .Var2}}{{end}}
go模板支持如下判斷方式：
-
eq: 相等，即 arg1 == arg2。比較特殊的是，它支持多個參數進行與比較，此時，它會將第一個參數和其餘參數依次比較，返回下式的結果：
{{if eq true .Var1 .Var2 .Var3}}{{end}} # 效果等同於： arg1==arg2 || arg1==arg3 || arg1==arg4 ... - ne: 不等，即 arg1 != arg2。
- lt: 小於，即 arg1 < arg2。
- le: 小於等於，即 arg1 <= arg2。
- gt: 大於，即 arg1 > arg2。
- ge: 大於等於，即 arg1 >= arg2。
判斷的使用
格式：
{{if pipeline}}{{end}}
{{if pipeline}}{{else}}{{if pipeline}}{{end}}{{end}}
{{if pipeline}}{{else if pipeline}}{{else}}{{end}}
示例操作：
# 輸出所有已停止的容器名稱：
docker inspect --format '{{if ne 0.0 .State.ExitCode}}{{.Name}}{{end}}' $(docker ps -aq)
docker inspect --format '{{if ne 0.0 .State.ExitCode}}{{.Name}}{{else}}該容器還在運行{{end}}' $(docker ps -aq)
docker inspect --format '{{if ne 0.0 .State.ExitCode}}{{.Name}}{{else if .}}該容器還在運行{{end}}' $(docker ps -aq)
# 輸出所有已停止或配置了 Restarting 策略的容器名稱
docker inspect --format '{{if ne 0.0 .State.ExitCode}}{{.Name}}{{else if eq .State.Restarting true}}容器{{.Name}}配置了Restarting策略.{{else}}{{end}}' $(docker ps -aq)
打印信息
docker --format 默認調用 go語言的 print 函數對模板中的字符串進行輸出。而 go語言還有另外 2 種相似的內置函數，對比說明如下：
- print： 將傳入的對象轉換為字符串並寫入到標準輸出中。如果後跟多個參數，輸出結果之間會自動填充空格進行分隔。
-
println: 功能和 print 類似，但會在結尾添加一個換行符。也可以直接使用
{{println}}來換行。 - printf: 與 shell 等環境一致，可配合占位符用於格式化輸出。詳細使用說明，可以參閱 go語言官方文檔。
對比示例輸出：
docker inspect --format '{{.State.Pid}}{{.State.ExitCode}}' $INSTANCE_ID
240390
docker inspect --format '{{print .State.Pid .State.ExitCode}}' $INSTANCE_ID
24039 0
docker inspect --format '{{.State.Pid}}{{println " 從這換行"}}{{.State.ExitCode}}' $INSTANCE_ID
24039 從這換行
0
docker inspect --format '{{printf "Pid:%d ExitCode:%d" .State.Pid .State.ExitCode}}' $INSTANCE_ID
Pid:24039 ExitCode:0
管道
管道 即 pipeline ，與 shell 中類似，可以是上下文的變量輸出，也可以是函數通過管道傳遞的返回值。
示例：
{{.Con | markdown | addlinks}}
{{.Name | printf "%s"}}
內置函數 len
內置函數 len 返回相應對象的長度。
示例：
docker inspect --format '{{len .Name}}' $INSTANCE_ID
Docker 增強模板及函數
Docker 基於 go模板的基礎上，構建了一些內置函數。下麵逐一說明：
json
Docker 默認以字符串顯示返回結果。而該函數可以將結果格式化為壓縮後的 json 格式數據。
示例：
# 獲取 Config 字段對應的 json 數據
docker inspect --format='{{json .Config}}' $INSTANCE_ID
join
用指定的字符串將返回結果連接後一起展示。操作對象必須是字符串數組。
示例：
# 輸出容器配置的所有 Entrypoint 參數，以 " , " 分隔：
docker inspect --format '{{join .Config.Entrypoint " , "}}' $INSTANCE_ID
lower
將返回結果中的字母全部轉換為小寫。操作對象必須是字符串。
docker inspect --format "{{lower .Name}}" $INSTANCE_ID
upper
將返回結果中的字母全部轉換為大寫。操作對象必須是字符串。
docker inspect --format "{{upper .Name}}" $INSTANCE_ID
title
將返回結果的首字母轉換為大寫。操作對象必須是字符串，而且不能是純數字。
docker inspect --format "{{title .State.Status}}" $INSTANCE_ID
split
使用指定分隔符將返回結果拆分為字符串列表。操作對象必須是字符串且不能是純數字。同時，字符串中必須包含相應的分隔符，否則會直接忽略操作。
docker inspect --format '{{split .HostsPath "/"}}' $INSTANCE_ID
參考資料
最後更新：2017-11-01 21:05:18