Go Service Template

🇻🇳 Tiếng Việt | 🇬🇧 English

---

English

A template for quickly scaffolding Go microservices following Clean Architecture + golang-standards/project-layout.

Usage

Windows (PowerShell)

.\init-service.ps1 -ServiceName point-service

Linux/macOS

chmod +x init-service.sh
./init-service.sh point-service

Custom target directory

./init-service.sh reward-service ./my-services/reward-service

Template Structure

go-service-template/
├── cmd/api/main.go                           # Entry point
├── internal/
│   ├── app/app.go                            # DI container
│   ├── config/config.go                      # Configuration
│   ├── entity/example.go                     # Domain entities
│   ├── usecase/
│   │   ├── interfaces.go                     # Repository interfaces
│   │   └── example.go                        # Business logic
│   ├── controller/http/
│   │   ├── server.go                         # HTTP server
│   │   ├── middleware.go                     # Middlewares
│   │   └── v1/                               # API v1 handlers
│   └── infrastructure/
│       ├── repository/postgres/              # PostgreSQL repos
│       ├── cache/redis/                      # Redis cache
│       └── messaging/kafka/                  # Kafka producer
├── migrations/                               # SQL migrations
├── Dockerfile
├── Makefile
├── .env.example
└── README.md

After Initializing a New Service

1. Update entity - internal/entity/example.go

   • Rename Example to your domain entity
   • Add required fields

2. Update usecase - internal/usecase/

   • Rename ExampleUseCase
   • Implement business logic

3. Update repository - internal/infrastructure/repository/postgres/

   • Rename ExampleRepository
   • Implement data access

4. Update handlers - internal/controller/http/v1/

   • Rename handlers
   • Add API endpoints

5. Update migrations - migrations/

   • Rename table examples
   • Add schema for your domain

Example: Creating a Point Service

./init-service.sh point-service

# Then:
# - Rename Example -> PointAccount, PointTransaction
# - Implement EarnPoints, RedeemPoints use cases
# - Add APIs: POST /points/earn, POST /points/redeem

Clean Architecture Layers

┌─────────────────────────────────────────┐
│           Frameworks & Drivers          │  ← infrastructure/
│         (DB, Cache, Messaging)          │
├─────────────────────────────────────────┤
│           Interface Adapters            │  ← controller/
│         (HTTP, gRPC handlers)           │
├─────────────────────────────────────────┤
│         Application Business Rules      │  ← usecase/
│              (Use Cases)                │
├─────────────────────────────────────────┤
│        Enterprise Business Rules        │  ← entity/
│              (Entities)                 │
└─────────────────────────────────────────┘

Dependency Rule

• entity/ → No dependencies
• usecase/ → Depends only on entity/, defines interfaces
• controller/ → Depends on usecase/
• infrastructure/ → Implements interfaces from usecase/

---

Tiếng Việt

Template để tạo nhanh microservice Go theo Clean Architecture + golang-standards/project-layout.

Sử dụng

Windows (PowerShell)

.\init-service.ps1 -ServiceName point-service

Linux/macOS

chmod +x init-service.sh
./init-service.sh point-service

Custom target directory

./init-service.sh reward-service ./my-services/reward-service

Cấu trúc Template

go-service-template/
├── cmd/api/main.go                           # Entry point
├── internal/
│   ├── app/app.go                            # DI container
│   ├── config/config.go                      # Configuration
│   ├── entity/example.go                     # Domain entities
│   ├── usecase/
│   │   ├── interfaces.go                     # Repository interfaces
│   │   └── example.go                        # Business logic
│   ├── controller/http/
│   │   ├── server.go                         # HTTP server
│   │   ├── middleware.go                     # Middlewares
│   │   └── v1/                               # API v1 handlers
│   └── infrastructure/
│       ├── repository/postgres/              # PostgreSQL repos
│       ├── cache/redis/                      # Redis cache
│       └── messaging/kafka/                  # Kafka producer
├── migrations/                               # SQL migrations
├── Dockerfile
├── Makefile
├── .env.example
└── README.md

Sau khi init service mới

1. Cập nhật entity - internal/entity/example.go

   • Đổi tên Example thành domain entity của bạn
   • Thêm các fields cần thiết

2. Cập nhật usecase - internal/usecase/

   • Đổi tên ExampleUseCase
   • Implement business logic

3. Cập nhật repository - internal/infrastructure/repository/postgres/

   • Đổi tên ExampleRepository
   • Implement data access

4. Cập nhật handlers - internal/controller/http/v1/

   • Đổi tên handlers
   • Thêm API endpoints

5. Cập nhật migrations - migrations/

   • Đổi tên table examples
   • Thêm schema cho domain

Ví dụ: Tạo Point Service

./init-service.sh point-service

# Sau đó:
# - Đổi Example -> PointAccount, PointTransaction
# - Implement EarnPoints, RedeemPoints use cases
# - Thêm API: POST /points/earn, POST /points/redeem

Clean Architecture Layers

┌─────────────────────────────────────────┐
│           Frameworks & Drivers          │  ← infrastructure/
│         (DB, Cache, Messaging)          │
├─────────────────────────────────────────┤
│           Interface Adapters            │  ← controller/
│         (HTTP, gRPC handlers)           │
├─────────────────────────────────────────┤
│         Application Business Rules      │  ← usecase/
│              (Use Cases)                │
├─────────────────────────────────────────┤
│        Enterprise Business Rules        │  ← entity/
│              (Entities)                 │
└─────────────────────────────────────────┘

Dependency Rule

• entity/ → Không phụ thuộc gì
• usecase/ → Chỉ phụ thuộc entity/, định nghĩa interfaces
• controller/ → Phụ thuộc usecase/
• infrastructure/ → Implement interfaces từ usecase/