Go REST API Boilerplate

This Go (Golang) REST API boilerplate is not only an excellent resource for developers looking to learn Go, but also a robust, production-ready, and enterprise-grade solution. It provides a solid, clean, and well-structured foundation, making it easy to understand, customize, and use for your backend service needs in demanding production environments.

Why Choose This Boilerplate?

• Learn Go with Best Practices: Dive into Go development with a project structured to reflect industry best practices and enterprise-quality standards, ensuring you build scalable, maintainable, and production-ready applications from the outset.
• Easy to Use & Manage: Designed for simplicity and operational efficiency, this boilerplate allows you to start development immediately. Its intuitive organization and clear documentation minimize setup and onboarding time, enabling your team to focus on feature development and long-term maintenance.
• Comprehensive & Modern: Covers essential components for a modern, production-ready REST API, such as robust routing, secure authentication middleware, detailed API documentation, and a comprehensive testing suite.
• Highly Testable: Built with testability in mind, featuring a clear separation of responsibilities that simplifies unit and integration testing, ensuring your application remains reliable and stable as it grows in production environments.
• Scalable & Resilient Architecture: A clean architecture promotes ease of maintenance and allows for rapid addition of new features and application scaling without compromising code quality or performance under high load.

Project Structure

The project's directory structure is designed to enforce separation of concerns and support scalability.

• /api: Presentation layer (router, handler, middleware, DTO).
  • /dto: Data Transfer Objects (DTO) for API requests and responses.
  • /handler: Manages HTTP requests/responses.
  • /middleware: Middleware for requests (e.g., authentication, logging).
  • /router: API route definitions.
• /cmd: Application entry point.
  • /server: main function to start the server.
• /docs: API documentation files (generated by Swaggo).
• /internal: Business logic and data abstraction.
  • /app: Core application logic (service, repository, model).
  • /platform: Infrastructure components (database connections, etc.).
• /static: For any Static files (e.g., Scalar UI).
• /tests: Tests, including integration tests.
  • /integration: End-to-end tests that examine the overall application flow.

---

How to Run the Project

Prerequisites:

• Go (version 1.21 or newer)
• PostgreSQL database server based

Environment Setup:

Copy the .env.example file to .env and adjust the configuration if necessary. bash cp .env.example .env

Install Dependencies:

go mod tidy

API Documentation

This project uses swaggo/swag to automatically generate API documentation from comments.

Regenerate Documentation:

If you make changes to the API comments, regenerate the documentation with this command:

swag init -g cmd/server/main.go

Run the Server:

To run the server, ensure you are in the project's root directory and run the following command:

go run cmd/server/main.go

---

Access Documentation:

Once the server is running, you can access the Scalar UI for API documentation at: http://localhost:<port>/api/docs

Running Tests

This project features two main types of tests to ensure functionality and stability:

1. Unit Tests

• Purpose: To test individual components (e.g., functions or services) in isolation.
• Location: Resides alongside the tested code, typically in files with a _test.go suffix (example: internal/app/user/user_service_test.go).
• Characteristics: Uses mocking to isolate external dependencies (such as databases or external services), ensuring that only the logic of the unit being tested is examined.

2. Integration Tests

• Purpose: To verify how multiple components interact with each other (e.g., HTTP handlers, services, and databases).
• Location: Consolidated in the /tests/integration directory (example: tests/integration/user_flow_test.go).
• Characteristics: Tests end-to-end workflows or partial workflows, often involving interaction with real dependencies (such as a running database).

Running Tests

To run the entire test suite (both unit and integration), use the following command from the project's root directory:

go test ./... -v

This command will automatically discover and run all test files (_test.go) throughout the project, providing comprehensive test coverage.

---

Architectural Advantages

• Separation of Concerns (SoC): Code is organized by its function (api, internal, platform), making it easier to understand and maintain.
• Dependency Injection: Dependencies (like database connections) are injected into the layers that need them, facilitating testing and flexibility.
• Testability: The separated structure facilitates writing unit tests for business logic without relying on databases or HTTP layers.
• Scalability: A solid foundation allows for the rapid addition of new features without sacrificing code quality.

---

Dependencies

This project utilizes the following Go dependencies to provide core functionality:

• github.com/go-playground/validator/v10: A Go data validation library. Used for validating HTTP request input.
• github.com/gofiber/fiber/v2: A fast, expressive, and minimalist web framework for Go. Used for building RESTful APIs.
• github.com/gofiber/swagger: Swagger/OpenAPI middleware for Fiber. Used to serve API documentation generated by Swag.
• github.com/golang-jwt/jwt/v5: A JSON Web Token (JWT) implementation library for Go. Used for token-based authentication and authorization.
• github.com/joho/godotenv: A library for loading environment variables from .env files. Used for managing application configuration.
• github.com/stretchr/testify: A set of easy-to-use utilities for Go testing. Used for writing unit and integration tests.
• github.com/swaggo/swag: A tool to automatically generate Swagger/OpenAPI documentation from Go code. Used to generate API specifications.
• golang.org/x/crypto: A collection of cryptographic packages from Go. Used for password hashing and other cryptographic operations.
• gorm.io/driver/postgres: PostgreSQL driver for GORM. Used for interacting with PostgreSQL databases.
• gorm.io/gorm: A powerful and developer-friendly ORM for Go. Used for database management and object-relational mapping.