example

README

example

Example project with best practices.

Dependency type	Tool/Library	Description
Runtime	go-faster/sdk	Application SDK with logging, metrics, tracing
Error handling	go-faster/errors	Error wrapping and handling
ORM	ent	Entity framework for Go
Migrations	atlas	Database schema migrations and management
Database	PostgreSQL 18	Reliable relational database
OpenAPI codegen	ogen	OpenAPI v3 code generator for Go
OpenAPI linter	vacuum	OpenAPI v3 linter
Mocks	moq	Generate mocks for Go interfaces

Installation

atlas

curl -sSf https://atlasgo.sh | sh

Commits

Conventional Commits MUST be used.

Structure

File/Directory	Description
.github/	GitHub workflows and configurations
_oas	OpenAPI specifications
cmd/	Main applications
pkg/	Directory that MUST NOT exist
internal/	Private application and library code. Most code SHOULD be here.
.golangci.yml	GolangCI-Lint configuration
.codecov.yml	Codecov configuration
.editorconfig	Editor configuration
Dockerfile	Dockerfile for building the application
LICENSE	License file
Makefile	Makefile with common commands
README.md	This file
generate.go	Code generation entrypoint
go.coverage.sh	Script to generate coverage report
go.mod	Go module definition. Tools are defined here.
go.sum	Go module checksums
go.test.sh	Script to run tests
migrate.Dockerfile	Docker file for ent migrations
AGENTS.md	Rules for LLMs. Linked to copilot-instructions.md
.atlas.hcl	Atlas configuration for ent migrations

.github

Dependencies files

1. Dependabot configuration files with groups for otel and golang dependencies.
2. Dependency

Workflows

• Commit linting
• Dependency checks
• Linting
• Tests

_oas

OpenAPI specifications.

generate.go

Code generation entrypoint.

go.mod

Note that tools are defined here. Example:

tool github.com/ogen-go/ogen/cmd/ogen

internal

Most code SHOULD be here.

ent

Ent ORM code.

Note entc.go and generate.go files.

atlas.hcl

Docker engine for atlas is configured as follows:

data "external_schema" "ent" {
  program = [
    "go", "tool", "ent", "schema",
    "./internal/ent/schema",
    "--dialect", "postgres",
  ]
}

env "dev" {
  dev = "docker://postgres/18/test?search_path=public"
  src  = data.external_schema.ent.url
}

To add migration named some-migration-name:

atlas migrate --env dev diff some-migration-name

schema

Ent schemas.

cmd

Main application entrypoints. All commands MUST be here.

SDK

Applications SHOULD use go-faster/sdk.

Approaches for structuring application

MVC-like

Divide application into models, views (handlers), controllers (services).

graph TB
    Client[Client/Browser] --> Handler[Handlers - Views]
    Handler --> Service[Services - Controllers]
    Service --> Model[Models]
    Model --> DB[(Database)]
    Model --> Ent[Ent Client]

    subgraph "Application Layers"
        Handler
        Service
        Model
    end

    subgraph "External Dependencies"
        DB
        Ent
    end

    Handler -.-> OAS[OAS Generated Code]
    Service -.-> BusinessLogic[Business Logic]
    Model -.-> Entities[Database Entities]

    classDef handler fill:#e1f5fe
    classDef service fill:#f3e5f5
    classDef model fill:#e8f5e8
    classDef external fill:#fff3e0

    class Handler handler
    class Service service
    class Model model
    class DB,Ent external

Handlers are implementation of oas handlers. Call services.

Model abstracts database entities, i.e. ent client interactions. Also model defines entities.

Service implements business logic, i.e. calls models and other services.

Pros

• Clear separation of concerns

Cons:

• More boilerplate code

Direct

Just handlers with business logic and ent client usage.

Pros:

• Less boilerplate code

Cons:

• Harder to test

Documentation

Index

• Variables
• type DB
• type Task

Variables

var ErrTaskNotFound = errors.New("task not found")

Types

type DB

type DB interface {
	CreateTask(ctx context.Context, title string) (*Task, error)
	ListTasks(ctx context.Context) ([]*Task, error)
	DeleteTask(ctx context.Context, id int64) error
	GenerateError(ctx context.Context) error
}

DB represents a database for tasks.

type Task

type Task struct {
	ID    int64
	Title string
}

Task models a task.