一款不错的 Go Server/API boilerplate，使用 K8S+DDD+CQRS+ES+gRPC 最佳实践构建

Golang API Starter Kit

• https://github.com/vardius/go-api-boilerplate

该项目的主要目的是使用最佳实践、DDD、CQRS、ES、gRPC 提供样板项目设置。为开发和生产环境提供 kubernetes 配置。允许与反映生产的 environment 一起工作，从而减少任何错误配置。

这是许多服务(如身份验证或用户域)的单一存储库(mono-repository)。除了共享包外，每个服务都有自己的代码库，以简化这个样板文件。服务之间通过 gRPC 进行通信。每个服务都可能为外部通信或/和 gRPC 公开 HTTP API。

这个项目设置应该减少整个 kubernetes 集群和/或每个微服务的环境配置时间。将每个服务提取到自己的存储库或将其保留为 mono-repo 应该是一个偏好问题。

Web UI 示例 (React)

此样板包括简单的 Web UI，以演示与 API 的示例交互。部署并设置好 hosts 后，请查看 https://api.go-api-boilerplate.local 以访问 UI。

关键概念

1. Rest API
2. Docker
   1. https://www.docker.com/what-docker
3. Kubernetes
   1. https://kubernetes.io
4. Helm chart
   1. https://helm.sh
5. Terraform
   1. https://terraform.io
6. gRPC
   1. https://grpc.io/docs
7. Domain Driven Design (DDD)
   1. https://en.wikipedia.org/wiki/Domain-driven_design
8. CQRS
   1. https://martinfowler.com/bliki/CQRS.html
9. Event Sourcing
   1. https://martinfowler.com/eaaDev/EventSourcing.html
10. Hexagonal, Onion, Clean Architecture
    1. https://herbertograca.com/2017/11/16/explicit-architecture-01-ddd-hexagonal-onion-clean-cqrs-how-i-put-it-all-together
11. oAuth2
    1. https://github.com/go-oauth2/oauth2

值得了解一下这个样板文件中使用的包:

1. gorouter
   1. https://github.com/vardius/gorouter
2. message-bus
   1. https://github.com/vardius/message-bus
3. gollback
   1. https://github.com/vardius/gollback
4. shutdown
   1. https://github.com/vardius/shutdown
5. pubsub
   1. https://github.com/vardius/pubsub
6. pushpull
   1. https://github.com/vardius/pushpull
7. gocontainer
   1. https://github.com/vardius/gocontainer

? 文档

• Wiki
  • https://github.com/vardius/go-api-boilerplate/wiki
• Package level docs
  • https://godoc.org/github.com/vardius/go-api-boilerplate#pkg-subdirectories
• Getting Started
  • https://github.com/vardius/go-api-boilerplate/wiki/1.-Getting-Started
• Installing and Setting up
  • https://github.com/vardius/go-api-boilerplate/wiki/2.-Installing-and-Setting-up
• Configuration
  • https://github.com/vardius/go-api-boilerplate/wiki/3.-Configuration
• Guides
  • https://github.com/vardius/go-api-boilerplate/wiki/4.-Guides

快速开始

Localhost alias

编辑 /etc/hosts 以添加 localhost 别名

➜ go-api-boilerplate git:(master) cat /etc/hosts
##
# Host Database
#
# localhost is used to configure the loopback interface
# when the system is booting. Do not change this entry.
##
127.0.0.1 go-api-boilerplate.local api.go-api-boilerplate.local maildev.go-api-boilerplate.local mysql.go-api-boilerplate.local

Build release

Local image

make docker-build BIN=auth
make docker-build BIN=migrate
make docker-build BIN=user
make docker-build BIN=web

GitHub Package Registry

使用 metadata 创建 tag 将触发 github workflow 并将 docker 镜像发布到 GitHub Package Registry。

标签 v1.0.0+user 将触发 user 服务的构建，发布 1.0.0 docker image tag。您可以在 cmd 目录中为所有服务创建 release。

v1.0.0+auth
v1.0.0+user
v1.0.0+web
v1.0.0+migrate

替换 main.yaml 中的 image 细节

  image:
-    repository: go-api-boilerplate-user
+    repository: docker.pkg.github.com/vardius/go-api-boilerplate/go-api-boilerplate-user
-    tag: latest
+    tag: 1.0.0
    pullPolicy: IfNotPresent

对所有服务重复此操作和 migrate init containers。

Private Registry

登录到 Docker

docker login

复制 docker config

cp ~/.docker/config.json ./k8s/.docker/config.json

验证 config.json

Deploy release

make terraform-install

Destroy

make terraform-destroy

如果持久卷(persistent volume)在终止时堆叠(stack)，则在持久卷受到保护时会发生这种情况。您应该能够交叉验证这一点：

kubectl describe pvc PVC_NAME --namespace=go-api-boilerplate | grep Finalizers

Output:
Finalizers:    [kubernetes.io/pvc-protection]

您可以通过使用 kubectl patch 将 finalizers 设置为 null 来解决此问题：

kubectl patch pvc PVC_NAME --namespace=go-api-boilerplate -p '{"metadata":{"finalizers": []}}' --type=merge

Build tags

Build flags 用于不同的持久层(persistence layers)。有关详细信息，请参阅 services.go 文件。提供的层是 mysql、mongo 和 memory。如果需要，可以按照给定的模式以类似的方式轻松添加新层。

go build -tags=persistence_mysql

可用的 build tags

• persistence_mysql (mysql service container)
• persistence_mongodb (mongodb service container)

Important 如果没有提供 flag，持久层默认为 memory（Docker image 设置了 persistence_mysql flag），详情请参阅每个服务 Dockerfile。

Domain(领域)

Dispatching command(分发命令)

通过 POST 请求发送示例 JSON

curl -d '{"email":"test@test.com"}' -H "Content-Type: application/json" -X POST https://api.go-api-boilerplate.local/users/v1/dispatch/user/user-register-with-email --insecure

View(视图)

Public routes(公共路由)

获取 user 详细信息 https://api.go-api-boilerplate.local/users/v1/34e7ed39-aa94-4ef2-9422-401bba9fc812

{"id":"34e7ed39-aa94-4ef2-9422-401bba9fc812","email":"test@test.com"}

获取 user 列表 https://api.go-api-boilerplate.local/users/v1?page=1&limit=10

{"page":1,"limit":20,"total":1,"users":[{"id":"34e7ed39-aa94-4ef2-9422-401bba9fc812","email":"test@test.com"}]}

Protected routes(受保护的路由)

访问 protected route，使用 `auth token https://api.go-api-boilerplate.local/users/v1/me.

{"code": "401","message": "Unauthorized"}

为 user 请求 access token

curl -d '{"email":"test@test.com"}' -H "Content-Type: application/json" -X POST https://api.go-api-boilerplate.local/users/v1/dispatch/user/user-request-access-token --insecure

从 mail catcher 获取您的 access token https://maildev.go-api-boilerplate.local.

使用 auth token 访问受保护的路由 https://api.go-api-boilerplate.local/users/v1/me?authToken=eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJyXHUwMDE277-977-977-977-9IiwiZXhwIjoxNTU5NjEwOTc2LCJzdWIiOiIzNGU3ZWQzOS1hYTk0LTRlZjItOTQyMi00MDFiYmE5ZmM4MTIifQ.pEkgtDAvNh2D3Dtgfpu4tt-Atn1h6QwMkDhz4KpgFxNX8jE7fQH00J6K5V7CV063pigxWhOMMTRLmQdhzhajzQ

{"id":"34e7ed39-aa94-4ef2-9422-401bba9fc812","email":"test@test.com"}