Kenhuang Academy
  • English

      • Go Program Structure

      Go programs have a clear organizational structure. Understanding program structure is the foundation of learning Go. This chapter will detail the various components of Go programs.

      🏗️ Basic Structure of Go Programs

      Simplest Go Program

      // hello.go
package main

import "fmt"

func main() {
    fmt.Println("Hello, World!")
}

      Program Structure Analysis

      package main        // 1. Package declaration
import "fmt"        // 2. Import packages
func main() {       // 3. Function definition
    // 4. Function body
    fmt.Println("Hello, World!")
}

      📦 Package (Package)

      Package Concept

      Packages are the basic unit of code organization in Go. Every Go file must belong to a package.

      Package Declaration Rules

      // Package declaration must be the first line of the file (except comments)
package main        // Package name for executable programs
package utils       // Package name for library packages
package calculator  // Custom package name

      Package Naming Conventions

      • Package names should be short and clear
      • Use lowercase letters
      • Avoid underscores and mixed case
      • Package names usually match directory names

      main Package

      // main package is the entry package for executable programs
package main

import "fmt"

// main function is the entry point of program execution
func main() {
    fmt.Println("This is an executable program")
}

      Library Package Example

      // math/calculator.go
package calculator

// Add calculates the sum of two numbers
func Add(a, b int) int {
    return a + b
}

// Subtract calculates the difference of two numbers
func Subtract(a, b int) int {
    return a - b
}

      📥 Import (Import)

      Basic Import Syntax

      // Single import
import "fmt"
import "math"

// Multiple imports (recommended)
import (
    "fmt"
    "math"
    "strings"
)

      Import Methods Detailed

      1. Standard Import

      import "fmt"
import "net/http"

func main() {
    fmt.Println("Hello")
    http.ListenAndServe(":8080", nil)
}

      2. Alias Import

      import (
    f "fmt"           // Give fmt package alias f
    "net/http"
)

func main() {
    f.Println("Using alias")  // Use alias to call
}
      import . "fmt"

func main() {
    Println("Call function directly")  // No package prefix needed
}

      4. Anonymous Import

      import _ "net/http/pprof"  // Only execute package's init function

func main() {
    // pprof package is imported but not directly used
}

      Import Paths

      Standard Library Import

      import (
    "fmt"           // Formatted I/O
    "os"            // Operating system interface
    "net/http"      // HTTP client and server
    "encoding/json" // JSON encoding/decoding
)

      Third-Party Package Import

      import (
    "github.com/gin-gonic/gin"
    "github.com/gorilla/mux"
    "golang.org/x/crypto/bcrypt"
)
      import (
    "./utils"      // utils package in current directory
    "../config"    // config package in parent directory
)

      🔧 Function (Function)

      main Function

      package main

// main function is the entry point of the program
// 1. Must be in main package
// 2. Cannot have parameters
// 3. Cannot have return values
func main() {
    // Program logic
}

      init Function

      package main

import "fmt"

// init function executes automatically before main function
func init() {
    fmt.Println("Init function executed")
}

func main() {
    fmt.Println("Main function executed")
}

// Output:
// Init function executed
// Main function executed

      init Function Characteristics

      • Executes automatically without calling
      • Each package can have multiple init functions
      • Executes in code order
      • Executes before main function

      Function Definition Syntax

      // Basic function syntax
func functionName(parameters) returnType {
    // Function body
    return value
}

// Example
func greet(name string) string {
    return "Hello, " + name
}

      📝 Comments (Comments)

      Single-line Comments

      package main

import "fmt"

func main() {
    // This is a single-line comment
    fmt.Println("Hello") // End-of-line comment
}

      Multi-line Comments

      /*
This is a multi-line comment
Can span multiple lines
Usually used for documentation
*/
package main

      Documentation Comments

      // Package calculator provides basic mathematical operations
package calculator

// Add calculates the sum of two integers
// Parameters a and b are the numbers to add
// Returns the result of a + b
func Add(a, b int) int {
    return a + b
}

/*
Divide calculates division operation
Supports floating-point division, returns error when divisor is 0

Parameters:
  - dividend: Dividend
  - divisor: Divisor

Return values:
  - result: Division result
  - error: Error message, not nil when divisor is 0
*/
func Divide(dividend, divisor float64) (float64, error) {
    if divisor == 0 {
        return 0, fmt.Errorf("divisor cannot be zero")
    }
    return dividend / divisor, nil
}

      🏢 Project Structure Example

      Small Project Structure

      myapp/
├── go.mod
├── go.sum
├── main.go
├── README.md
└── utils/
    └── helper.go

      Medium Project Structure

      myproject/
├── go.mod
├── go.sum
├── main.go
├── README.md
├── cmd/                 # Command-line programs
│   ├── server/
│   │   └── main.go
│   └── client/
│       └── main.go
├── pkg/                 # Library code that can be used externally
│   ├── auth/
│   │   ├── auth.go
│   │   └── auth_test.go
│   └── database/
│       ├── db.go
│       └── db_test.go
├── internal/            # Internal packages, cannot be imported externally
│   ├── config/
│   │   └── config.go
│   └── handlers/
│       └── handler.go
├── web/                 # Web related files
│   ├── templates/
│   └── static/
├── docs/                # Documentation
└── scripts/             # Script files

      Large Project Structure

      enterprise-app/
├── go.mod
├── go.sum
├── README.md
├── Makefile
├── Dockerfile
├── cmd/                 # Application entry points
│   ├── api/
│   │   └── main.go
│   ├── worker/
│   │   └── main.go
│   └── cli/
│       └── main.go
├── internal/            # Private application code
│   ├── app/
│   │   ├── api/
│   │   ├── worker/
│   │   └── cli/
│   ├── pkg/
│   │   ├── config/
│   │   ├── database/
│   │   ├── logger/
│   │   └── middleware/
│   └── domain/
│       ├── user/
│       ├── order/
│       └── product/
├── pkg/                 # Library code that external applications can use
│   ├── client/
│   └── types/
├── api/                 # API definition files
│   ├── openapi/
│   └── proto/
├── web/                 # Web application related
│   ├── static/
│   └── template/
├── configs/             # Configuration files
├── deployments/         # Deployment configuration
├── docs/               # Design and user documentation
├── examples/           # Application examples
├── scripts/            # Build, install, analysis scripts
├── test/              # Additional external test applications and test data
└── vendor/            # Application dependencies (manually or tool-managed)

      📋 File Organization Standards

      File Naming Conventions

      // Good file naming
user.go          // Singular form
user_test.go     // Test file
user_model.go    // Specific functionality
database.go      // Function description

// Avoid
users.go         // Plural form
UserModel.go     // Capitalized beginning
user-model.go    // Using hyphen

      Package File Organization

      // user/user.go - Main type definitions
package user

type User struct {
    ID   int    `json:"id"`
    Name string `json:"name"`
}

// user/service.go - Business logic
package user

func (u *User) Save() error {
    // User save logic
    return nil
}

// user/repository.go - Data access
package user

type Repository interface {
    Create(user *User) error
    FindByID(id int) (*User, error)
}

// user/user_test.go - Test file
package user

import "testing"

func TestUser_Save(t *testing.T) {
    // Test code
}

      🔄 Program Execution Order

      Execution Flow Diagram

      1. Initialize imported packages
   ├── Execute package-level variable initialization
   ├── Execute init functions (in import order)
   └── Recursively process all dependent packages

2. Initialize main package
   ├── Execute package-level variable initialization
   └── Execute main package's init function

3. Execute main function

      Detailed Example

      // package a
package a

import "fmt"

var A = func() int {
    fmt.Println("Variable A initialized")
    return 1
}()

func init() {
    fmt.Println("Package a's init function")
}

// package b
package b

import (
    "fmt"
    _ "path/to/a"  // Import package a
)

var B = func() int {
    fmt.Println("Variable B initialized")
    return 2
}()

func init() {
    fmt.Println("Package b's init function")
}

// main.go
package main

import (
    "fmt"
    _ "path/to/b"  // Import package b
)

var MainVar = func() int {
    fmt.Println("main package variable initialized")
    return 3
}()

func init() {
    fmt.Println("main package's init function")
}

func main() {
    fmt.Println("main function executed")
}

// Output order:
// Variable A initialized
// Package a's init function
// Variable B initialized
// Package b's init function
// main package variable initialized
// main package's init function
// main function executed

      🎯 Practical Example

      Create a Complete Project

      # 1. Create project directory
mkdir calculator-app
cd calculator-app

# 2. Initialize module
go mod init github.com/username/calculator-app

      Project File Structure

      // main.go
package main

import (
    "fmt"
    "github.com/username/calculator-app/pkg/calculator"
)

func main() {
    fmt.Println("Calculator Application")
    
    result := calculator.Add(10, 5)
    fmt.Printf("10 + 5 = %d\n", result)
    
    result = calculator.Multiply(3, 4)
    fmt.Printf("3 * 4 = %d\n", result)
}

// pkg/calculator/calculator.go
package calculator

// Add calculates the sum of two numbers
func Add(a, b int) int {
    return a + b
}

// Subtract calculates the difference of two numbers
func Subtract(a, b int) int {
    return a - b
}

// Multiply calculates the product of two numbers
func Multiply(a, b int) int {
    return a * b
}

// Divide calculates the quotient of two numbers
func Divide(a, b int) (int, error) {
    if b == 0 {
        return 0, fmt.Errorf("divisor cannot be zero")
    }
    return a / b, nil
}

// pkg/calculator/calculator_test.go
package calculator

import "testing"

func TestAdd(t *testing.T) {
    result := Add(2, 3)
    expected := 5
    if result != expected {
        t.Errorf("Add(2, 3) = %d; want %d", result, expected)
    }
}

func TestDivide(t *testing.T) {
    // Normal case
    result, err := Divide(10, 2)
    if err != nil {
        t.Errorf("Divide(10, 2) returned error: %v", err)
    }
    expected := 5
    if result != expected {
        t.Errorf("Divide(10, 2) = %d; want %d", result, expected)
    }
    
    // Zero divisor case
    _, err = Divide(10, 0)
    if err == nil {
        t.Error("Divide(10, 0) should return error")
    }
}

      Run Project

      # Run main program
go run main.go

# Run tests
go test ./...

# Build program
go build -o calculator

      📚 Standard Library Import Example

      Common Standard Library Packages

      package main

import (
    "fmt"          // Formatted I/O
    "os"           // Operating system interface
    "time"         // Time handling
    "strings"      // String operations
    "strconv"      // String conversion
    "math"         // Mathematical functions
    "net/http"     // HTTP client and server
    "encoding/json" // JSON handling
    "io/ioutil"    // I/O utilities
    "log"          // Logging
)

func main() {
    // Use various standard libraries
    fmt.Println("Hello, World!")
    
    now := time.Now()
    fmt.Println("Current time:", now.Format("2006-01-02 15:04:05"))
    
    str := strings.ToUpper("hello")
    fmt.Println("Converted to uppercase:", str)
    
    num, _ := strconv.Atoi("123")
    fmt.Println("String to integer:", num)
}

      🎓 Summary

      In this chapter, we learned the basic structure of Go programs:

      • ✅ Package Declaration: Every Go file must declare a package name
      • ✅ Import Statements: Import packages that need to be used
      • ✅ Function Definition: main function is the program entry point
      • ✅ Comment Standards: Single-line, multi-line, and documentation comments
      • ✅ Project Organization: Reasonable directory structure and file naming
      • ✅ Execution Order: Understanding program initialization and execution flow

      Understanding program structure is the foundation of writing Go programs. Next, we will learn the basic syntax of Go language.

      Next chapter, we will learn Go Basic Syntax to master the syntax foundation of Go language.

      ::: tip Best Practices

      • Keep package names short and descriptive
      • Use consistent project structure
      • Write documentation comments for exported functions and types
      • Organize files reasonably, avoid individual files being too large :::