Go Template

A minimal Go project template with database schema management and code generation.

Technology Stack

Tech	Version
Go	1.26.0
GORM	1.25.11
oapi-codegen	2.6.0
Atlas	1.1.0
TypeSpec	1.10.0
MySQL	8.4.5

Project Structure

.
├── cmd/                  # Application entrypoints
├── db/                   # Database schema definitions
│   ├── main.sql          # Schema entrypoint that includes files from tables/
│   └── tables/           # Individual table DDL files
├── internal/             # Private application code (not intended for external use)
│   ├── application/      # Use cases / application services
│   ├── domain/           # Domain models and business logic
│   ├── handler/          # Transport layer (e.g. HTTP handlers)
│   │   └── gen/          # Code generated from OpenAPI specifications
│   └── interface/        # Implementations for external systems
│       └── mysql_gen/    # Code generated by GORM Gen
│           ├── model/    # Struct models mapped to database tables
│           └── query/    # Type-safe query builders
├── pkg/                  # Reusable shared packages
│   ├── config/           # Configuration loading
│   └── logger/           # Logger setup
├── openapi/              # OpenAPI specifications generated from TypeSpec
│   ├── schema/           # Database schema exported by Atlas
│   └── html/             # HTML documentation generated from OpenAPI specifications
├── typespec/             # TypeSpec files
└── scripts/              # Development scripts

Tools

This project uses the following tools:

General tools:

• mise: A tool for managing development environments and dependencies
• lefthook: A Git hooks manager
• commitlint: A tool to lint commit messages
• prettier: A code formatter for other languages
• typespec: A tool for designing APIs and generating OpenAPI specifications
• openapi-generate-html: A tool to generate HTML documentation from OpenAPI specifications

Go tools:

• golangci-lint: A Go linters aggregator
• oapi-codegen: A tool to generate Go code from OpenAPI specifications
• air: A live reloading tool for Go applications
• atlas: A database schema management tool
• GORM gen: A code generation tool for GORM

Setup

To set up the Go template project, run the following command to install all dependencies and tools:

mise install
mise install-tools

Usage

OpenAPI Code Generation

Generates Go code from the OpenAPI specifications located in openapi/schema/. The generated code is placed under internal/handler/gen/.

mise oapi-gen

GORM gen

Generates data models from the tables registered in scripts/gorm_gen/main.go.

mise gorm-gen

Atlas

Exports the database schema from the running MySQL container to schema/.

mise atlas-inspect

Runs declarative migrations based on the DDL files located in db/.

mise atlas-apply

TypeSpec

First, run mise typespec-install to install TypeSpec dependencies.

Then generates OpenAPI specifications from the TypeSpec files located in typespec/src.

mise typespec-compile

OpenAPI Generate HTML

Generates HTML documentation from the OpenAPI specifications located in openapi/schema/.

mise swagger-build

Run mise swagger-serve to host the documentation at http://localhost:6608.