{"id":25120435,"url":"https://github.com/mathcale/go-api-boilerplate","last_synced_at":"2025-04-02T14:41:18.601Z","repository":{"id":253732130,"uuid":"844354062","full_name":"mathcale/go-api-boilerplate","owner":"mathcale","description":"A slightly opinionated HTTP API boilerplate with the Go programming language","archived":false,"fork":false,"pushed_at":"2025-03-01T03:26:25.000Z","size":106,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-01T22:01:04.795Z","etag":null,"topics":["api","authentication","boilerplate","clean-architecture","golang","rest-api"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mathcale.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-19T04:43:10.000Z","updated_at":"2025-03-13T17:32:44.000Z","dependencies_parsed_at":"2025-02-23T04:19:29.156Z","dependency_job_id":"29bb4db7-5fd6-4a33-84c1-2c412419a989","html_url":"https://github.com/mathcale/go-api-boilerplate","commit_stats":null,"previous_names":["mathcale/go-api-boilerplate"],"tags_count":0,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mathcale%2Fgo-api-boilerplate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mathcale%2Fgo-api-boilerplate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mathcale%2Fgo-api-boilerplate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mathcale%2Fgo-api-boilerplate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mathcale","download_url":"https://codeload.github.com/mathcale/go-api-boilerplate/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246834218,"owners_count":20841500,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","authentication","boilerplate","clean-architecture","golang","rest-api"],"created_at":"2025-02-08T05:29:26.449Z","updated_at":"2025-04-02T14:41:18.596Z","avatar_url":"https://github.com/mathcale.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- markdownlint-disable MD029 --\u003e\n# Go API Boilerplate\n\nA slightly opinionated HTTP API boilerplate with the Go programming language, following (some) Clean Architecture principles.\n\n[![Continuous Integration](https://github.com/mathcale/go-api-boilerplate/actions/workflows/ci.yaml/badge.svg)](https://github.com/mathcale/go-api-boilerplate/actions/workflows/ci.yaml)\n[![Go Report Card](https://goreportcard.com/badge/github.com/mathcale/go-api-boilerplate)](https://goreportcard.com/report/github.com/mathcale/go-api-boilerplate)\n![Go Version](https://img.shields.io/badge/go%20version-%3E=1.24-61CFDD.svg)\n[![MIT License](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)\n\n## Features\n\n- HTTP server with [net/http](https://pkg.go.dev/net/http#hdr-Servers);\n- Testing suites, assertions and mocks with [testify](https://github.com/stretchr/testify);\n- Live reload with [air](https://github.com/air-verse/air);\n- Logging with [zerolog](https://github.com/rs/zerolog);\n- Configuration with [viper](https://github.com/spf13/viper);\n- PostgreSQL database connection with [pgx](https://github.com/jackc/pgx) and [sqlx](https://github.com/jmoiron/sqlx)\n- Pre-configured CI job with Github Actions;\n- JWT authentication (under the [`with-auth`](../../tree/with-auth) branch)\n\n## Project structure\n\n```plaintext\n.\n├── cmd\n│   └── api                    \u003c== Application entrypoint\n├── config                     \u003c== Configurations setup\n├── docs                       \u003c== Auto-generated OpenAPI documents\n├── internal\n│   ├── domain                 \u003c== Domain objects with their own contracts and business logic\n│   ├── infra                  \u003c== Everything related to the infrastructure layer, such as databases, web handlers, queues etc\n│   │   ├── database\n│   │   │   ├── models         \u003c== Objects representing database entities\n│   │   │   └── repositories   \u003c== Database operations and queries\n│   │   ├── gateways           \u003c== Objects that encapsulates access to infra resources, following an interface defined by each use-case\n│   │   └── web                \u003c== Everything related to the HTTP REST API\n│   │       ├── handlers       \u003c== \"Controllers\"\n│   │       │   └── dto        \u003c== Input and output objects\n│   │       └── middlewares    \u003c== Request middlewares\n│   ├── pkg                    \u003c== Shared code that doesn't contain business logic, but are needed to support other packages\n│   │   ├── apierror           \u003c== Error returned to the API client\n│   │   ├── apperror           \u003c== Internal error object\n│   │   ├── di                 \u003c== Dependency injection resolver, where everything is glued together\n│   │   └── logger             \u003c== Logging utilities\n│   ├── tests                  \u003c== Testing utilities\n│   │   ├── fixtures           \u003c== Pre-built objects for test cases\n│   │   └── mocks              \u003c== Methods mocks for necessary packages\n│   └── usecases               \u003c== Main business rules\n│       └── counter\n├── migrations                 \u003c== Database migrations generated with `migrate`\n├── scripts                    \u003c== Utilitarian shell scripts\n```\n\n## Requirements\n\n- [Go](https://go.dev/) 1.24 (or newer)\n- [GNU Make](https://www.gnu.org/software/make/)\n- [Docker](https://www.docker.com/)\n- [air](https://github.com/air-verse/air): live-reloading\n- [migrate](https://github.com/golang-migrate/migrate): database migrations\n\n## First run\n\n1. Create .env file\n\n```sh\ncp .env.example .env\n```\n\n2. Rename packages to your project's name\n\n```sh\nmake rename-pkgs\n```\n\n3. Run setup script\n\n```sh\nmake setup\n```\n\n## Running locally\n\nTo start a local server with live-reload and all necessary containers, execute:\n\n```sh\nmake run\n```\n\n## Testing\n\nTo execute all test suites and get a coverage report at the end, just run:\n\n```sh\nmake test\n```\n\n## Building for production\n\n### With Docker\n\nThere's a `Dockerfile.prod` included with the project to build an optimized image based on [distroless](https://github.com/GoogleContainerTools/distroless), so you just need to adapt it for your needs and publish to your desired registry.\n\n```sh\n# This should be set by your CI/CD system\nexport BUILD_ID=\"$(uuidgen)\"\n\n# Building the image\ndocker build . \\\n  -t mathcale/go-api-boilerplate \\\n  -f Dockerfile.prod \\\n  --build-arg BUILD_ID\n\n# Clean intermediate images\ndocker image prune \\\n  --filter label=stage=builder \\\n  --filter label=build=$BUILD_ID\n```\n\n### Manually\n\nBy running the following command, the application will be compiled and outputted to the `bin` directory.\n\n```sh\nmake build\n```\n\n## Next Steps\n\n- [X] Add database connection\n- [X] Add logging middleware\n- [X] Add Github Actions CI workflow\n- [X] Add database\n- [X] Add authentication branch\n- [X] Add OpenAPI specs on web handlers\n- [ ] Improve project structure documentation\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmathcale%2Fgo-api-boilerplate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmathcale%2Fgo-api-boilerplate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmathcale%2Fgo-api-boilerplate/lists"}