README.md

gin-apiserver

gin-apiserver is a HTTP apiserver framework based on Gin.

Introduction

gin-apiserver是一个基于gin框架写的ApiServer框架，主要用于企业生产环境中的快速开发

Features

• 1、支持configmap reload api

  // config reload
  r.Any("/-/reload", func(c *gin.Context) {
          log.Info("===== Server Stop! Cause: Config Reload. =====")
          os.Exit(1)
  })

• 2、支持ping-pong健康检查&版本获取

  // a ping api test
  r.GET("/ping", controller.Ping)
  
  // get gin-apiserver version
  r.GET("/version", controller.Version)

• 3、支持dump-goroutine-stack-traces

  $ kill -SIGUSR1 41307
  
  === BEGIN goroutine stack dump ===
  goroutine 20 [running]:
  github.com/duyanghao/gin-apiserver/pkg/util.dumpStacks()
          /root/go/src/github.com/duyanghao/gin-apiserver/pkg/util/trap.go:23 +0x6d
  github.com/duyanghao/gin-apiserver/pkg/util.SetupSigusr1Trap.func1(0xc000332240)
          /root/go/src/github.com/duyanghao/gin-apiserver/pkg/util/trap.go:16 +0x34
  created by github.com/duyanghao/gin-apiserver/pkg/util.SetupSigusr1Trap
          /root/go/src/github.com/duyanghao/gin-apiserver/pkg/util/trap.go:14 +0xab
  
  goroutine 1 [IO wait]:
  internal/poll.runtime_pollWait(0x7fccf3b86f68, 0x72, 0x0)
          /usr/local/go/src/runtime/netpoll.go:182 +0x56
  internal/poll.(*pollDesc).wait(0xc000442618, 0x72, 0x0, 0x0, 0xbadadd)
          /usr/local/go/src/internal/poll/fd_poll_runtime.go:87 +0x9b
  internal/poll.(*pollDesc).waitRead(...)
          /usr/local/go/src/internal/poll/fd_poll_runtime.go:92
  internal/poll.(*FD).Accept(0xc000442600, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0)
          /usr/local/go/src/internal/poll/fd_unix.go:384 +0x1ba
  net.(*netFD).accept(0xc000442600, 0xb51080, 0x50, 0xc0000a77c0)
          /usr/local/go/src/net/fd_unix.go:238 +0x42
  net.(*TCPListener).accept(0xc00049e110, 0xc000046a80, 0x7fccf3be26d0, 0xc000000180)
          /usr/local/go/src/net/tcpsock_posix.go:139 +0x32
  net.(*TCPListener).AcceptTCP(0xc00049e110, 0x40d9b8, 0x30, 0xb51080)
          /usr/local/go/src/net/tcpsock.go:247 +0x48
  net/http.tcpKeepAliveListener.Accept(0xc00049e110, 0xb51080, 0xc0002d0e70, 0xadef20, 0x2294c70)
          /usr/local/go/src/net/http/server.go:3264 +0x2f
  net/http.(*Server).Serve(0xc0002d7d40, 0xcb8640, 0xc00049e110, 0x0, 0x0)
          /usr/local/go/src/net/http/server.go:2859 +0x22d
  net/http.(*Server).ListenAndServe(0xc0002d7d40, 0xc0002d7d40, 0xc000355ea8)
          /usr/local/go/src/net/http/server.go:2797 +0xe4
  net/http.ListenAndServe(...)
          /usr/local/go/src/net/http/server.go:3037
  github.com/gin-gonic/gin.(*Engine).Run(0xc000394000, 0xc000355f48, 0x1, 0x1, 0x0, 0x0)
          /root/go/src/github.com/duyanghao/gin-apiserver/vendor/github.com/gin-gonic/gin/gin.go:294 +0x140
  main.main()
          /root/go/src/github.com/duyanghao/gin-apiserver/cmd/main.go:22 +0x2c4
  
  goroutine 19 [syscall]:
  os/signal.signal_recv(0xcb28a0)
          /usr/local/go/src/runtime/sigqueue.go:139 +0x9c
  os/signal.loop()
          /usr/local/go/src/os/signal/signal_unix.go:23 +0x22
  created by os/signal.init.0
          /usr/local/go/src/os/signal/signal_unix.go:29 +0x41
  
  === END goroutine stack dump ===

Framework

gin-apiserver框架的核心就是pkg包，下面主要针对该包结构进行描述：

pkg/
├── config
│   ├── config.go
│   ├── key.go
│   ├── model.go
│   └── opt_defs.go
├── controller
│   ├── ping.go
│   ├── todo.go
│   └── version.go
├── log
│   └── log.go
├── middleware
│   ├── basic_auth_middleware.go
├── models
│   └── common.go
├── route
│   └── routes.go
├── service
│   └── todo.go
├── store
└── util

• config：主要用于配置文件，实现：文件+环境变量+命令行参数读取
• controller: 对应MVC中controller，调用service中的接口进行实际处理，自己只做数据校验与拼接
• service: 负责主要的逻辑实现
• log: 日志模块，实现：模块名(文件名)+函数名+行数+日志级别
• middleware: 中间件，负责通用的处理，例如：鉴权
• models: 对应MVC中的model
• route: gin路由
• store: 存储模块，可以添加MySQL、Redis等
• util: 通用的库函数

Usage

• step1 - 替换项目名称

  实际使用中，通常需要将gin-apiserver替换成业务需要的后台server名称，可以执行如下命令：

  $ grep -rl gin-apiserver . | xargs sed -i 's/gin-apiserver/youapiserver/g' 

• step2 - 开发业务controller和service

  框架中已经集成了一个示例(todo)：

  // controller(pkg/controller/todo.go)
  type ToDoController interface {
  	GetToDo(c *gin.Context)
  }
  
  // service(pkg/service/todo.go)
  type ToDoService interface {
  	Get()
  }

  我们需要按照自身业务需求开发todo(替换成任意功能)的controller和service逻辑。另外你也可以参考todo添加其它功能对应的controller和service

• step3 - 启动服务

  可以直接启动运行服务，如下：

  $ bash hack/start.sh

  也可以在Kubernetes集群中启动服务，如下：

  # generated image
  $ make dockerfiles.build
  # retag and push to your docker registry
  $ docker tag duyanghao/gin-apiserver:v0.1.0 xxx/duyanghao/gin-apiserver:v0.1.0
  $ docker push xxx/duyanghao/gin-apiserver:v0.1.0
  # Update the deployment to use the built image name
  $ sed -i 's|REPLACE_IMAGE|xxx/duyanghao/gin-apiserver:v0.1.0|g' hack/deploy/deployment.yaml
  # create service 
  $ kubectl apply -f hack/deploy/service.yaml
  # create deployment
  $ kubectl apply -f hack/deploy/deployment.yaml

3rd party Implements

• coredns-dynapi-adapter - coredns dynamic middleware apiserver adapter

Refs

• dump-goroutine-stack-traces