1# Project Structure and Module Management
2 
3## Standard Project Layout
4 
5```
6myproject/
7├── cmd/                    # Main applications
8│   ├── server/
9│   │   └── main.go        # Entry point for server
10│   └── cli/
11│       └── main.go        # Entry point for CLI tool
12├── internal/              # Private application code
13│   ├── api/              # API handlers
14│   ├── service/          # Business logic
15│   └── repository/       # Data access layer
16├── pkg/                   # Public library code
17│   └── models/           # Shared models
18├── api/                   # API definitions
19│   ├── openapi.yaml      # OpenAPI spec
20│   └── proto/            # Protocol buffers
21├── web/                   # Web assets
22│   ├── static/
23│   └── templates/
24├── scripts/               # Build and install scripts
25├── configs/              # Configuration files
26├── deployments/          # Docker, K8s configs
27├── test/                 # Additional test data
28├── docs/                 # Documentation
29├── go.mod               # Module definition
30├── go.sum               # Dependency checksums
31├── Makefile             # Build automation
32└── README.md
33```
34 
35## go.mod Basics
36 
37```go
38// Initialize module
39// go mod init github.com/user/project
40 
41module github.com/user/myproject
42 
43go 1.21
44 
45require (
46    github.com/gin-gonic/gin v1.9.1
47    github.com/lib/pq v1.10.9
48    go.uber.org/zap v1.26.0
49)
50 
51require (
52    // Indirect dependencies (automatically managed)
53    github.com/bytedance/sonic v1.9.1 // indirect
54    github.com/chenzhuoyu/base64x v0.0.0-20221115062448-fe3a3abad311 // indirect
55)
56 
57// Replace directive for local development
58replace github.com/user/mylib => ../mylib
59 
60// Retract directive to mark bad versions
61retract v1.0.1 // Contains critical bug
62```
63 
64## Module Commands
65 
66```bash
67# Initialize module
68go mod init github.com/user/project
69 
70# Add missing dependencies
71go mod tidy
72 
73# Download dependencies
74go mod download
75 
76# Verify dependencies
77go mod verify
78 
79# Show module graph
80go mod graph
81 
82# Show why package is needed
83go mod why github.com/user/package
84 
85# Vendor dependencies (copy to vendor/)
86go mod vendor
87 
88# Update dependency
89go get -u github.com/user/package
90 
91# Update to specific version
92go get github.com/user/[email protected]
93 
94# Update all dependencies
95go get -u ./...
96 
97# Remove unused dependencies
98go mod tidy
99```
100 
101## Internal Packages
102 
103```go
104// internal/ packages can only be imported by code in the parent tree
105 
106myproject/
107├── internal/
108│   ├── auth/           # Can only be imported by myproject
109│   │   └── jwt.go
110│   └── database/
111│       └── postgres.go
112└── pkg/
113    └── models/         # Can be imported by anyone
114        └── user.go
115 
116// This works (same project):
117import "github.com/user/myproject/internal/auth"
118 
119// This fails (different project):
120import "github.com/other/project/internal/auth" // Error!
121 
122// Internal subdirectories
123myproject/
124└── api/
125    └── internal/       # Can only be imported by code in api/
126        └── helpers.go
127```
128 
129## Package Organization
130 
131```go
132// user/user.go - Domain package
133package user
134 
135import (
136    "context"
137    "time"
138)
139 
140// User represents a user entity
141type User struct {
142    ID        string
143    Email     string
144    CreatedAt time.Time
145}
146 
147// Repository defines data access interface
148type Repository interface {
149    Create(ctx context.Context, user *User) error
150    GetByID(ctx context.Context, id string) (*User, error)
151    Update(ctx context.Context, user *User) error
152    Delete(ctx context.Context, id string) error
153}
154 
155// Service handles business logic
156type Service struct {
157    repo Repository
158}
159 
160// NewService creates a new user service
161func NewService(repo Repository) *Service {
162    return &Service{repo: repo}
163}
164 
165func (s *Service) RegisterUser(ctx context.Context, email string) (*User, error) {
166    user := &User{
167        ID:        generateID(),
168        Email:     email,
169        CreatedAt: time.Now(),
170    }
171    return user, s.repo.Create(ctx, user)
172}
173```
174 
175## Multi-Module Repository (Monorepo)
176 
177```
178monorepo/
179├── go.work              # Workspace file
180├── services/
181│   ├── api/
182│   │   ├── go.mod
183│   │   └── main.go
184│   └── worker/
185│       ├── go.mod
186│       └── main.go
187└── shared/
188    └── models/
189        ├── go.mod
190        └── user.go
191 
192// go.work
193go 1.21
194 
195use (
196    ./services/api
197    ./services/worker
198    ./shared/models
199)
200 
201// Commands:
202// go work init ./services/api ./services/worker
203// go work use ./shared/models
204// go work sync
205```
206 
207## Build Tags and Constraints
208 
209```go
210// +build integration
211// integration_test.go
212 
213package myapp
214 
215import "testing"
216 
217func TestIntegration(t *testing.T) {
218    // Integration test code
219}
220 
221// Build: go test -tags=integration
222 
223// File-level build constraints (Go 1.17+)
224//go:build linux && amd64
225 
226package myapp
227 
228// Multiple constraints
229//go:build linux || darwin
230//go:build amd64
231 
232// Negation
233//go:build !windows
234 
235// Common tags:
236// linux, darwin, windows, freebsd
237// amd64, arm64, 386, arm
238// cgo, !cgo
239```
240 
241## Makefile Example
242 
243```makefile
244# Makefile
245.PHONY: build test lint clean run
246 
247# Variables
248BINARY_NAME=myapp
249BUILD_DIR=bin
250GO=go
251GOFLAGS=-v
252 
253# Build the application
254build:
255	$(GO) build $(GOFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME) ./cmd/server
256 
257# Run tests
258test:
259	$(GO) test -v -race -coverprofile=coverage.out ./...
260 
261# Run tests with coverage report
262test-coverage: test
263	$(GO) tool cover -html=coverage.out
264 
265# Run linters
266lint:
267	golangci-lint run ./...
268 
269# Format code
270fmt:
271	$(GO) fmt ./...
272	goimports -w .
273 
274# Run the application
275run:
276	$(GO) run ./cmd/server
277 
278# Clean build artifacts
279clean:
280	rm -rf $(BUILD_DIR)
281	rm -f coverage.out
282 
283# Install dependencies
284deps:
285	$(GO) mod download
286	$(GO) mod tidy
287 
288# Build for multiple platforms
289build-all:
290	GOOS=linux GOARCH=amd64 $(GO) build -o $(BUILD_DIR)/$(BINARY_NAME)-linux-amd64 ./cmd/server
291	GOOS=darwin GOARCH=amd64 $(GO) build -o $(BUILD_DIR)/$(BINARY_NAME)-darwin-amd64 ./cmd/server
292	GOOS=windows GOARCH=amd64 $(GO) build -o $(BUILD_DIR)/$(BINARY_NAME)-windows-amd64.exe ./cmd/server
293 
294# Run with race detector
295run-race:
296	$(GO) run -race ./cmd/server
297 
298# Generate code
299generate:
300	$(GO) generate ./...
301 
302# Docker build
303docker-build:
304	docker build -t $(BINARY_NAME):latest .
305 
306# Help
307help:
308	@echo "Available targets:"
309	@echo "  build         - Build the application"
310	@echo "  test          - Run tests"
311	@echo "  test-coverage - Run tests with coverage report"
312	@echo "  lint          - Run linters"
313	@echo "  fmt           - Format code"
314	@echo "  run           - Run the application"
315	@echo "  clean         - Clean build artifacts"
316	@echo "  deps          - Install dependencies"
317```
318 
319## Dockerfile Multi-Stage Build
320 
321```dockerfile
322# Build stage
323FROM golang:1.21-alpine AS builder
324 
325WORKDIR /app
326 
327# Copy go mod files
328COPY go.mod go.sum ./
329RUN go mod download
330 
331# Copy source code
332COPY . .
333 
334# Build binary
335RUN CGO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo -o server ./cmd/server
336 
337# Final stage
338FROM alpine:latest
339 
340RUN apk --no-cache add ca-certificates
341 
342WORKDIR /root/
343 
344# Copy binary from builder
345COPY --from=builder /app/server .
346 
347# Copy config files if needed
348COPY --from=builder /app/configs ./configs
349 
350EXPOSE 8080
351 
352CMD ["./server"]
353```
354 
355## Version Information
356 
357```go
358// version/version.go
359package version
360 
361import "runtime"
362 
363var (
364    // Set via ldflags during build
365    Version   = "dev"
366    GitCommit = "none"
367    BuildTime = "unknown"
368)
369 
370// Info returns version information
371func Info() map[string]string {
372    return map[string]string{
373        "version":    Version,
374        "git_commit": GitCommit,
375        "build_time": BuildTime,
376        "go_version": runtime.Version(),
377        "os":         runtime.GOOS,
378        "arch":       runtime.GOARCH,
379    }
380}
381 
382// Build with version info:
383// go build -ldflags "-X github.com/user/project/version.Version=1.0.0 \
384//   -X github.com/user/project/version.GitCommit=$(git rev-parse HEAD) \
385//   -X github.com/user/project/version.BuildTime=$(date -u +%Y-%m-%dT%H:%M:%SZ)"
386```
387 
388## Go Generate
389 
390```go
391// models/user.go
392//go:generate mockgen -source=user.go -destination=../mocks/user_mock.go -package=mocks
393 
394package models
395 
396type UserRepository interface {
397    GetUser(id string) (*User, error)
398    SaveUser(user *User) error
399}
400 
401// tools.go - Track tool dependencies
402//go:build tools
403 
404package tools
405 
406import (
407    _ "github.com/golang/mock/mockgen"
408    _ "golang.org/x/tools/cmd/stringer"
409)
410 
411// Install tools:
412// go install github.com/golang/mock/mockgen@latest
413 
414// Run generate:
415// go generate ./...
416```
417 
418## Configuration Management
419 
420```go
421// config/config.go
422package config
423 
424import (
425    "os"
426    "time"
427 
428    "github.com/kelseyhightower/envconfig"
429)
430 
431type Config struct {
432    Server   ServerConfig
433    Database DatabaseConfig
434    Redis    RedisConfig
435}
436 
437type ServerConfig struct {
438    Host         string        `envconfig:"SERVER_HOST" default:"0.0.0.0"`
439    Port         int           `envconfig:"SERVER_PORT" default:"8080"`
440    ReadTimeout  time.Duration `envconfig:"SERVER_READ_TIMEOUT" default:"10s"`
441    WriteTimeout time.Duration `envconfig:"SERVER_WRITE_TIMEOUT" default:"10s"`
442}
443 
444type DatabaseConfig struct {
445    URL          string `envconfig:"DATABASE_URL" required:"true"`
446    MaxOpenConns int    `envconfig:"DB_MAX_OPEN_CONNS" default:"25"`
447    MaxIdleConns int    `envconfig:"DB_MAX_IDLE_CONNS" default:"5"`
448}
449 
450type RedisConfig struct {
451    Addr     string `envconfig:"REDIS_ADDR" default:"localhost:6379"`
452    Password string `envconfig:"REDIS_PASSWORD"`
453    DB       int    `envconfig:"REDIS_DB" default:"0"`
454}
455 
456// Load loads configuration from environment
457func Load() (*Config, error) {
458    var cfg Config
459    if err := envconfig.Process("", &cfg); err != nil {
460        return nil, err
461    }
462    return &cfg, nil
463}
464```
465 
466## Quick Reference
467 
468| Command | Description |
469|---------|-------------|
470| `go mod init` | Initialize module |
471| `go mod tidy` | Add/remove dependencies |
472| `go mod download` | Download dependencies |
473| `go get package@version` | Add/update dependency |
474| `go build -ldflags "-X ..."` | Set version info |
475| `go generate ./...` | Run code generation |
476| `GOOS=linux go build` | Cross-compile |
477| `go work init` | Initialize workspace |
478