Cấu trúc dự án Golang: cmd, internal và cách chia package

Bắt đầu với một tệp

Một chương trình Go có thể nằm trọn trong một tệp main.go, và các công cụ nhỏ nên như vậy. Chương trình hoàn chỉnh dưới đây đọc đầu vào, xử lý rồi in ra báo cáo, tất cả trong một package:

package main

import (
	"fmt"
	"sort"
	"strings"
)

type Task struct {
	Title string
	Done  bool
}

func parse(lines string) []Task {
	var tasks []Task
	for _, line := range strings.Split(strings.TrimSpace(lines), "\n") {
		done := strings.HasPrefix(line, "[x] ")
		title := strings.TrimPrefix(strings.TrimPrefix(line, "[x] "), "[ ] ")
		tasks = append(tasks, Task{Title: title, Done: done})
	}
	return tasks
}

func report(tasks []Task) string {
	sort.SliceStable(tasks, func(i, j int) bool { return !tasks[i].Done && tasks[j].Done })
	var b strings.Builder
	for _, t := range tasks {
		mark := " "
		if t.Done {
			mark = "x"
		}
		fmt.Fprintf(&b, "[%s] %s\n", mark, t.Title)
	}
	return b.String()
}

func main() {
	input := `[x] write tests
[ ] fix login bug
[x] update README
[ ] review PR`
	fmt.Print(report(parse(input)))
}

Khi chương trình lớn dần, hãy tách nó thành nhiều tệp trong cùng thư mục và cùng package (parse.go, report.go, main.go). Các tệp trong một package dùng chung mọi định danh, nên không cần export hay import gì. Thường thì đó là tất cả cấu trúc mà một dự án vài nghìn dòng cần.

Nhớ rằng một package main gồm nhiều tệp phải được chạy như một package: go run ., không phải go run main.go. Nếu không, mỗi tệp được biên dịch riêng lẻ và bạn sẽ gặp lỗi undefined với những tên được định nghĩa ở các tệp khác.

Không có bố cục bắt buộc

Go không yêu cầu cấu trúc thư mục nào ngoài quy tắc "mỗi thư mục là một package". Hướng dẫn chính thức là trang Organizing a Go module trên go.dev, và trang này mô tả vài dạng bố cục, không phải quy tắc.

Repository GitHub golang-standards/project-layout được sao chép rất nhiều và cũng bị nhầm là một chuẩn rất nhiều. Đó là bộ sưu tập quy ước của cộng đồng rút ra từ các dự án lớn, và Russ Cox, khi đó là trưởng nhóm kỹ thuật của Go, đã mở một issue ở đó nói rõ rằng nó không phải chuẩn của Go. Phần lớn thư mục trong đó (pkg/, api/, build/, deployments/) chỉ có ý nghĩa với codebase lớn. Sao chép nguyên bộ khung vào một dự án mới chỉ tạo ra các thư mục rỗng và đường dẫn import dài mà chẳng được lợi gì.

Các quy tắc mà công cụ thực sự áp dụng rất ngắn:

• Một thư mục là một package. Mọi tệp .go trong đó (trừ các tệp _test.go dùng hậu tố _test) có chung một tên package.
• Đường dẫn import là đường dẫn module cộng với đường dẫn thư mục.
• Thư mục tên internal giới hạn ai được import những gì bên trong nó.
• Các thư mục tên testdata, và những thư mục bắt đầu bằng . hoặc _, bị công cụ go bỏ qua.

Các dạng bố cục phổ biến

Một lệnh duy nhất

todo/
├── go.mod        module github.com/you/todo
├── main.go
├── parse.go
├── report.go
└── parse_test.go

Phẳng, mọi thứ trong package main. go install github.com/you/todo@latest chạy được và tệp thực thi có tên todo.

Một thư viện

slug/
├── go.mod        module github.com/you/slug
├── slug.go       package slug
├── slug_test.go
├── example_test.go
└── internal/
    └── table/    helpers the public package uses, hidden from users

Package nằm ở gốc module, nên người dùng import github.com/you/slug và gọi slug.Make(...). Bất cứ thứ gì bạn không muốn hỗ trợ như API public thì đặt dưới internal/.

Một service hoặc nhiều tệp thực thi

shop/
├── go.mod                module github.com/you/shop
├── cmd/
│   ├── shop-api/
│   │   └── main.go       package main: flags, config, wiring
│   └── shop-worker/
│       └── main.go
├── internal/
│   ├── order/            package order: domain types and logic
│   │   ├── order.go
│   │   └── order_test.go
│   ├── store/            package store: database access
│   └── httpapi/          package httpapi: handlers, routing
├── migrations/
└── README.md

cmd/<name>/main.go chứa mỗi tệp thực thi một thư mục, và tên thư mục trở thành tên tệp thực thi (go build ./cmd/shop-api tạo ra shop-api). Mỗi main giữ thật mỏng: đọc cấu hình, tạo các phụ thuộc, khởi động máy chủ. Code thật nằm trong các package dưới internal/, nơi cả hai tệp thực thi dùng được còn module khác thì không.

Đây là bố cục mà phần lớn service Go cuối cùng đều đi tới. Hãy dùng nó khi bạn có tệp thực thi thứ hai hoặc có lý do thật sự để tách package, đừng dùng ngay từ ngày đầu.

internal/ được lệnh go kiểm soát

Một package dưới internal/ chỉ có thể được import bởi code nằm trong cây thư mục có gốc là thư mục cha của internal. Từ một module khác, quá trình build sẽ thất bại:

package example.com/b
	main.go:6:2: use of internal package example.com/a/internal/secret not allowed

Điều đó biến internal/ thành công cụ để giữ phạm vi API thật nhỏ. Code ở đó có thể thay đổi thoải mái, vì bạn biết mọi nơi gọi đều nằm trong repository của mình. Với một ứng dụng, đặt gần như mọi thứ vào internal/ là hợp lý. Với một thư viện, nó tách những gì bạn cam kết giữ ổn định khỏi những gì không cam kết.

internal hoạt động ở mọi độ sâu: shop/internal/order nhìn thấy được từ toàn bộ shop/, còn shop/internal/order/internal/pricing chỉ nhìn thấy được bên trong shop/internal/order/.

Đặt tên package

Tên package xuất hiện ở mọi chỗ gọi, nên nó quan trọng hơn cả cây thư mục.

• Ngắn, viết thường, một từ: order, store, httpapi. Không dấu gạch dưới, không mixedCaps.
• Đặt theo thứ nó cung cấp, không theo thứ nó chứa. util, common, helpers, misc và models không nói lên điều gì và trở thành bãi chứa đủ thứ; hướng dẫn phong cách của đội ngũ Go khuyên tránh những tên này một cách rõ ràng. Hãy đặt hàm hỗ trợ trong package dùng nó, hoặc trong một package được đặt tên theo mục đích (slug, retry).
• Tránh lặp từ. Nơi gọi viết order.Order và order.New, nên đừng đặt tên order.OrderService hay order.NewOrder. Thư viện chuẩn làm điều này nhất quán: http.Server, không phải http.HTTPServer.
• Tên thư mục và tên package nên trùng nhau, trừ package main trong các thư mục lệnh. Khi chúng khác nhau, người đọc phải mở tệp ra mới biết import đó đưa vào định danh nào.

Hãy tách package theo trách nhiệm, không theo loại. Cách chia models/, controllers/, services/ (phổ biến ở các hệ sinh thái khác) buộc mỗi tính năng phải đụng tới ba package và dễ tạo ra import vòng tròn, điều Go cấm. Các package được tổ chức quanh một khái niệm nghiệp vụ (order, payment, user) giữ kiểu dữ liệu và logic của chúng ở cùng một chỗ.

Đặt test ở đâu

Test nằm cạnh code trong cùng thư mục, trong các tệp tên *_test.go. Không có cây thư mục tests/.

• package order trong order_test.go: test nội bộ, dùng được các định danh unexported.
• package order_test trong cùng thư mục: test bên ngoài, chỉ nhìn thấy API exported như một nơi gọi bình thường. Hữu ích cho các ví dụ và để tránh import vòng tròn trong test.
• Tệp dữ liệu mẫu nằm trong thư mục testdata/ cạnh các test. Công cụ go bỏ qua thư mục này, và test chạy với thư mục package làm thư mục làm việc, nên các đường dẫn tương đối như testdata/big.json dùng được.

Các tệp khác ở thư mục gốc

Lỗi thường gặp

• Sao chép một template lớn cho dự án nhỏ. Hãy bắt đầu phẳng và thêm thư mục khi xuất hiện tệp thực thi thứ hai hoặc một ranh giới thật sự.
• Package tên utils hay common. Hãy đặt tên package theo việc nó làm.
• Mỗi tệp hay mỗi kiểu một package. Package trong Go được thiết kế là đơn vị lớn hơn class trong Java. Một package có mười tệp là bình thường.
• Import vòng tròn. Hai package không thể import lẫn nhau. Điều này thường có nghĩa là chúng thuộc về nhau, rằng một kiểu dùng chung nên chuyển xuống package ở tầng thấp hơn, hoặc rằng một bên nên phụ thuộc vào một interface nhỏ thay vì package kia.
• Dùng pkg/ theo phản xạ. Nó thêm một đoạn vào mọi đường dẫn import mà không thêm ý nghĩa.
• Đặt test trong thư mục riêng. Ở đó chúng không nhìn thấy code unexported và công cụ cũng không tìm chúng ở đó.