feat: add pkg/

.golangci.yml

@@ -26,7 +26,7 @@ run:
   # "/" will be replaced by current OS file path separator to properly work
   # on Windows.
   skip-dirs:
-    - old
+    #- old
     - "^api/(.*/)?(client|model|restapi)$"
 
   # default is true. Enables skipping of directories:
@@ -153,6 +153,8 @@ linters-settings:
         paramsOnly: true
       rangeValCopy:
         sizeThreshold: 32
+      ruleguard:
+        rules: "build/gorules/rules.go" # Run `golangci-lint cache clean` when it changes!
   gocyclo:
     # minimal code complexity to report, 30 by default (but we recommend 10-20)
     min-complexity: 15
@@ -404,7 +406,7 @@ issues:
         - gocritic
 
     # Package def is designed to contain global constants.
-    - path: internal/def/
+    - path: pkg/def/
       linters:
         - gochecknoglobals
 
@@ -418,32 +420,48 @@ issues:
       linters:
         - funlen
 
+    # Servers are allowed to contain a lot of handlers/middlewares.
+    - path: internal/srv/[^/]*/srv.go
+      text: Function 'NewServer'
+      linters:
+        - funlen
+
     # Common well-known style of the project.
-    - path: ^ # Obvious.
-      text: '`(Ctx|Log)` should have comment'
+    - path: internal/(config|srv/[^/]*|sub|app|dal|svc/[^/]*)/[^/]*.go
+      text: 'should have a package comment'
+
+    - path: ^
+      text: '`(Ctx|Log|InitMetrics)` should have comment'
+
+    - path: internal/config/
+      text: '`(FlagSets|Init|\w+Config|Get\w+|MustGet\w+)` should have comment'
+
+    - path: internal/srv/
+      text: '`(Config|Server|NewServer)` should have comment'
+
+    - path: internal/sub/
+      text: '`(Config|Sub|New)` should have comment'
+
+    - path: internal/app/
+      text: '`(Config|App|New)` should have comment'
 
     - path: internal/app/ # Should be documented in app.Appl interface.
       text: '`App[.]\w+` should have comment'
 
     - path: internal/dal/ # Should be documented in app.Repo interface.
       text: '`Repo[.]\w+` should have comment'
 
-    - path: internal/svc/ # Should be documented in app.Svc* interface.
-      text: '`Svc[.]\w+` should have comment'
-
-    - path: internal/app/ # Obvious.
-      text: '`(Config|App|New)` should have comment'
-
-    - path: internal/svc/ # Obvious.
+    - path: internal/svc/
       text: '`(Config|Svc|New)` should have comment'
 
-    - path: internal/srv/ # Obvious.
-      text: '`(Config|NewServer)` should have comment'
+    - path: internal/svc/ # Should be documented in app.Svc* interface.
+      text: '`Svc[.]\w+` should have comment'
 
     - path: ^api/ext- # Not our API, should be documented elsewhere.
       text: 'should have comment'
 
-    - path: ^cmd/|internal/config/ # Require access to unexported identifiers.
+    # Require access to unexported identifiers from tests.
+    - path: ^cmd/|internal/config/
       linters:
         - testpackage
 

README.md

@@ -42,16 +42,16 @@ adapters":
 - `api/*` - definitions of own and 3rd-party APIs/protocols and related
   auto-generated code
 - `cmd/*` - main application(s)
-- `internal/def` - defaults for both application(s) and tests
 - `internal/config` - configuration(s) (default values, env, flags) for
   application(s) subcommands and tests
 - `internal/app` - define interfaces ("ports") and implements business-logic
-- `internal/srv/*`, `internal/dal`, `internal/svc/*` - implements
-  "adapters" (for APIs/UI served by application(s), DB, access to external
-  services)
-- `pkg/*`, `internal/pkg/*` - helper packages, not related to architecture
-  and business-logic (may be later moved to own modules and/or replaced by
-  external dependencies)
+- `internal/srv/*` - adapters for served APIs/UI
+- `internal/dal` - adapter for data storage
+- `internal/svc/*` - adapters for accessing external services
+- `pkg/*` - helper packages, not related to architecture and
+  business-logic (may be later moved to own modules and/or replaced by
+  external dependencies), e.g.:
+    - `pkg/def/` - project-wide defaults
 
 ## Features
 
@@ -80,11 +80,11 @@ adapters":
 - Tools used to build/test project:
 
 ```sh
-curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin v1.30.0
+curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin v1.31.0
 go get gotest.tools/gotestsum@v0.5.3
-curl -sSfL https://github.com/go-swagger/go-swagger/releases/download/v0.25.0/swagger_$(uname)_amd64 | install /dev/stdin $(go env GOPATH)/bin/swagger
 go get github.com/golang/mock/mockgen@v1.4.4
 go get github.com/cheekybits/genny@master
+curl -sSfL https://github.com/go-swagger/go-swagger/releases/download/v0.25.0/swagger_$(uname)_amd64 | install /dev/stdin $(go env GOPATH)/bin/swagger
 ```
 
 ## Setup
@@ -117,6 +117,7 @@ convenience only.
     - Access project at host/port(s) defined in `env.sh`.
 
 ### Cheatsheet
+
 ```sh
 dc up -d --remove-orphans               # (re)start all project's services
 dc logs -f -t                           # view logs of all services

api/openapi/generate.go

@@ -1,5 +1,5 @@
-// Package openapi contains OpenAPI spec and code generated by go-swagger.
-package openapi
+// Package api contains OpenAPI spec and code generated by go-swagger.
+package api
 
 //go:generate rm -rf model restapi client
 //go:generate swagger generate server --api-package op --model-package model --strict-responders --strict-additional-properties --keep-spec-order --principal github.com/powerman/go-service-goswagger-clean-example/internal/app.Auth --exclude-main

cmd/address-book/init_test.go

@@ -10,8 +10,8 @@ import (
 	"github.com/powerman/go-service-goswagger-clean-example/api/openapi/model"
 	"github.com/powerman/go-service-goswagger-clean-example/internal/app"
 	"github.com/powerman/go-service-goswagger-clean-example/internal/config"
-	"github.com/powerman/go-service-goswagger-clean-example/internal/def"
 	"github.com/powerman/go-service-goswagger-clean-example/internal/srv/openapi"
+	"github.com/powerman/go-service-goswagger-clean-example/pkg/def"
 )
 
 func TestMain(m *testing.M) {

cmd/address-book/main.go

@@ -11,18 +11,18 @@ import (
 	"time"
 
 	"github.com/powerman/appcfg"
-	"github.com/powerman/go-service-goswagger-clean-example/internal/def"
-	"github.com/powerman/go-service-goswagger-clean-example/internal/pkg/cobrax"
+	"github.com/powerman/go-service-goswagger-clean-example/pkg/cobrax"
+	"github.com/powerman/go-service-goswagger-clean-example/pkg/def"
 	"github.com/powerman/structlog"
 	"github.com/spf13/cobra"
 )
 
 //nolint:gochecknoglobals // Main.
 var (
-	log = structlog.New(structlog.KeyUnit, "main")
-
 	svc = &service{}
 
+	log = structlog.New(structlog.KeyUnit, "main")
+
 	logLevel = appcfg.MustOneOfString("debug", []string{"debug", "info", "warn", "err"})
 	rootCmd  = &cobra.Command{
 		Use:           def.ProgName,
@@ -46,12 +46,12 @@ var (
 func main() {
 	err := def.Init()
 	if err != nil {
-		log.Fatalln("failed to get defaults:", err)
+		log.Fatalf("failed to get defaults: %s", err)
 	}
 
 	err = initService(rootCmd, serveCmd)
 	if err != nil {
-		log.Fatalln("failed to init service:", err)
+		log.Fatalf("failed to init service: %s", err)
 	}
 
 	rootCmd.PersistentFlags().Var(&logLevel, "log.level", "log level [debug|info|warn|err]")
@@ -82,7 +82,8 @@ func runServeWithGracefulShutdown(_ *cobra.Command, _ []string) error {
 	go func() {
 		<-ctxShutdown.Done()
 		time.Sleep(serveShutdownTimeout.Value(nil))
-		log.Fatalln("failed to graceful shutdown", "version", def.Version())
+		log.PrintErr("failed to graceful shutdown", "version", def.Version())
+		os.Exit(1)
 	}()
 
 	return svc.runServe(ctxStartup, ctxShutdown, shutdown)

cmd/address-book/metrics.go

@@ -3,7 +3,7 @@ package main
 import (
 	"runtime"
 
-	"github.com/powerman/go-service-goswagger-clean-example/internal/def"
+	"github.com/powerman/go-service-goswagger-clean-example/pkg/def"
 	"github.com/prometheus/client_golang/prometheus"
 )
 

cmd/address-book/service.go

@@ -8,10 +8,10 @@ import (
 	"github.com/powerman/go-service-goswagger-clean-example/internal/app"
 	"github.com/powerman/go-service-goswagger-clean-example/internal/config"
 	"github.com/powerman/go-service-goswagger-clean-example/internal/dal"
-	"github.com/powerman/go-service-goswagger-clean-example/internal/def"
-	"github.com/powerman/go-service-goswagger-clean-example/internal/pkg/concurrent"
-	"github.com/powerman/go-service-goswagger-clean-example/internal/pkg/serve"
 	"github.com/powerman/go-service-goswagger-clean-example/internal/srv/openapi"
+	"github.com/powerman/go-service-goswagger-clean-example/pkg/concurrent"
+	"github.com/powerman/go-service-goswagger-clean-example/pkg/def"
+	"github.com/powerman/go-service-goswagger-clean-example/pkg/serve"
 	"github.com/powerman/structlog"
 	"github.com/prometheus/client_golang/prometheus"
 	"github.com/spf13/cobra"

cmd/address-book/service_integration_test.go

@@ -10,26 +10,24 @@ import (
 	"github.com/powerman/go-service-goswagger-clean-example/api/openapi/client"
 	"github.com/powerman/go-service-goswagger-clean-example/api/openapi/client/op"
 	"github.com/powerman/go-service-goswagger-clean-example/api/openapi/model"
-	"github.com/powerman/go-service-goswagger-clean-example/internal/def"
-	"github.com/powerman/go-service-goswagger-clean-example/internal/pkg/netx"
 	"github.com/powerman/go-service-goswagger-clean-example/internal/srv/openapi"
+	"github.com/powerman/go-service-goswagger-clean-example/pkg/def"
+	"github.com/powerman/go-service-goswagger-clean-example/pkg/netx"
 )
 
 func TestSmoke(tt *testing.T) {
 	t := check.T(tt)
 
 	s := &service{cfg: cfg}
 
-	ctxStartup, cancel := context.WithTimeout(ctx, 10*def.TestSecond)
+	ctxStartup, cancel := context.WithTimeout(ctx, def.TestTimeout)
 	defer cancel()
 	ctxShutdown, shutdown := context.WithCancel(ctx)
 	errc := make(chan error)
 	go func() { errc <- s.runServe(ctxStartup, ctxShutdown, shutdown) }()
 	defer func() {
 		shutdown()
-		if err := <-errc; err != nil {
-			t.Log("failed to Serve:", err)
-		}
+		t.Nil(<-errc, "RunServe")
 	}()
 	t.Must(t.Nil(netx.WaitTCPPort(ctxStartup, cfg.Addr), "connect to service"))
 

internal/app/init_test.go

@@ -7,7 +7,7 @@ import (
 	"github.com/golang/mock/gomock"
 	"github.com/powerman/check"
 	"github.com/powerman/go-service-goswagger-clean-example/internal/app"
-	"github.com/powerman/go-service-goswagger-clean-example/internal/def"
+	"github.com/powerman/go-service-goswagger-clean-example/pkg/def"
 	"github.com/prometheus/client_golang/prometheus"
 	_ "github.com/smartystreets/goconvey/convey"
 )

internal/app/metrics.go

@@ -1,7 +1,7 @@
 package app
 
 import (
-	"github.com/powerman/go-service-goswagger-clean-example/internal/def"
+	"github.com/powerman/go-service-goswagger-clean-example/pkg/def"
 	"github.com/prometheus/client_golang/prometheus"
 )
 

internal/config/config.go

@@ -8,15 +8,13 @@
 package config
 
 import (
-	"strconv"
-
 	"github.com/powerman/appcfg"
-	"github.com/powerman/go-service-goswagger-clean-example/internal/def"
-	"github.com/powerman/go-service-goswagger-clean-example/internal/pkg/netx"
+	"github.com/powerman/go-service-goswagger-clean-example/pkg/def"
+	"github.com/powerman/go-service-goswagger-clean-example/pkg/netx"
 	"github.com/spf13/pflag"
 )
 
-// envPrefix defines common prefix for environment variables.
+// EnvPrefix defines common prefix for environment variables.
 const envPrefix = "EXAMPLE_"
 
 // All configurable values of the microservice.
@@ -30,8 +28,8 @@ var all = &struct { //nolint:gochecknoglobals // Config is global anyway.
 	MetricsAddrPort appcfg.Port           `env:"METRICS_ADDR_PORT"`
 }{ // Defaults, if any:
 	AddrHost:        appcfg.MustNotEmptyString(def.Hostname),
-	AddrPort:        appcfg.MustPort(strconv.Itoa(def.Port)),
-	MetricsAddrPort: appcfg.MustPort(strconv.Itoa(def.MetricsPort)),
+	AddrPort:        appcfg.MustPort("8000"),
+	MetricsAddrPort: appcfg.MustPort("9000"),
 }
 
 // FlagSets for all CLI subcommands which use flags to set config values.
@@ -42,6 +40,8 @@ type FlagSets struct {
 var fs FlagSets //nolint:gochecknoglobals // Flags are global anyway.
 
 // Init updates config defaults (from env) and setup subcommands flags.
+//
+// Init must be called once before using this package.
 func Init(flagsets FlagSets) error {
 	fs = flagsets
 

internal/config/config_test.go

@@ -5,15 +5,15 @@ import (
 	"testing"
 
 	"github.com/powerman/check"
-	"github.com/powerman/go-service-goswagger-clean-example/internal/def"
-	"github.com/powerman/go-service-goswagger-clean-example/internal/pkg/netx"
+	"github.com/powerman/go-service-goswagger-clean-example/pkg/def"
+	"github.com/powerman/go-service-goswagger-clean-example/pkg/netx"
 )
 
 func Test(t *testing.T) {
 	want := &ServeConfig{
 		APIKeyAdmin: "admin",
-		Addr:        netx.NewAddr(def.Hostname, def.Port),
-		MetricsAddr: netx.NewAddr(def.Hostname, def.MetricsPort),
+		Addr:        netx.NewAddr(def.Hostname, 8000),
+		MetricsAddr: netx.NewAddr(def.Hostname, 9000),
 	}
 
 	t.Run("required", func(tt *testing.T) {

internal/config/init_test.go

@@ -5,7 +5,7 @@ import (
 	"testing"
 
 	"github.com/powerman/check"
-	"github.com/powerman/go-service-goswagger-clean-example/internal/def"
+	"github.com/powerman/go-service-goswagger-clean-example/pkg/def"
 	_ "github.com/smartystreets/goconvey/convey"
 	"github.com/spf13/pflag"
 )

internal/config/testing.go

@@ -1,7 +1,7 @@
 package config
 
 import (
-	"github.com/powerman/go-service-goswagger-clean-example/internal/pkg/netx"
+	"github.com/powerman/go-service-goswagger-clean-example/pkg/netx"
 	"github.com/powerman/must"
 	"github.com/spf13/pflag"
 )

internal/dal/init_test.go

@@ -6,7 +6,7 @@ import (
 
 	"github.com/powerman/check"
 	"github.com/powerman/go-service-goswagger-clean-example/internal/app"
-	"github.com/powerman/go-service-goswagger-clean-example/internal/def"
+	"github.com/powerman/go-service-goswagger-clean-example/pkg/def"
 	"github.com/prometheus/client_golang/prometheus"
 	_ "github.com/smartystreets/goconvey/convey"
 )

internal/srv/openapi/error.go

@@ -8,7 +8,7 @@ import (
 	"github.com/go-openapi/swag"
 	"github.com/powerman/go-service-goswagger-clean-example/api/openapi/model"
 	"github.com/powerman/go-service-goswagger-clean-example/api/openapi/restapi/op"
-	"github.com/powerman/go-service-goswagger-clean-example/internal/def"
+	"github.com/powerman/go-service-goswagger-clean-example/pkg/def"
 )
 
 func errListContacts(log Log, err error, code errCode) op.ListContactsResponder {

internal/srv/openapi/gen.error.go

@@ -10,7 +10,7 @@ import (
 	"github.com/go-openapi/swag"
 	"github.com/powerman/go-service-goswagger-clean-example/api/openapi/model"
 	"github.com/powerman/go-service-goswagger-clean-example/api/openapi/restapi/op"
-	"github.com/powerman/go-service-goswagger-clean-example/internal/def"
+	"github.com/powerman/go-service-goswagger-clean-example/pkg/def"
 )
 
 func errAddContact(log Log, err error, code errCode) op.AddContactResponder {

internal/srv/openapi/init_test.go

@@ -13,9 +13,9 @@ import (
 	"github.com/powerman/go-service-goswagger-clean-example/api/openapi/client"
 	"github.com/powerman/go-service-goswagger-clean-example/api/openapi/model"
 	"github.com/powerman/go-service-goswagger-clean-example/internal/app"
-	"github.com/powerman/go-service-goswagger-clean-example/internal/def"
-	"github.com/powerman/go-service-goswagger-clean-example/internal/pkg/netx"
 	"github.com/powerman/go-service-goswagger-clean-example/internal/srv/openapi"
+	"github.com/powerman/go-service-goswagger-clean-example/pkg/def"
+	"github.com/powerman/go-service-goswagger-clean-example/pkg/netx"
 	"github.com/prometheus/client_golang/prometheus"
 	_ "github.com/smartystreets/goconvey/convey"
 )
@@ -76,7 +76,7 @@ func testNewServer(t *check.C) (c *client.AddressBook, url string, mockAppl *app
 	url = fmt.Sprintf("http://%s", ln.Addr().String())
 
 	// Avoid race between server.Serve() and server.Shutdown().
-	ctx, cancel := context.WithTimeout(context.Background(), 10*def.TestSecond)
+	ctx, cancel := context.WithTimeout(context.Background(), def.TestTimeout)
 	defer cancel()
 	req, err := http.NewRequestWithContext(ctx, "GET", url, nil)
 	t.Must(t.Nil(err))