Blaze V2

After a lot of using the original template in small and big projects, i am now ready to roll out this big overhaul of Blaze that will change how the project is structured and layered. I decided to prioritize Developer Experience over anything else, reducing frictions, iteration time and of course encouraging cleaner and more idiomatic codebases.

This will probably be the "final form" for this template as all the updates from now on will be deps upgrades and bug fixes. If one day i feel like changing things around or doing some "breaking changes" (even if this is not a library of course) i will do it in a 3.x release.

1. Routers and services

• All the "plumbing", startup and initialziation of the application dependencies and services is done in the init.go file
• API handlers and business logic are now separate and layered
• New internal structure: /routers contains API routes and handlers (so all the HTTP logic) and those will call services (only business logic) functions under the /services folder

Layers: init.go -> routers -> services -> storage, mailer etc. (pkgs)

This change makes working in large projects much more cleaner and enjoyable, without adding too much abstraction layers. There is no routes.go file anymore as the routes are now mounted inline with their handlers in /routers, reducing developer friction when adding new routes and services.

Business logic is the most important thing of your backend so it must be clean, readable and easily testable.

2. Error handling

In v2 all domain errors are separate from API errors: the business layer (services) will never know it is an HTTP handler. Its just a function.

• All errors between service and router layer are standard Go errors
• All custom errors returned from services can be declared under new internal folder /domain
• When the router returns an error by using the Blaze RenderError util, it will first check if the error is mapped in init.go and if it is not it will render a generic 500 Internal error with error message attached to it
• It is possible to map any standard go error to a corresponding ApiError in the error map in init.go

This is much more idiomatic and cleaner than the previous version. This way we can have a nice overview of all the errors that our backend can return and will encourage the developer to declare more detailed errors than before. Also it is much easier to unit test services and check for errors.

3. SQL and migrations

• The starter template (repo) now contains a basic CRUD example using sqlx and sqlite3 (pkg/storage)
• Migrations are by default under /db folder and will be included in the built binary using standard go:embed FS
• At application startup (init.go) all the migrations will be automatically applied using goose

The dev can of course remove all SQL and storage things from the starter template if it is not needed. I decided to include all this new scaffolding for migration, db etc. as 90% of web backends need these.

4. Minor changes and improvements

• Changed httpcore pkg containing all the main utils to power the API to httpx (much more idiomatic and adheres to Go conventions)
• Stricter linting
• Better Environment variables handling
• Upgrade to Go 1.23

Full Changelog: v1.3.0...v2.0.0

New for version v1.3.0

Better Env variable validation

• Changed syntax for internal environment variable initialization (see internal/api/env.go)
• More declarative and simple initialization for EnvConfig struct
• New function: GetEnvOrDefault to set the env to a default value instaed of panicking with GetEnvOrPanic
• This somehow decreased by a little bit the server startup time

Default CORS configuration

• Added default CORS config in httpcore
• New config now comes with MaxAge header set by default (for HTTP browser caching)

Other

• Upgrade all dependencies

Full Changelog: v1.2.0...v1.3.0

New for version v1.2.0

Better HTTP errors handling

• New method for ApiError for better HTTP error handling: .With() to append a Go error to the API error message
• .Msg() method for ApiError now appends a string to the API error message instaed of an error (use With to append errors)
• Breaking: if you want to upgrade your app to this new version you need to migrate old error handling using the new methods.
• You can find examples on how to use them in the official wiki

Init logic and handler refactoring

• Router initialization with default middlewares (timeout, panic recovery, logger...) has been moved in api/init.go for better readability and consistency (instaed of pkg/httpcore/router)
• HTTP Handlers has been moved in /handlers package to scale better when adding many handlers for different business logic domains

Minor improvements

• Removed useless allocations when replying with an ApiError

Full Changelog: v1.1.0...v1.2.0

What's Changed

• Support for Go 1.22
• New structued logging with zerolog, faster and more idiomatic
• Added several strict linting rules and updated golangci-lint config
• Upgraded all direct and indirect packages
• Fixed security issues (bump dependencies)
• Changed AWS Lambda base image to the newer provided.al2023 (faster and lighter) in serverless branch
• Improved example OpenAPI template

Full Changelog: v1.0.0...v1.1.0

Full Changelog: https://github.com/paologaleotti/blaze/commits/v1.0.0