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 |
| Migrations | migrate | Database schema migrations |
| 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 |
| Instrumentation Generation | ./internal/otel-iface-gen | Generate instrumentation boilerplate for interfaces |
| OpenTelemetry Registry | weaver | OpenTelemetry signal registry manipulation |
Commits
Conventional Commits MUST be used.
Structure
| File/Directory | Description |
|---|---|
.github/ |
GitHub workflows and configurations |
_oas |
OpenAPI specifications |
_otel |
OpenTelemetry Registry |
cmd/ |
Main applications |
pkg/ |
Directory that MUST NOT exist |
internal/ |
Private application and library code. Most code SHOULD be here. |
internal/db/_migrations |
Database migrations are placed 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 migrations |
AGENTS.md |
Rules for LLMs. Linked to copilot-instructions.md |
.github
Dependencies files
- Dependabot configuration files with groups for otel and golang dependencies.
- Dependency review config for reviewing licenses of dependencies.
Workflows
- Commit linting
- Dependency checks
- Linting
- Tests
_oas
OpenAPI specifications.
_otel
OpenTelemetry Registry files for semantic conventions.
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.
cmd
Main application entrypoints. All commands MUST be here.
SDK
Applications SHOULD use go-faster/sdk.
Observability
Schema-driven observability that relies on code generation or compile-time checks is preferred.
- Code-generated instrumentation for interfaces
- Compile-time checks for instrumentation
- Code-generated attributes, log fields, spans
Currently, code generation from registry is not implemented.
otel-iface-gen
Code generation for OpenTelemetry instrumentation boilerplate. Used for services and database interfaces.
See internal/o11y for generated code.
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 --> pgx[postgresql Client]
subgraph "Application Layers"
Handler
Service
Model
end
subgraph "External Dependencies"
DB
pgx
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,pgx external
Handlers
Handlers are implementation of oas handlers. Call services.
Example: internal/cmd/http/handler/*.
Database
Model abstracts database entities, i.e. pgx client interactions. Also model defines entities.
Example: internal/db/*.
Models
Service implements business logic, i.e. calls models and other services.
Example: internal/service/*, task.go with interfaces.
Also contains interfaces abstracting other layers if necessary, e.g. DB.
Generated mocks
Mock generation for interfaces defined on Models layer via moq.
Generated Instrumentation
Generated instrumentation for interfaces defined on Models layer via otelifacegen.
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrTaskNotFound = errors.New("task not found")
Functions ¶
This section is empty.
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.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
example
command
|
|
|
internal
|
|
|
cmd/otel-sort
command
Binary otel-sort sorts OpenTelemetry registry bundles by group ID.
|
Binary otel-sort sorts OpenTelemetry registry bundles by group ID. |
|
db
Package entdb provides helper for creating pgx dabase for ent.
|
Package entdb provides helper for creating pgx dabase for ent. |
|
oas
Code generated by ogen, DO NOT EDIT.
|
Code generated by ogen, DO NOT EDIT. |
|
otel-iface-gen
command
|
|
|
semconv
Package semconv defines semantic conventions for OpenTelemetry, like log or trace attributes.
|
Package semconv defines semantic conventions for OpenTelemetry, like log or trace attributes. |
|
service
Package service implements the business logic of the application.
|
Package service implements the business logic of the application. |