最近讀到一篇關(guān)于 CLI 的文章: Exploring CLI Best Practices, 關(guān)于開發(fā) CLI 程序的一些最佳實(shí)踐, 感覺非常受益. 文中提出14條建議, 挨個(gè)實(shí)踐下來即可.
1. Every option that can have a default option should have a default option.
所有可以有默認(rèn)值的選項(xiàng)都應(yīng)該設(shè)置默認(rèn)值.
但我覺得還值得補(bǔ)充的是: 默認(rèn)值必須通過日志/print 方式告知用戶. 不然有些選項(xiàng)默認(rèn)值對(duì)新用戶有種懵逼的效用.
2. Provide long, readable option names with short aliases.
提供可讀性很好的長(zhǎng)名字的選項(xiàng)名稱和短的簡(jiǎn)寫選項(xiàng)名稱
例如, 在 python 中:
parser.add_argument('-v', '--version', help="print the current version")
文中的理由是: 長(zhǎng)名字可讀性好, 而簡(jiǎn)寫方便用戶在寫腳本的時(shí)候方便. 我不是很同意提供簡(jiǎn)寫選項(xiàng).理由如下:
- 簡(jiǎn)寫重名情況下, 有人傾向于選擇一個(gè)根本與長(zhǎng)名稱選項(xiàng)不相關(guān)的簡(jiǎn)寫, 很迷惑, 例如,
-v可以用于--version標(biāo)識(shí)打印版本號(hào), 但如果我還有一個(gè)選項(xiàng)--verbose用戶打開調(diào)試日志怎么辦? 換一個(gè)其他的簡(jiǎn)寫? - 不提供簡(jiǎn)寫是避免有人用簡(jiǎn)寫開發(fā)了腳本而其他人接手后還要繼續(xù)查詢 help 搞清楚什么含義.
3. Use common command line options.
用常用的選項(xiàng)名稱
就是遵從大多數(shù)的常用單詞, 別自己發(fā)明. 給出的鏈接也很有用, 值得參照.
4. Provide options for explicitly identifying the files to process.
提供選項(xiàng)支持指定要處理的文件
5. Don’t have positional options.
不要使用位置相關(guān)的選項(xiàng)
例如: your_command arg1 arg2 arg3 必須按照位置來的情況. 使用 --option option_value 的方式.
不過這個(gè)也特殊的情況, 比如一個(gè)命令包含了幾個(gè)大模塊的功能, 第一個(gè)選項(xiàng)用于指定子模塊. 例如: airflow 就是第一個(gè)選項(xiàng)是模塊名稱, 每個(gè)模塊下面都是通過 --option option-value 的方式指定參數(shù).
6. Provide an extensive, comprehensive help command that can be accessed by help, --help or -h.
通過 -h 或者 --help 選項(xiàng)打印幫助文檔.
7. Provide a version command that can be accessed by version, --version or -v.
通過 -v 或者 --version 打印版本號(hào)
但我覺得還不夠, 應(yīng)該在每次程序運(yùn)行日志開始自動(dòng)打印當(dāng)前命令的版本號(hào). 方便時(shí)候調(diào)試定位問題.
8. Don't go for a long period without output to the user.
長(zhǎng)時(shí)間運(yùn)行的程序, 通過打印一些信息告知用戶程序沒完蛋, 而是很忙
9. If a command has a side effect provide a dry-run/whatif/no_post option.
如果命令有副作用, 提供 dry-run 選項(xiàng)
dry-run 選項(xiàng)就是僅僅檢測(cè)當(dāng)前情況是否滿足運(yùn)行條件, 而不最終執(zhí)行. dry-run 是我認(rèn)為最性感的 CLI 的feature. 不光針對(duì)有副作用的命令, 針對(duì)需要非常長(zhǎng)時(shí)間運(yùn)行的命令也是如此(例如 Apache Pig 就有dry-run 特性, 而 Hive 就沒有), 開發(fā)過程必定要調(diào)試命令是否ok.
實(shí)現(xiàn) dry-run 不是簡(jiǎn)單的提供一個(gè)什么都不干的選項(xiàng)糊弄用戶, 而是分幾步走:
- 確定命令的核心功能, 比如 Pig 就是運(yùn)行 pig 計(jì)算腳本
- 在執(zhí)行核心功能前一步, 檢測(cè) dry-run, 如果打開, 程序就此停止, 告知用戶.
- 在 dry-run 作用前, 檢測(cè)所有的參數(shù)合法性, 執(zhí)行環(huán)境是否OK.
再說一遍: dry-run 是方便用戶大膽調(diào)試危險(xiǎn)操作, 而不是糊弄用戶. 要保證 dry-run 打開執(zhí)行成功的情況下, 刪掉dry-run 程序立馬執(zhí)行核心功能
10. For long running operations, allow the user to recover at a failure point if possible.
長(zhǎng)時(shí)間運(yùn)行的程序, 允許用戶可以從上次失敗的點(diǎn)恢復(fù)操作
這個(gè)說起來簡(jiǎn)單, 但做到不容易. 畢竟涉及到 checkpoint 的存儲(chǔ)和恢復(fù). 舉一個(gè)容易實(shí)現(xiàn)的例子: maven 編譯多模塊的 Java 項(xiàng)目, 提供了 mvn 命令 -rf 模塊名稱 的方式, 從之前失敗的模塊繼續(xù)執(zhí)行.
11. Exit with nonzero status codes if and only if the program terminated with errors.
正常執(zhí)行成功 exit_code 保證為0. 不正常情況保證 exit_code 非零
這是必須遵守的規(guī)范, 不遵守可以視為 bug. 是保證在shell 中通過 $? ==0 判斷上一個(gè)命令是否成功的基礎(chǔ).
12. Write to stdout for useful information, stderr for warnings and errors.
正常信息輸出到 stdout, 錯(cuò)誤和警告信息輸出到 stderr
13. Keep the CLI script itself as small as possible.
CLI 腳本本身越簡(jiǎn)單越好, 核心邏輯放到其他地方
14. Reserve outputting stack traces for truly exceptional cases.
保留錯(cuò)誤情況下的堆棧信息
用 Java 的話說: 吃異常等于吃屎, 最好別干.
總結(jié)
非常好的一篇關(guān)于 CLI 開發(fā)的最佳實(shí)踐, 雖然有幾點(diǎn)我不是很贊同, 但還是值得仔細(xì)閱讀, 認(rèn)真遵守大多數(shù).
-- EOF --
