Day 11: Package-Oriented Design & Project Structure

Section 0: The "Why" & Core Vocabulary

ในโลกของ JVM / Kotlin / Spring Boot เราคุ้นชินกับการจัดหมวดหมู่โค้ดตาม "หน้าที่ทางเทคนิค" (Technical Layering): คลาส Controller ทั้งหมดไปกองรวมกันที่ controller/, Service ทั้งหมดไปอยู่ที่ service/, และ Entity/DTO ทั้งหมดไปอยู่ที่ model/

ใน Go กฎเหล็กของคอมไพเลอร์คือ: ห้ามมี Cyclic Import เด็ดขาด (Strict Directed Acyclic Graph - DAG) หาก Package A import Package B แล้ว Package B พยายาม import Package A ตัวคอมไพเลอร์จะหยุดการทำงานและปฏิเสธการ Build ทันที! Go จึงบีบให้เราต้องออกแบบระบบเป็น Domain-Driven Packages ที่มองแต่ละโฟลเดอร์เป็น "Micro-Library" อิสระ

Section 1: Go Syntax & Command Blueprint

การทำงานกับ Package ใน Go อิงตามโครงสร้าง Directory บนระบบไฟล์โดยตรง โดยมีหลักไวยากรณ์และการตั้งชื่อที่ต้องปฏิบัติตามอย่างเคร่งครัด:

1.1 การสร้าง Module และโครงสร้าง Standard Project Layout

# 1. คำสั่งเริ่มต้นสร้าง Go Module ที่ Root Directory
$ go mod init github.com/mybank/core-ledger

# 2. โครงสร้าง Standard Go Project Layout ระดับ Production:
core-ledger/
├── go.mod                  # นิยาม Module Path และ dependencies
├── go.sum                  # Checksum cryptographic hashes ของ dependencies
├── cmd/
│   └── ledger-cli/
│       └── main.go         # Entry point ของ binary: package main
├── internal/               # โค้ดลับเฉพาะภายในโปรเจกต์นี้ ห้ามคนนอก import
│   ├── account/            # Domain Package: บัญชีเงินฝาก
│   │   ├── account.go
│   │   └── account_test.go
│   └── settlement/         # Domain Package: การเคลียริ่งยอดเงิน
│       └── clearing.go
└── pkg/                    # (Optional) โค้ดที่อนุญาตให้ Public Library ภายนอกดึงไปใช้ได้
    └── money/
        └── currency.go

1.2 ไวยากรณ์ Package Declaration & Visibility Rules

ใน Go ไม่มีคีย์เวิร์ด public หรือ private แต่ใช้ ตัวอักษรพิมพ์ใหญ่ (Uppercase) = Exported (Public) และ ตัวอักษรพิมพ์เล็ก (Lowercase) = Unexported (Package-Private):

// internal/account/account.go
package account // ชื่อ package ต้องตรงกับชื่อโฟลเดอร์ (lowercase, คำสั้นๆ, ห้าม snake_case)

import "errors"

// ErrNegativeAmount ขึ้นต้นตัวใหญ่ = Exported (ภายนอก Package เรียกใช้ได้)
var ErrNegativeAmount = errors.New("amount must be greater than zero")

// Account ขึ้นต้นตัวใหญ่ = Exported Struct
type Account struct {
    ID      string // Exported field: JSON serializable / คนนอกอ่านได้
    balance int64  // Unexported field: ซ่อนข้อมูลระดับ Capsule! ภายนอกห้ามแตะตรงๆ
}

// NewAccount เป็น Factory Constructor Function (Idiomatic Go)
func NewAccount(id string, initialBalance int64) (*Account, error) {
    if initialBalance < 0 {
        return nil, ErrNegativeAmount
    }
    return &Account{
        ID:      id,
        balance: initialBalance,
    }, nil
}

// Balance() เป็น Getter Method (Idiomatic Go ไม่นิยมตั้งชื่อ GetBalance)
func (a *Account) Balance() int64 {
    return a.balance
}

1.3 การ Import และการตั้งชื่อ Package ไม่ให้เกิด Package Name Pollution

// cmd/ledger-cli/main.go
package main

import (
    "fmt"
    "log"

    // Full Module Import Path (Module Path + Folder Path)
    "github.com/mybank/core-ledger/internal/account"
)

func main() {
    acc, err := account.NewAccount("ACC-10029", 50000)
    if err != nil {
        log.Fatalf("failed to init account: %v", err)
    }

    // เรียกใช้ Exported Field และ Exported Method
    fmt.Printf("Account: %s, Current Balance: %d\n", acc.ID, acc.Balance())

    // บรรทัดนี้จะ COMPILE ERROR ทันที เพราะ balance เป็นตัวพิมพ์เล็ก (Unexported)!
    // acc.balance = 99999999 
}

Section 2: Architecture & The `internal/` Compiler Rule

ทำไมสถาปัตยกรรมระดับ Production ของ Go จึงต้องมีโฟลเดอร์ internal/? นี่ไม่ใช่แค่ Convention ที่ตกลงกันเอง แต่เป็น Compiler Enforcement Rule ที่ถูก Hardcode ไว้ในตัว Go Toolchain ตั้งแต่ Go 1.4 เป็นต้นมา

2.1 กฎเหล็กของโฟลเดอร์ `internal/`

โค้ดใดก็ตามที่วางอยู่ใต้โฟลเดอร์ชื่อ internal/ จะสามารถถูก import ได้โดยแพ็กเกจที่อยู่ภายใต้ Root Parent เดียวกันเท่านั้น โมดูลภายนอก (Third-party หรือ Repositories อื่น) จะไม่สามารถ import ไปใช้งานได้โดยเด็ดขาด:

2.2 การตัดวงจร Cyclic Dependency ด้วย Consumer-Driven Interfaces

เมื่อ Package A ต้องการส่งข้อมูลให้ Package B แต่ Package B ก็ต้องการเรียกใช้งาน Package A ทางออกใน Go ไม่ใช่การใช้ Magic Annotation แต่เป็นการนำหลักการ "Consumer-Driven Interface" มาใช้:

Section 3: Visual Workflow & Dependency Graph

ใน Go โครงสร้าง Dependency Graph ของคุณต้องเป็น Directed Acyclic Graph (DAG) เสมอ ข้อมูลและคำสั่งต้องไหลจากบนลงล่าง หรือไหลจากขอบนอกเข้าสู่แกนกลางเท่านั้น

3.1 Architectural Flow in Banking Microservices

ข้อสังเกต: จุดที่ทำการสร้าง Instance (เช่น account.NewAccount()) และส่งผ่านเข้าไปยัง Service อื่น ควรเกิดขึ้นที่ cmd/main.go (Composition Root) เสมอ เพื่อหลีกเลี่ยงไม่ให้ Package ระดับเดียวกันต้องสร้าง Dependency ข้ามกันโดยตรง

Section 4: Edge Cases, Hazards & Idiomatic Patterns

// อันตราย: ปล่อยให้ภายนอกเขียนค่าทับได้โดยตรง
type UnsafeAccount struct {
    Balance int64 // Public field: ใครก็แก้เป็น 1,000,000,000 ได้!
}

// ปลอดภัยตามหลัก Encapsulation:
type SafeAccount struct {
    balance int64 // Private: บังคับแก้ไขผ่านฟังก์ชันที่มี Guard เท่านั้น
}

func (s *SafeAccount) Deposit(amount int64) error {
    if amount <= 0 {
        return errors.New("deposit amount must be positive")
    }
    s.balance += amount
    return nil
}

Idiomatic Naming Conventions ใน Go:

• ชื่อ Package ต้องสั้น กระชับ และเป็นตัวพิมพ์เล็กตัวเดียว (Single-word Lowercase): เช่น transport, ledger, rfid ห้ามใช้ camelCase, snake_case, หรือขีดกลาง kebab-case
• หลีกเลี่ยง Stuttering (การตั้งชื่อซ้ำซาก): เมื่อเรียกใช้งานจากภายนอก ชื่อ Package จะนำหน้า Type เสมอ ดังนั้นอย่าตั้งชื่อว่า account.AccountService ให้ตั้งชื่อว่า account.Service เพราะเวลาเรียกจะกลายเป็น account.Service ที่อ่านลื่นไหลกว่า
• Single Responsibility: 1 Package ควรรับผิดชอบโดเมนเดียว ไม่ควรนำโค้ดระบบบัญชีไปปนกับระบบส่งอีเมลแจ้งเตือน

Section 5: Knowledge Verification Quiz (16 Challenges)

ทดสอบความเข้าใจเชิงลึกระดับ Compiler & Package Architecture ทุกข้อมีคะแนนสะสมและอธิบายเหตุผลอย่างละเอียด

Section 6: Hands-on Engineering Labs

ลงมือออกแบบ Package และ Struct ให้ถูกต้องตามกฎเกณฑ์ของ Idiomatic Go และตรวจสอบผลผ่าน Verification Engine