repository·master·Indexed 20 days ago
https://github.com/allaboutapps/go-starterA foundational template and boilerplate for building Go applications using standard Go patterns. It includes support for generating Go types from OpenAPI/Swagger specifications, database schema diagram generation via SchemaCrawler, and database migrations using sql-migrate. The project follows standard Go project layout conventions with specific directories for internal logic (/internal), reusable packages (/pkg), and web assets (/web), and utilizes Cobra for CLI management.
The /web directory is the central location for all web-specific components. Use this directory to manage:
This structure follows the golang-standards/project-layout convention.
The /internal/types directory contains autogenerated go-swagger types and validations.
Important: Do not place your own files in this directory. These types are derived from the Swagger OpenAPI specifications located in ../api/**/*.yml and are updated automatically when running make.
The project follows standard Go project layout conventions for organizing code based on reusability and visibility:
/cmd: Contains the main applications (entry points). Keep logic minimal here./pkg: Contains code that is intended to be imported and reused by other projects./internal: Contains code that is not intended for external reuse. Code in this directory is protected by the Go compiler and cannot be imported by outside packages.When deciding where to place code, ask if it should be reusable. If yes, use /pkg. If no, or if you want to explicitly prevent reuse, use /internal.
Instead of manually managing the lifecycle of database transactions (using db.BeginTx, db.Commit, and db.Rollback), use db|dbUtil.WithTransaction.
This approach is safer and is enforced by a custom linter to prevent common transaction management errors. Manual management should only be used in exceptional cases where you can opt-out via linter excludes.
The final /api/swagger.yml file is an auto-generated aggregate composed of three distinct parts:
/api/config/main.yml./api/paths/*.yml./api/definitions/*.yml that are referenced by the skeleton or path specifications.When adding new endpoints or data models, ensure they are placed in the correct directory so they are included in the final generated specification.
The /internal directory contains private application and library code that is not intended to be imported by external applications or libraries. This is enforced by the Go compiler.
While the directory is private, it is organized into sub-packages to separate concerns. For larger projects, you can further distinguish between application-specific code (e.g., /internal/app/myapp) and shared internal code (e.g., /internal/pkg/myprivlib).
The /internal/models directory contains autogenerated SQLBoiler models.
Important: Do not place your own files in this directory. These models are derived from the database schema defined in ../migrations/*.sql and are updated automatically when running make.
To start developing with go-starter, use the provided docker-helper.sh to launch a Docker Compose-based development environment. This setup uses VSCode DevContainers, meaning you do not need a local Go toolchain installed on your host machine.
ms-vscode-remote.remote-containers)# Clone your new repository, cd into it, then start the dev environment
./docker-helper.sh --upIn version 25.04.0, fixtures were moved to dedicated packages. This is a BREAKING change.
internal/data/ to internal/data/fixtures.internal/test/ to internal/test/fixtures.Action Required: Update all imports in your project that reference the old fixture locations to point to the new fixtures sub-packages.
When the project requires a Go version bump (e.g., upgrading from v1.16.2 to v1.16.3), you must rebuild the environment using the helper script.
./docker-helper.sh --rebuildTo support automated dependency injection, you must move away from initializing components via methods on the Server struct (e.g., func (s *Server) InitPush() error). Instead, you must define providers following the Google Wire guidelines.
A provider is an ordinary function that accepts necessary dependencies as input parameters and returns an initialized component. If a provider cannot reside in its dedicated package, place it in providers.go.
Example Provider:
func NewPush(cfg config.Server, db *sql.DB) (*push.Service, error) {
// initialization logic
}func NewPush(cfg config.Server, db *sql.DB) (*push.Service, error) {
// ...
}