Tham số dòng lệnh Golang: os.Args, flag và biến môi trường

os.Args

os.Args là một slice chuỗi. os.Args[0] là tên chương trình, phần còn lại là các đối số (argument) đúng như shell đã truyền vào.

package main

import (
	"fmt"
	"os"
)

func main() {
	fmt.Println("argument count:", len(os.Args)-1)
	for i, arg := range os.Args[1:] {
		fmt.Printf("arg %d: %q\n", i+1, arg)
	}
	if len(os.Args) < 2 {
		fmt.Println("no arguments: type some in the Args panel and run again")
	}
}

Trong khung Args của trình chỉnh sửa, mỗi ô là một đối số, được truyền nguyên dạng. Thử nhập hello, two words và -v vào ba ô: chương trình thấy ba đối số, và two words vẫn là một đối số có dấu cách ở giữa. Trong terminal, shell sẽ tách các đối số, nên điều tương tự được viết là go run . hello "two words" -v.

Luôn kiểm tra len(os.Args) trước khi truy cập theo chỉ số. os.Args[1] khi không có đối số sẽ panic với index out of range [1] with length 1.

Đối số là chuỗi. Hãy chuyển số bằng strconv.Atoi hoặc strconv.ParseFloat và xử lý lỗi, vì người dùng có thể gõ bất cứ thứ gì.

Package flag

Với các tùy chọn như -port 8080 -verbose, hãy dùng flag. Package này phân tích, chuyển kiểu, báo lỗi và tạo thông báo trợ giúp.

package main

import (
	"flag"
	"fmt"
	"strings"
	"time"
)

func main() {
	name := flag.String("name", "world", "who to greet")
	count := flag.Int("count", 1, "how many times")
	loud := flag.Bool("loud", false, "shout the greeting")
	delay := flag.Duration("delay", 0, "pause between greetings, e.g. 10ms")

	flag.Parse()

	msg := "hello, " + *name
	if *loud {
		msg = strings.ToUpper(msg) + "!"
	}
	for i := range *count {
		if i > 0 {
			time.Sleep(*delay)
		}
		fmt.Println(msg)
	}
	fmt.Println("remaining args:", flag.Args())
}

Khi không có đối số, chương trình in hello, world một lần. Trong khung Args, thử nhập -name và Gopher vào hai ô, rồi -count=3, -loud và extra vào ba ô nữa. Chương trình in HELLO, GOPHER! ba lần và remaining args: [extra].

Cách flag hoạt động:

• Mỗi hàm định nghĩa (flag.String, flag.Int, flag.Bool, flag.Float64, flag.Duration, flag.Uint64...) nhận một tên, một giá trị mặc định và một chuỗi hướng dẫn, rồi trả về một con trỏ. Đọc giá trị bằng *name sau flag.Parse().
• Các dạng Var gắn vào một biến bạn đã có: flag.IntVar(&cfg.Port, "port", 8080, "port"). Cách này gọn hơn khi dùng một struct cấu hình.
• Người dùng có thể viết -name value, -name=value, --name value hoặc --name=value. Go không phân biệt một gạch hay hai gạch.
• Boolean cần = để nhận giá trị. -loud đặt thành true, -loud=false đặt thành false, nhưng -loud false đặt thành true và để false lại làm một đối số vị trí.
• Việc phân tích dừng ở đối số đầu tiên không phải flag (hoặc ở --). prog file.txt -v coi -v là một đối số vị trí. Hãy đặt flag lên trước.
• flag.Args() trả về các đối số vị trí còn lại, flag.NArg() trả về số lượng của chúng, và flag.Arg(i) trả về một đối số trong đó.

Một flag không xác định hoặc một giá trị sai sẽ in ra lỗi kèm hướng dẫn sử dụng, rồi thoát với mã trạng thái 2. -h hoặc -help in ra hướng dẫn sử dụng và thoát với mã trạng thái 0 (từ Go 1.15). Nội dung hướng dẫn được tạo từ các định nghĩa của bạn:

Usage of greet:
  -count int
    	how many times (default 1)
  -delay duration
    	pause between greetings, e.g. 10ms
  -loud
    	shout the greeting
  -name string
    	who to greet (default "world")

Gán một hàm cho flag.Usage để in phần đầu riêng của bạn trước khi gọi flag.PrintDefaults().

Lệnh con với FlagSet

Các công cụ như git commit -m msg có lệnh con với flag riêng. Hãy tạo một flag.FlagSet cho mỗi lệnh con và chọn một cái bằng switch trên đối số đầu tiên:

package main

import (
	"flag"
	"fmt"
	"os"
)

func run(args []string) error {
	if len(args) < 1 {
		return fmt.Errorf("usage: todo <add|list> [flags]")
	}

	switch args[0] {
	case "add":
		fs := flag.NewFlagSet("add", flag.ContinueOnError)
		priority := fs.Int("p", 3, "priority 1 to 5")
		if err := fs.Parse(args[1:]); err != nil {
			return err
		}
		if fs.NArg() == 0 {
			return fmt.Errorf("add: missing task text")
		}
		fmt.Printf("added %q with priority %d\n", fs.Arg(0), *priority)
	case "list":
		fs := flag.NewFlagSet("list", flag.ContinueOnError)
		all := fs.Bool("all", false, "include finished tasks")
		if err := fs.Parse(args[1:]); err != nil {
			return err
		}
		fmt.Println("listing tasks, all =", *all)
	default:
		return fmt.Errorf("unknown command %q", args[0])
	}
	return nil
}

func main() {
	args := os.Args[1:]
	if len(args) == 0 {
		args = []string{"add", "-p", "1", "buy milk"} // demo input when the Args panel is empty
	}
	if err := run(args); err != nil {
		fmt.Fprintln(os.Stderr, "error:", err)
		os.Exit(1)
	}
}

flag.ContinueOnError khiến Parse trả về lỗi thay vì thoát, nhờ đó hàm vẫn kiểm thử được. run nhận các đối số qua tham số thay vì đọc os.Args, nên một bài test có thể gọi thẳng run([]string{"list", "-all"}). Thử nhập list và -all vào khung Args, hoặc delete để xem nhánh lỗi.

Với các CLI lớn có lệnh lồng nhau, tự hoàn thành trong shell và tài liệu tự sinh, phần lớn dự án dùng thư viện bên thứ ba github.com/spf13/cobra. Package flag chuẩn đáp ứng tốt các công cụ nhỏ.

Biến môi trường

package main

import (
	"fmt"
	"os"
	"strconv"
)

func envInt(key string, fallback int) (int, error) {
	v, ok := os.LookupEnv(key)
	if !ok {
		return fallback, nil
	}
	n, err := strconv.Atoi(v)
	if err != nil {
		return 0, fmt.Errorf("%s must be a number, got %q", key, v)
	}
	return n, nil
}

func main() {
	os.Setenv("APP_WORKERS", "8") // for the demo; normally set by the shell
	os.Setenv("APP_MODE", "")     // set, but empty
	os.Unsetenv("APP_MISSING")    // make sure it is unset

	fmt.Printf("Getenv APP_MODE:    %q\n", os.Getenv("APP_MODE"))
	fmt.Printf("Getenv APP_MISSING: %q\n", os.Getenv("APP_MISSING"))

	_, modeSet := os.LookupEnv("APP_MODE")
	_, missingSet := os.LookupEnv("APP_MISSING")
	fmt.Println("APP_MODE set:", modeSet, "| APP_MISSING set:", missingSet)

	workers, err := envInt("APP_WORKERS", 4)
	fmt.Println("workers:", workers, err)

	timeout, err := envInt("APP_TIMEOUT", 30)
	fmt.Println("timeout:", timeout, err)

	fmt.Println(os.ExpandEnv("running with $APP_WORKERS workers"))
}

• os.Getenv trả về "" cả khi biến không tồn tại lẫn khi biến được đặt là chuỗi rỗng. os.LookupEnv phân biệt được hai trường hợp.
• Giá trị luôn là chuỗi. Hãy chuyển kiểu và kiểm tra chúng ngay lúc khởi động, và báo lỗi bằng một thông điệp rõ ràng thay vì thất bại giữa chừng một request.
• os.Setenv ảnh hưởng tới tiến trình hiện tại và các tiến trình con khởi chạy sau đó. Nó không thể thay đổi môi trường của shell đã chạy chương trình.
• os.Environ() trả về mọi biến dưới dạng chuỗi "KEY=value".

Một cách bố trí cấu hình phổ biến: flag cho những gì người dùng gõ, biến môi trường cho thiết lập triển khai (các nền tảng container đặt chúng), trong đó flag ghi đè biến môi trường và biến môi trường ghi đè giá trị mặc định.

Mã thoát và os.Exit

Một chương trình Go thoát với mã trạng thái 0 khi main trả về. os.Exit(code) kết thúc tiến trình ngay lập tức với mã trạng thái đó. Theo quy ước, 0 là thành công, 1 là lỗi chung, và 2 là lỗi cách dùng (package flag dùng 2).

os.Exit không chạy các hàm defer. Tệp không được ghi hết và phần dọn dẹp bằng defer bị bỏ qua. log.Fatal gọi os.Exit(1) và có cùng tác dụng. Hãy để os.Exit ở một chỗ duy nhất, cuối main, và đặt chương trình thật vào một hàm run trả về lỗi, như ví dụ lệnh con ở trên:

func main() {
	if err := run(os.Args[1:]); err != nil {
		fmt.Fprintln(os.Stderr, "error:", err)
		os.Exit(1)
	}
}

Ghi thông báo lỗi ra os.Stderr, không phải os.Stdout, để chúng vẫn hiện ra khi đầu ra được chuyển hướng vào tệp hoặc nối ống sang lệnh khác. Một panic không được recover sẽ thoát với mã trạng thái 2.

Lỗi thường gặp

• Truy cập os.Args theo chỉ số mà không kiểm tra độ dài. Thiếu đối số sẽ gây panic.
• Đọc flag trước flag.Parse(). Bạn chỉ nhận được giá trị mặc định.
• Quên dấu *. fmt.Println(port) in ra một địa chỉ như 0xc000012345, không phải giá trị.
• Đặt flag sau đối số vị trí. prog input.txt -v không phân tích -v.
• -verbose false cho một flag boolean. Hãy viết -verbose=false.
• Gọi os.Exit hoặc log.Fatal sâu bên trong chương trình. Phần dọn dẹp bằng defer không bao giờ chạy và code không kiểm thử được. Hãy trả lỗi ngược lên main.