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/clean-architecture.md
View on GitHub# Clean Architecture in Go
## When to Use
Apply clean architecture when you need strong separation between business logic and infrastructure — typically medium-to-large services (2K+ lines) where testability, framework independence, and clear dependency direction matter. Do NOT use for small CLI tools or scripts.
## The Dependency Rule
Dependencies point inward only. Inner layers never import outer layers.
```
Frameworks & Drivers → Interface Adapters → Use Cases → Entities
(HTTP, DB, gRPC) (handlers, repos) (app logic) (domain)
```
Each layer defines interfaces for what it needs. Outer layers implement those interfaces.
## Project Structure
```
order-service/
├── cmd/
│ └── server/
│ └── main.go # Wiring only — builds the dependency graph
├── internal/
│ ├── entity/
│ │ ├── order.go # Order entity + business rules
│ │ ├── item.go # OrderItem
│ │ └── status.go # OrderStatus enum
│ ├── order/
│ │ ├── place.go # PlaceOrderUseCase
│ │ ├── cancel.go # CancelOrderUseCase
│ │ └── port.go # Interfaces this use case depends on
│ ├── adapter/
│ │ ├── handler/
│ │ │ └── order_handler.go # HTTP handler — calls use cases
│ │ ├── repository/
│ │ │ └── order_postgres.go # OrderRepository — implements port
│ │ └── gateway/
│ │ └── payment_client.go # External payment API client
│ └── infrastructure/
│ ├── router.go # HTTP router setup
│ ├── database.go # DB connection
│ └── config.go # Config loading
├── go.mod
└── go.sum
```
## Code Examples
### Entity — pure domain logic, zero dependencies
```go
// internal/entity/order.go
package entity
type Order struct {
ID string
Items []Item
Status OrderStatus
}
func (o *Order) Cancel() error {
if o.Status == StatusShipped {
return ErrCannotCancelShipped
}
o.Status = StatusCancelled
return nil
}
func (o *Order) Total() int64 {
var sum int64
for _, item := range o.Items {
sum += item.Price * int64(item.Quantity)
}
return sum
}
```
### Use Case — orchestrates business operations
```go
// internal/order/port.go
package order
// Ports — interfaces defined by the use case, implemented by adapters
type OrderRepository interface {
Save(ctx context.Context, order *entity.Order) error
FindByID(ctx context.Context, id string) (*entity.Order, error)
}
type PaymentGateway interface {
Charge(ctx context.Context, orderID string, amount int64) error
}
```
```go
// internal/order/place.go
package order
type PlaceOrderUseCase struct {
orders OrderRepository
payments PaymentGateway
}
func NewPlaceOrderUseCase(orders OrderRepository, payments PaymentGateway) *PlaceOrderUseCase {
return &PlaceOrderUseCase{orders: orders, payments: payments}
}
func (uc *PlaceOrderUseCase) Execute(ctx context.Context, orderID string) error {
order, err := uc.orders.FindByID(ctx, orderID)
if err != nil {
return fmt.Errorf("finding order: %w", err)
}
if err := uc.payments.Charge(ctx, order.ID, order.Total()); err != nil {
return fmt.Errorf("charging payment: %w", err)
}
order.Status = entity.StatusPlaced
return uc.orders.Save(ctx, order)
}
```
### Adapter — implements a port
```go
// internal/adapter/repository/order_postgres.go
package repository
type OrderPostgres struct {
db *sql.DB
}
func NewOrderPostgres(db *sql.DB) *OrderPostgres {
return &OrderPostgres{db: db}
}
func (r *OrderPostgres) FindByID(ctx context.Context, id string) (*entity.Order, error) {
// SQL query, scan into entity.Order
}
func (r *OrderPostgres) Save(ctx context.Context, order *entity.Order) error {
// SQL upsert
}
```
### Handler — translates HTTP to use case calls
```go
// internal/adapter/handler/order_handler.go
package handler
type OrderHandler struct {
placeOrder *usecase.PlaceOrderUseCase
}
func (h *OrderHandler) HandlePlaceOrder(w http.ResponseWriter, r *http.Request) {
orderID := chi.URLParam(r, "id")
if err := h.placeOrder.Execute(r.Context(), orderID); err != nil {
// Map domain errors to HTTP status codes
http.Error(w, err.Error(), mapToHTTPStatus(err))
return
}
w.WriteHeader(http.StatusOK)
}
```
## Key Principle
Interfaces live where they are consumed, not where they are implemented. The `usecase/order/port.go` file defines `OrderRepository` — the adapter in `adapter/repository/` implements it. This keeps the use case layer free from infrastructure imports.
## Wiring
All dependency construction happens 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 |