Solizardking/clawd-bot / .agents/skills/golang-design-patterns
golang-design-patterns
VerifiedIdiomatic Golang design patterns — functional options, constructors, error flow and cascading, resource management and lifecycle, graceful shutdown, resilience, architecture, dependency injection, data handling, streaming, and more. Apply when explicitly choosing between architectural patterns, implementing functional options, designing constructor APIs, setting up graceful shutdown, applying resilience patterns, or asking which idiomatic Go pattern fits a specific problem.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 11.4 KB |
| evals/evals.json | config | 20.3 KB |
| references/architecture.md | markdown | 4.7 KB |
| references/clean-architecture.md | markdown | 5.0 KB |
| references/data-handling.md | markdown | 1.6 KB |
| references/ddd.md | markdown | 6.8 KB |
| references/hexagonal-architecture.md | markdown | 6.0 KB |
| references/resource-management.md | markdown | 4.0 KB |
references/hexagonal-architecture.md
View on GitHub# Hexagonal Architecture (Ports & Adapters) in Go
## When to Use
Apply hexagonal architecture when a service interacts with multiple external systems (databases, APIs, message queues, caches) and you want the domain logic fully decoupled from all of them. Particularly effective when the same business logic needs multiple entry points (HTTP, gRPC, CLI, message consumer). Do NOT use for simple CRUD apps or libraries.
## Core Concepts
- **Domain** — Business logic and types. No external dependencies.
- **Ports** — Interfaces that define how the domain interacts with the outside world.
- **Primary (driving) ports**: How the outside world calls into the domain (e.g., `OrderService` interface).
- **Secondary (driven) ports**: How the domain calls out to infrastructure (e.g., `OrderRepository`, `PaymentGateway` interfaces).
- **Adapters** — Concrete implementations of ports.
- **Primary adapters**: HTTP handlers, gRPC servers, CLI commands — they call primary ports.
- **Secondary adapters**: PostgreSQL repository, Stripe client, Redis cache — they implement secondary ports.
## Project Structure
```
order-service/
├── cmd/
│ ├── server/
│ │ └── main.go # HTTP server wiring
│ └── worker/
│ └── main.go # Message consumer wiring
├── internal/
│ ├── domain/
│ │ ├── order.go # Order entity + business rules
│ │ ├── item.go # OrderItem
│ │ └── status.go # OrderStatus enum
│ ├── port/
│ │ ├── incoming.go # Primary ports (OrderService interface)
│ │ └── outgoing.go # Secondary ports (OrderRepository, PaymentGateway)
│ ├── service/
│ │ └── order_service.go # Implements primary ports — orchestrates domain + secondary ports
│ └── adapter/
│ ├── primary/
│ │ ├── http/
│ │ │ ├── router.go
│ │ │ └── order_handler.go # HTTP adapter — calls OrderService
│ │ └── grpc/
│ │ └── order_server.go # gRPC adapter — calls OrderService
│ └── secondary/
│ ├── postgres/
│ │ └── order_repo.go # Implements OrderRepository
│ └── stripe/
│ └── payment.go # Implements PaymentGateway
├── go.mod
└── go.sum
```
## Code Examples
### Domain — pure business logic
```go
// internal/domain/order.go
package domain
type Order struct {
ID string
Items []Item
Status OrderStatus
}
func (o *Order) Ship() error {
if o.Status != StatusPaid {
return ErrOrderNotPaid
}
o.Status = StatusShipped
return nil
}
```
### Ports — interfaces defined separately from implementations
```go
// internal/port/incoming.go
package port
// Primary port — how the outside world drives the application
type OrderService interface {
PlaceOrder(ctx context.Context, items []domain.Item) (string, error)
ShipOrder(ctx context.Context, orderID string) error
GetOrder(ctx context.Context, orderID string) (*domain.Order, error)
}
```
```go
// internal/port/outgoing.go
package port
// Secondary ports — how the application reaches external systems
type OrderRepository interface {
Save(ctx context.Context, order *domain.Order) error
FindByID(ctx context.Context, id string) (*domain.Order, error)
}
type PaymentGateway interface {
Charge(ctx context.Context, orderID string, amount int64) error
}
```
### Service — implements primary port, depends on secondary ports
```go
// internal/service/order_service.go
package service
type orderService struct {
orders port.OrderRepository
payments port.PaymentGateway
}
func NewOrderService(orders port.OrderRepository, payments port.PaymentGateway) port.OrderService {
return &orderService{orders: orders, payments: payments}
}
func (s *orderService) PlaceOrder(ctx context.Context, items []domain.Item) (string, error) {
order := domain.NewOrder(items)
if err := s.payments.Charge(ctx, order.ID, order.Total()); err != nil {
return "", fmt.Errorf("charging payment: %w", err)
}
if err := s.orders.Save(ctx, order); err != nil {
return "", fmt.Errorf("saving order: %w", err)
}
return order.ID, nil
}
```
### Primary Adapter — HTTP handler calls the service port
```go
// internal/adapter/primary/http/order_handler.go
package http
type OrderHandler struct {
svc port.OrderService
}
func NewOrderHandler(svc port.OrderService) *OrderHandler {
return &OrderHandler{svc: svc}
}
func (h *OrderHandler) HandlePlaceOrder(w http.ResponseWriter, r *http.Request) {
var req PlaceOrderRequest
if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
http.Error(w, "invalid request", http.StatusBadRequest)
return
}
id, err := h.svc.PlaceOrder(r.Context(), req.Items)
if err != nil {
http.Error(w, err.Error(), mapToHTTPStatus(err))
return
}
json.NewEncoder(w).Encode(map[string]string{"id": id})
}
```
### Secondary Adapter — implements a driven port
```go
// internal/adapter/secondary/postgres/order_repo.go
package postgres
type OrderRepo struct {
db *sql.DB
}
func NewOrderRepo(db *sql.DB) *OrderRepo {
return &OrderRepo{db: db}
}
func (r *OrderRepo) Save(ctx context.Context, order *domain.Order) error {
// SQL upsert
}
func (r *OrderRepo) FindByID(ctx context.Context, id string) (*domain.Order, error) {
// SQL query
}
```
## Multiple Entry Points
The hexagonal approach shines when the same `OrderService` is called from different primary adapters — HTTP for external clients, gRPC for internal services, a message consumer for async events. Each adapter is wired in its own `cmd/` entry point.
## Wiring
Construct adapters and inject them in `cmd/server/main.go`. → See `samber/cc-skills-golang@golang-dependency-injection` skill for DI library alternatives.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |