{"id":19167060,"url":"https://github.com/powerman/go-service-example","last_synced_at":"2025-05-07T15:45:24.875Z","repository":{"id":38331858,"uuid":"181335293","full_name":"powerman/go-service-example","owner":"powerman","description":"Example Go service using go-swagger and Clean Architecture","archived":false,"fork":false,"pushed_at":"2023-04-13T21:57:15.000Z","size":607,"stargazers_count":172,"open_issues_count":18,"forks_count":15,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-05-06T03:58:06.000Z","etag":null,"topics":["clean-architecture","example","example-project","go","go-swagger","golang","swagger"],"latest_commit_sha":null,"homepage":null,"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/powerman.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2019-04-14T16:12:33.000Z","updated_at":"2025-04-28T07:20:11.000Z","dependencies_parsed_at":"2023-07-13T09:27:02.048Z","dependency_job_id":null,"html_url":"https://github.com/powerman/go-service-example","commit_stats":null,"previous_names":["powerman/go-service-goswagger-clean-example"],"tags_count":10,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/powerman%2Fgo-service-example","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/powerman%2Fgo-service-example/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/powerman%2Fgo-service-example/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/powerman%2Fgo-service-example/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/powerman","download_url":"https://codeload.github.com/powerman/go-service-example/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252908684,"owners_count":21823471,"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":["clean-architecture","example","example-project","go","go-swagger","golang","swagger"],"created_at":"2024-11-09T09:35:38.253Z","updated_at":"2025-05-07T15:45:24.824Z","avatar_url":"https://github.com/powerman.png","language":"Go","readme":"# Example Go service using go-swagger and The Clean Architecture\n\n[![PkgGoDev](https://pkg.go.dev/badge/github.com/powerman/go-service-example)](https://pkg.go.dev/github.com/powerman/go-service-example)\n[![Go Report Card](https://goreportcard.com/badge/github.com/powerman/go-service-example)](https://goreportcard.com/report/github.com/powerman/go-service-example)\n[![CI/CD](https://github.com/powerman/go-service-example/workflows/CI/CD/badge.svg?event=push)](https://github.com/powerman/go-service-example/actions?query=workflow%3ACI%2FCD)\n[![CircleCI](https://circleci.com/gh/powerman/go-service-example.svg?style=svg)](https://circleci.com/gh/powerman/go-service-example)\n[![Coverage Status](https://coveralls.io/repos/github/powerman/go-service-example/badge.svg?branch=master)](https://coveralls.io/github/powerman/go-service-example?branch=master)\n[![Project Layout](https://img.shields.io/badge/Standard%20Go-Project%20Layout-informational)](https://github.com/golang-standards/project-layout)\n[![Release](https://img.shields.io/github/v/release/powerman/go-service-example)](https://github.com/powerman/go-service-example/releases/latest)\n\nThis project shows an example of how to use go-swagger accordingly to\nUncle Bob's \"Clean Architecture\".\n\nAlso it includes [go-swagger JSON Schema support\ncheatsheet](docs/json-schema-cheatsheet.yml), which list all\nvalidations/annotations for JSON body actually implemented by go-swagger\nv0.18.0.\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n**Table of Contents**\n\n- [Overview](#overview)\n  - [The Clean Architecture](#the-clean-architecture)\n  - [The hexagonal architecture, or ports and adapters architecture](#the-hexagonal-architecture-or-ports-and-adapters-architecture)\n  - [Structure of Go packages](#structure-of-go-packages)\n  - [Features](#features)\n- [Development](#development)\n  - [Requirements](#requirements)\n  - [Setup](#setup)\n  - [Usage](#usage)\n    - [Cheatsheet](#cheatsheet)\n- [Run](#run)\n  - [Docker](#docker)\n  - [Source](#source)\n- [TODO](#todo)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n## Overview\n\n### The Clean Architecture\n\n[![The Clean Architecture](https://blog.cleancoder.com/uncle-bob/images/2012-08-13-the-clean-architecture/CleanArchitecture.jpg)](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html)\n\nIt's not a complete example of The Clean Architecture itself\n(business-logic of this example is too trivial, so \"Use Cases\" layer in\npackage `app` embeds \"Entities\" layer), but it does show the most relevant\npart: how to create \"API Controller\" layer in package `srv/openapi`\nbetween code auto-generated by go-swagger and \"Use Cases\" layer in package\n`app`. Also it includes \"DB Gateway\" layer in packages `dal/memory` (provided\ntrivial in-memory implementation is \"DB\" and \"Gateway\" layers at once) and\n`dal/mysql` (just \"Gateway\" layer).\n\n### The hexagonal architecture, or ports and adapters architecture\n\nIt may be even easier to understand implemented architecture as \"ports and\nadapters\":\n\n- \"ports\" are defined as interfaces in `app/app.go` - they make it\n  possible to easily test business-logic in `app` without any external\n  dependencies by mocking all these interfaces.\n- \"adapters\" are implemented in `srv/*` (serve project APIs), `dal/*`\n  (access DB) and `svc/*` (use external services) packages - they can't be\n  tested that easy, so they should be as thin and straightforward as\n  possible and try hard to do nothing than convert (\"adapt\") data between\n  format used by external world and our business-logic (package `app`).\n\n### Structure of Go packages\n\n- `api/*` - definitions of own and 3rd-party (in `api/ext-*`)\n  APIs/protocols and related auto-generated code\n- `cmd/*` - main application(s)\n- `internal/config` - configuration(s) (default values, env, flags) for\n  application(s) subcommands and tests\n- `internal/app` - define interfaces (\"ports\") and implements business-logic\n- `internal/srv/*` - adapters for served APIs/UI\n- `internal/dal/*` - adapters for data storage\n- `internal/migrations/*` - DB migrations (in both SQL and Go)\n- `internal/svc/*` - adapters for accessing external services\n- `pkg/*` - helper packages, not related to architecture and\n  business-logic (may be later moved to own modules and/or replaced by\n  external dependencies), e.g.:\n  - `pkg/def/` - project-wide defaults\n\n### Features\n\n- [X] Project structure (mostly) follows\n  [Standard Go Project Layout](https://github.com/golang-standards/project-layout).\n- [X] Strict but convenient golangci-lint configuration.\n- [X] Easily testable code (thanks to The Clean Architecture).\n- [X] Avoids (and resists to) using global objects (to make it possible to\n  embed such microservices into modular monolith).\n- [X] CLI subcommands support using [cobra](https://github.com/spf13/cobra).\n- [X] Graceful shutdown support.\n- [X] Configuration defaults can be overwritten by env vars and flags.\n- [X] CORS support, so you can play with API using Swagger Editor tool.\n- [X] Example go-swagger authentication and authorization.\n- [X] Example DAL (data access layer):\n  - [X] MySQL 5.6 (strictest SQL mode).\n- [X] Example tests, both unit and integration.\n- [X] Production logging using [structlog](https://github.com/powerman/structlog).\n- [X] Production metrics using Prometheus.\n- [X] Docker and docker-compose support.\n- [X] Smart test coverage report, with optional support for coveralls.io.\n- [X] Linters for Dockerfile and shell scripts.\n- [X] CI/CD setup for GitHub Actions and CircleCI.\n\n## Development\n\n### Requirements\n\n- Go 1.16\n- [Docker](https://docs.docker.com/install/) 19.03+\n- [Docker Compose](https://docs.docker.com/compose/install/) 1.25+\n\n### Setup\n\n1. After cloning the repo copy `env.sh.dist` to `env.sh`.\n2. Review `env.sh` and update for your system as needed.\n3. It's recommended to add shell alias `alias dc=\"if test -f env.sh; then\n   source env.sh; fi \u0026\u0026 docker-compose\"` and then run `dc` instead of\n   `docker-compose` - this way you won't have to run `source env.sh` after\n   changing it.\n\n### Usage\n\nTo develop this project you'll need only standard tools: `go generate`,\n`go test`, `go build`, `docker build`. Provided scripts are for\nconvenience only.\n\n- Always load `env.sh` *in every terminal* used to run any project-related\n  commands (including `go test`): `source env.sh`.\n  - When `env.sh.dist` change (e.g. by `git pull`) next run of `source\n    env.sh` will fail and remind you to manually update `env.sh` to match\n    current `env.sh.dist`.\n- `go generate ./...` - do not forget to run after making changes related\n  to auto-generated code\n- `go test ./...` - test project (excluding integration tests), fast\n- `./scripts/test` - thoroughly test project, slow\n- `./scripts/test-ci-circle` - run tests locally like CircleCI will do\n- `./scripts/cover` - analyse and show coverage\n- `./scripts/build` - build docker image and binaries in `bin/`\n  - Then use mentioned above `dc` (or `docker-compose`) to run and control\n    the project.\n  - Access project at host/port(s) defined in `env.sh`.\n\n#### Cheatsheet\n\n```sh\ndc up -d --remove-orphans               # (re)start all project's services\ndc logs -f -t                           # view logs of all services\ndc logs -f SERVICENAME                  # view logs of some service\ndc ps                                   # status of all services\ndc restart SERVICENAME\ndc exec SERVICENAME COMMAND             # run command in given container\ndc stop \u0026\u0026 dc rm -f                     # stop the project\ndocker volume rm PROJECT_SERVICENAME    # remove some service's data\n```\n\nIt's recommended to avoid `docker-compose down` - this command will also\nremove docker's network for the project, and next `dc up -d` will create a\nnew network… repeat this many enough times and docker will exhaust\navailable networks, then you'll have to restart docker service or reboot.\n\n## Run\n\n### Docker\n\n```\n$ docker run -i -t --rm ghcr.io/powerman/go-service-example -v\naddress-book version 0894daa 2020-09-13_19:44:26 go1.15.2\n\n$ dc up -d mysql\n$ docker run -i -t --rm \\\n    -p 8000:8000 \\\n    --net=go-service-example_default \\\n    -e EXAMPLE_APIKEY_ADMIN=secret \\\n    -e EXAMPLE_MYSQL_ADDR_HOST=mysql \\\n    -e EXAMPLE_MYSQL_AUTH_LOGIN=root \\\n    -e EXAMPLE_MYSQL_AUTH_PASS= \\\n    ghcr.io/powerman/go-service-example\n address-book: inf      main: `started` version 0894daa 2020-09-13_19:44:26\n address-book: inf   openapi: `OpenAPI protocol` version 0.2.0\n address-book: inf     serve: `serve` b3ecd12369c3:9000 [Prometheus metrics]\n address-book: inf     serve: `serve` 172.19.0.6:8000 [OpenAPI]\n address-book: inf   swagger: `Serving address book at http://172.19.0.6:8000`\n^C\n address-book: inf   swagger: `Shutting down... `\n address-book: inf   swagger: `HTTP server Shutdown: context deadline exceeded`\n address-book: inf   swagger: `Stopped serving address book at http://172.19.0.6:8000`\n address-book: inf     serve: `shutdown` [OpenAPI]\n address-book: inf     serve: `shutdown` [Prometheus metrics]\n address-book: inf      main: `finished` version 0894daa 2020-09-13_19:44:26\n```\n\n### Source\n\nUse of the `./scripts/build` script is optional (it's main feature is\nembedding git version into compiled binary), you can use usual\n`go get|install|build` to get the application instead.\n\n```\n$ ./scripts/build\n$ ./bin/address-book -h\nExample microservice with OpenAPI\n\nUsage:\n  address-book [flags]\n  address-book [command]\n\nAvailable Commands:\n  help        Help about any command\n  serve       Starts microservice\n\nFlags:\n  -h, --help                    help for address-book\n      --log.level OneOfString   log level [debug|info|warn|err] (default debug)\n  -v, --version                 version for address-book\n\nUse \"address-book [command] --help\" for more information about a command.\n\n$ ./bin/address-book serve -h\nStarts microservice\n\nUsage:\n  address-book serve [flags]\n\nFlags:\n  -h, --help                        help for serve\n      --host NotEmptyString         host to serve OpenAPI (default localhost)\n      --metrics.port Port           port to serve Prometheus metrics (default 9000)\n      --port Port                   port to serve OpenAPI (default 8000)\n      --timeout.shutdown Duration   must be less than 10s used by 'docker stop' between SIGTERM and SIGKILL (default 9s)\n      --timeout.startup Duration    must be less than swarm's deploy.update_config.monitor (default 3s)\n\nGlobal Flags:\n      --log.level OneOfString   log level [debug|info|warn|err] (default debug)\n\n$ ./bin/address-book -v\naddress-book version v1.0.0 5e45f44 2020-09-03_15:15:53 go1.15.1\n\n$ ./bin/address-book serve\n address-book: inf      main: `started` version v1.0.0 5e45f44 2020-09-03_15:15:53\n address-book: inf   openapi: `OpenAPI protocol` version 0.2.0\n address-book: inf     serve: `serve` localhost:9000 [Prometheus metrics]\n address-book: inf     serve: `serve` 127.0.0.1:8000 [OpenAPI]\n address-book: inf   swagger: `Serving address book at http://127.0.0.1:8000`\n address-book: dbg   openapi: 127.0.0.1:36500           POST    contacts: `calling AddContact` admin\n address-book: dbg       dal: 127.0.0.1:36500           POST    contacts: `contact added` admin\n address-book: inf   openapi: 127.0.0.1:36500       201 POST    contacts: `handled` admin\n address-book: dbg   openapi: 127.0.0.1:36502           POST    contacts: `calling AddContact` admin\n address-book: dbg       dal: 127.0.0.1:36502           POST    contacts: `contact added` admin\n address-book: inf   openapi: 127.0.0.1:36502       201 POST    contacts: `handled` admin\n address-book: inf   openapi: 127.0.0.1:36504       200 GET     contacts: `handled` admin\n address-book: inf   openapi: 127.0.0.1:36508       200 GET     contacts: `handled` user\n address-book: inf   openapi: 127.0.0.1:36510       401 GET     contacts: `handled`\n address-book: inf   openapi: 127.0.0.1:36518       403 POST    contacts: `handled`\n^C\n address-book: inf   swagger: `Shutting down... `\n address-book: inf   swagger: `HTTP server Shutdown: context deadline exceeded`\n address-book: inf   swagger: `Stopped serving address book at http://127.0.0.1:8000`\n address-book: inf     serve: `shutdown` [OpenAPI]\n address-book: inf     serve: `shutdown` [Prometheus metrics]\n address-book: inf      main: `finished` version v1.0.0 5e45f44 2020-09-03_15:15:53\n```\n\n## TODO\n\n- [ ] Update JSON Schema support cheatsheet to latest go-swagger version.\n- [ ] Add alternative DAL implementation for Postgresql.\n- [ ] Add cookie-based auth with CSRF middleware.\n- [ ] Add an example of adapter for external service in `svc/something`.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpowerman%2Fgo-service-example","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpowerman%2Fgo-service-example","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpowerman%2Fgo-service-example/lists"}