{"id":23223357,"url":"https://github.com/imantung/boilerplate-go-backend","last_synced_at":"2025-04-05T16:33:09.668Z","repository":{"id":240934112,"uuid":"803815652","full_name":"imantung/boilerplate-go-backend","owner":"imantung","description":"Boilerplate project for golang backend","archived":false,"fork":false,"pushed_at":"2024-05-22T06:18:21.000Z","size":30,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-05-22T14:36:28.993Z","etag":null,"topics":["backend","boilerplate","go"],"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/imantung.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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-05-21T12:40:19.000Z","updated_at":"2024-05-28T06:07:26.302Z","dependencies_parsed_at":"2024-05-28T06:22:37.789Z","dependency_job_id":null,"html_url":"https://github.com/imantung/boilerplate-go-backend","commit_stats":null,"previous_names":["imantung/boilerplate-go-backend"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imantung%2Fboilerplate-go-backend","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imantung%2Fboilerplate-go-backend/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imantung%2Fboilerplate-go-backend/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imantung%2Fboilerplate-go-backend/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/imantung","download_url":"https://codeload.github.com/imantung/boilerplate-go-backend/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247365614,"owners_count":20927363,"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":["backend","boilerplate","go"],"created_at":"2024-12-18T23:17:08.960Z","updated_at":"2025-04-05T16:33:09.644Z","avatar_url":"https://github.com/imantung.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Boilerplate Go Backend\n\nBoilerplate for golang backend project. \n\n## Prerequisite\n\n- Programming Language: [Go](https://go.dev/) \n- Task Manager/Build-Tool: [GoTask](https://taskfile.dev/)\n- DB Migration Tool: [Golang-Migrate](https://github.com/golang-migrate/migrate/tree/master/cmd/migrate)\n- Infrastructure: [Docker](https://www.docker.com/)\n\n## Getting Started\n```bash\n# First setup for mac (for other OS, please refer to respective documentation)\nbrew install go\nbrew install go-task\nbrew install golang-migrate\n\ntask --list-all   # Show available tasks\ntask run          # Run the project\ntask clean        # Clean the dev local environment\n\ntask gen-oapi        # Generate open-api controller from api-spec.yaml\ntask gen-dotenv      # Generate .env file from config struct\ntask gen-entity      # Generate entity/repo from database table\ntask gen-converter   # Generate converter from DAO to Entity and vice-versa\n\ntask create-migration NAME=create_some_table   # Create new migration file\n```\n\n## Tech Overview\n\nFramework/library:\n- [Echo](https://echo.labstack.com/): High performance, minimalist Go web framework\n- [OApi-CodeGen](https://github.com/oapi-codegen/oapi-codegen): Generate Go client and server boilerplate from OpenAPI 3 specifications\n- [Go-Auth2](https://github.com/go-oauth2/oauth2): OAuth 2.0 server library for the Go programming language\n- [Go-Mock](https://github.com/uber-go/mock): a mocking framework for the Go programming language\n- [Dig](https://github.com/uber-go/dig): A reflection based dependency injection toolkit for Go.\n- [Squirrel](https://github.com/Masterminds/squirrel): Fluent SQL generation for golang\n- [Zerolog](https://github.com/rs/zerolog): Zero Allocation JSON Logger\n\nDatabase:\n- Relational Database: [Postgres](https://www.postgresql.org/) \n- In-Memory Database: [Redis](https://redis.io/)\n\n## Project Checklist\n\n- General\n  - [x] [Golang Standards Project Layout](https://github.com/golang-standards/project-layout)\n  - [x] [Dependency Injection](https://en.wikipedia.org/wiki/Dependency_injection) with [Uber Dig](https://github.com/uber-go/dig) -- Check the code at [internal/app/infra/di/di.go](internal/app/infra/di/di.go)\n  - [x] Centralized config (env variable) -- Check the code at [internal/app/infra/config/config.go](internal/app/infra/config/config.go)\n  - [x] Graceful Shutdown -- Check the code at [cmd/boilerplate-go-backend/main.go](cmd/boilerplate-go-backend/main.go)\n  - [x] Health check -- Check the code at [internal/app/health.go](internal/app/health.go)\n- API Server\n  - [x] [OpenAPI Specification 3.0](https://swagger.io/resources/open-api/) -- Check the specification at [api/api-spec.yml](api/api-spec.yml)\n    - [x] Enable [swagger-ui](https://github.com/swagger-api/swagger-ui) (`/swagger/ui`)\n  - [x] [Echo Framework](https://echo.labstack.com/)  -- Check the router at [internal/app/router.go](internal/app/router.go)\n    - [x] [Recovery from panic](https://echo.labstack.com/docs/middleware/recover)\n    - [x] [Generate Request ID](https://echo.labstack.com/docs/middleware/request-id)\n    - [x] [Protection against XSS attack and other common security threats](https://echo.labstack.com/docs/middleware/secure)\n    - [x] Custom error handler\n    - [ ] Server-Side Cache (Redis)\n    - [ ] Rate Limiter (Redis)\n- [RESTful API](https://en.wikipedia.org/wiki/REST)\n  - [x] `POST` Create operation \n  - [x] `GET` Read operation \n    - [x] Single entity\n    - [x] Entity List\n    - [ ] Pagination\n    - [ ] Search / Filtering\n    - [ ] Sorting\n  - [x] `UPDATE` Update operation\n  - [x] `PATCH` Partially update operation\n  - [x] `DELETE` Delete operation\n    - [x] Soft-Delete\n    - [x] Idempotent\n- [Layered Architecture](https://herbertograca.com/2017/08/03/layered-architecture/)\n   -  [x] Controller Layer -- Generated by [oapi-codegen](https://github.com/deepmap/oapi-codegen)\n   -  [x] Business Logic Layer (Services) -- Check the code at [internal/app/service](internal/app/service)\n      - [x] Validation Logics\n      - [x] Trigger Database Transaction (`BEGIN`) -- Check [dbtxn](https://github.com/imantung/dbtxn) library\n   -  [x] Data Access Layer (Repos) - Generated by [tools/entity-gen](tools/entity-gen)\n      - [x] ORMHate Philosophy\n      - [x] Query Builder (using [Squirrel](https://github.com/Masterminds/squirrel))\n- Database\n  - [x] Connection pool -- Check the code at [internal/app/infra/database/postgres.go](internal/app/infra/database/postgres.go)\n  - [x] Audit Columns (`created_at`, `modified_at`, etc)\n  - [x] Migration tool with [golang-migrate](https://github.com/golang-migrate/migrate)\n  - [x] Data seeding to insert initial dummy data to database -- Check the tool at [tools/dbseed](tools/dbseed)\n  - [ ] User AuditTrail (Transaction Logs)\n- Security and Observability\n  - [x] Basic Auth -- Check the code at [internal/app/infra/auth/basic.go](internal/app/infra/auth/basic.go)\n  - [x] OAuth2 with [Go-OAuth2](https://github.com/go-oauth2/oauth2) \n    - [x] Use Postgres to store oauth-client -- Check the code at [internal/app/infra/auth/oauth_client_store.go](internal/app/infra/auth/oauth_client_store.go)\n    - [ ] Use Redis to store oauth-token\n    - [x] Handle authorize request and token access\n    - [x] Validate bearer token and scope access -- Check the code at [internal/app/infra/auth/oauth_handler.go](internal/app/infra/auth/oauth_handler.go)\n  - [x] Enable [expvar](https://pkg.go.dev/expvar) endpoint (`/debug/vars`) \n  - [x] Enable [pprof](https://pkg.go.dev/net/http/pprof) endpoint (`/debug/pprof`)\n  - [x] Structured Log with [ZeroLog](https://github.com/rs/zerolog) -- Check the code at [/internal/app/infra/logger](/internal/app/infra/logger)\n    - [x] Pretty format (not json) when debug enabled\n    - [x] Escalate log level to `WARN` for slow API\n    - [x] Append log field `pid` \n    - [x] Append log field `go_version`\n    - [x] Append log field `latency` \n    - [x] Append log field `request_id`\n    - [x] Append log field `user_id`\n  - [ ] Open Tracing\n- Code Generator\n  - [x] Generate Server Interface and Controller Layer with [oapi-codegen](https://github.com/deepmap/oapi-codegen) -- Check the config at [tools/openapi-gen](tools/openapi-gen) \n  - [x] Generate Dotenv file from Config struct -- Check the tool at [tools/dotenv-gen](tools/dotenv-gen)\n  - [x] Generate Entity Model and Repository Layer from Database schema -- Check the tool at [tools/entity-gen](tools/entity-gen)\n  - [x] Generate Converter from DAO to Entity and vice-versa -- Check the tool at [tools/converter-gen](tools/converter-gen)\n- Testing\n  - [x] Table Driven Test -- Check the code at [internal/app/service/employee_svc_test.go](internal/app/service/employee_svc_test.go)\n  - [x] Mocking object with [GoMock](https://github.com/golang/mock)\n  - [ ] API Test Automation\n- Others\n  - [x] Build tool with [TaskFile](https://taskfile.dev/) (a better alternative from [GNU Make](https://www.gnu.org/software/make/))\n  - [x] Dockerfile \n  - [x] Docker-compose\n\n## Study Case: Employee Clocking System\n\nThe project use employee clocking system as the study case\n- Client App API\n  - [x] Clock-in\n  - [x] Clock-out\n- Backoffice Dashboard API\n  - [x] Manage Employee\n  - [x] Employee Clock History\n\n## Notes \n\n- The project is OPINIONATED based on author knowledge and experience\n- The project is PRAGMATIC, it use proven libraries/frameworks as much as possible without reinvented the wheel\n- The project is MONOLITH BACKEND, you may need to customize code for microservices needs\n- This is CONTINUOUS PROJECT, the author use it as his actual work and keep improve it\n- The project is OPEN-FOR-DISCUSSION, feel free to ping the author for any feedback/question and/or open issue ticket\n\n## FAQ\n\n1. Echo VS Fiber? \n\n    [Fiber](https://github.com/gofiber/fiber) is arguably better than [Echo](https://echo.labstack.com/) but is not compatible with [net/http](https://pkg.go.dev/net/http) (it is based on [fasthttp](https://github.com/valyala/fasthttp)). We use [go-oauth2](https://go-oauth2.github.io/) who only support `net/http`, therefore we choose to use Echo instead. \n\n2. Pgx for postgres? \n\n    [Pgx](https://github.com/jackc/pgx) is a faster and more compatible postgres driver compared with [pq](https://github.com/lib/pq). There are 2 ways to use pgx: through [database/sql](https://pkg.go.dev/database/sql) and direct implementation (which offer more capability) but not compatible with `database/sql`. We want to keep compatibility with `database/sql` to give flexibility to use other library.\n\n## Author\n\n\u003ciman.tung@gmail.com\u003e\n\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimantung%2Fboilerplate-go-backend","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fimantung%2Fboilerplate-go-backend","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimantung%2Fboilerplate-go-backend/lists"}