介绍

介绍
架构图
生命周期
目录结构
如何运行
依赖注入
配置
日志
错误处理
- 转换为 HTTP 状态码
- 将 GRPC 错误转换为 Error
组件
transport 层
- HTTP
service 层
命令行功能模块
cron 定时任务功能模块
如何部署

介绍

go-scaffold 是一个基于 cobra 和 kratos 框架的脚手架，设计思想是基于 wire 实现模块和功能的组件化

go-scaffold 开箱即用，使用简单，可以快速搭建起一个微服务进行业务代码的开发，支持功能：

依赖注入
cobra 命令行
cron 定时任务
apollo 远程配置中心和配置监听
日志切割
服务注册和发现
jaeger 链路追踪
Swagger 文档生成
docker-compose 和 Kubernetes 部署

架构图

生命周期

目录结构

|-- bin # 二进制文件目录
|-- cmd # 编译入口
|   `-- app
|-- deploy # 环境和部署相关目录
|   |-- docker-compose # docker-compose 容器编排目录
|   `-- kubernetes # k8s 编排配置目录
|-- docs # 文档目录
|-- etc # 配置文件目录
|-- internal
|   `-- app
|       |-- command # 命令行功能模块
|       |   |-- handler
|       |   `-- script # 临时脚本
|       |-- component # 功能组件，如：db, redis 等
|       |-- config # 配置模型
|       |-- cron # 定时任务功能模块
|       |   `-- job
|       |-- model # 数据库模型
|       |-- pkg # 功能类库
|       |-- repository # 数据处理层
|       |-- service # 业务逻辑层
|       |-- test
|       `-- transport
|           |-- grpc
|           |   |-- api # proto 文件目录
|           |   |-- handler # 控制层
|           |   `-- middleware # 中间件
|           `-- http
|               |-- api # swagger 文档
|               |-- handler # 控制层
|               |-- middleware # 中间件
|               `-- router # 路由
|-- logs # 日志目录
|-- pkg # 功能类库
`-- proto # 第三方 proto 文件目录

如何运行

首先将 etc/config.yaml.example 拷贝为 etc/config.yaml

`go build` 或 `go run`

go build 方式

$ go generate ./...
$ go build -o bin/app cmd/app/main.go cmd/app/wire_gen.go
$ ./bin/app

go run 方式

$ go generate ./...
$ go run cmd/app/main.go cmd/app/wire_gen.go

`make`

# 下载依赖
$ make download
$ make build

# 或依据平台编译
$ make linux-build
$ make windows-build
$ make mac-build

# 运行
$ ./bin/app

`docker-compose`

docker-compose 的启动方式有两种，一种是基于 air 镜像，一种是基于 Dockerfile 来构建镜像

注意：

基于 air 镜像的方式只适用于开发阶段，请勿用于生产环境 > - 在 Windows 系统环境下，热更新可能不会生效，这是因为 fsnotify 无法收到 wsl 文件系统的变更通知

基于 Dockerfile 的方式如果用于开发阶段，修改的代码将不会更新，除非在 docker-compose 启动时指定 --build 参数，但是这将会导致每次启动时都重新构建镜像，可能需要等待很长时间

# 基于 air 
$ docker-compose -f deploy/docker-compose/docker-compose-dev.yaml up

# 基于 Dockerfile
$ docker-compose -f deploy/docker-compose/docker-compose.yaml up

热重启

热重启功能基于 air

$ air

运行子命令或脚本

命令行程序功能基于 cobra

$ ./bin/app [标志] <子命令> [标志] [参数]

# 帮助信息

$ ./bin/app -h
$ ./bin/app <子命令> -h

依赖注入

依赖通过自动生成代码的方式在编译期完成注入

依赖结构：

配置

默认配置文件路径为：etc/app/config.yaml

可以在运行程序时通过 --config 或 -f 选项指定其它配置文件

配置模型

配置文件的内容在程序启动时会被加载到配置模型中，相关目录：internal/app/config

internal/app/config/declare.go：配置的结构体定义
internal/app/config/config.go：声明 Provider 和监听的配置 Key

如何获取配置模型：

注入配置模型类型：*config.Config
注入 App 配置模型类型：*config.App
...

例：

package trace

import "go-scaffold/internal/app/config"

type Handler struct {
    conf    *config.Config
    appConf *config.App
}

func NewHandler(
    conf *config.Config,
    appConf *config.App,
) *Handler {
    return &Handler{
    	conf:    conf,
    	appConf: appConf,
    }
}

远程配置

在启动程序时，可通过以下选项配置远程配置中心

--config.apollo.enable: apollo 是否启用
--config.apollo.endpoint: 连接地址
--config.apollo.appid: appID
--config.apollo.cluster: cluster
--config.apollo.namespace: 命名空间
--config.apollo.secret: secret

监听配置变更

在 internal/app/config/config.go 文件的 watchKeys 变量中注册需要监听的配置键

注册完成后，如果配置文件内容发生变更，无需重启服务，更改内容会自动同步到配置实例中

例：

var watchKeys = []string{
   "services.self",
   "jwt.key",
}

日志

日志基于 zap，日志的轮转基于 file-rotatelogs

日志内容默认输出到 logs 目录中，并且根据每天的日期进行分割

可在程序启动时，通过以下选项改变日志行为：

--log.path: 日志输出路径
--log.level: 日志等级（debug、info、warn、error、panic、fatal）
--log.format: 日志输出格式（text、json）
--log.caller-skip: 日志 caller 跳过层数

如何获取日志实例：

注入类型：log.Logger

例：

package greet

import "github.com/go-kratos/kratos/v2/log"

type Service struct {
    logger *log.Helper
}

func NewService(logger log.Logger) *Service {
    return &Service{
        logger: log.NewHelper(logger),
    }
}

错误处理

脚手架定义了统一的错误格式

type Error struct {
    // Code 状态码
    Code ErrorCode

    // Message 错误信息
    Message string

    // Metadata 元数据
    Metadata map[string]string
}

快捷函数：

// ServerError 服务器错误
func ServerError(options ...Option) *Error {
    return New(ServerErrorCode, ServerErrorCode.String(), options...)
}

// ClientError 客户端错误
func ClientError(options ...Option) *Error {
    return New(ClientErrorCode, ClientErrorCode.String(), options...)
}

// ValidateError 参数校验错误
func ValidateError(options ...Option) *Error {
    return New(ValidateErrorCode, ValidateErrorCode.String(), options...)
}

// Unauthorized 未认证
func Unauthorized(options ...Option) *Error {
    return New(UnauthorizedCode, UnauthorizedCode.String(), options...)
}

// PermissionDenied 权限拒绝错误
func PermissionDenied(options ...Option) *Error {
    return New(PermissionDeniedCode, PermissionDeniedCode.String(), options...)
}

// ResourceNotFound 资源不存在
func ResourceNotFound(options ...Option) *Error {
    return New(ResourceNotFoundCode, ResourceNotFoundCode.String(), options...)
}

// TooManyRequest 请求太过频繁
func TooManyRequest(options ...Option) *Error {
    return New(TooManyRequestCode, TooManyRequestCode.String(), options...)
}

转换为 `HTTP` 状态码

Code 属性实现了 HTTP 状态码的转换

例：

func (s *Service) Hello(ctx context.Context, req HelloRequest) (*HelloResponse, error) {
    // ...
    
    // 返回 Error
    return nil, errors.ServerError()
	
    // ...
}

// ...

// 调用 service 方法
ret, err := h.service.Hello(ctx.Request.Context(), *req)
if err != nil {
    // response.Error 方法会自动将 Error 转换为对应的 HTTP 状态
    response.Error(ctx, err)
    return
}

// ...

将 `GRPC` 错误转换为 `Error`

Error 实现了 GRPCStatus() 接口，通过 FromGRPCError 函数可将 GRPC 错误转换为 Error

例：

// ...

client := greet.NewGreetClient(conn)
resp, err := client.Hello(reqCtx, &greet.HelloRequest{Name: "Example"})
if err != nil {
    // 将 GRPC 错误转换为 Error
    e := errors.FromGRPCError(err)
    response.Error(ctx, fmt.Errorf("GRPC 调用错误：%s", e.Message))
    return
}

// ...

组件

`Casbin`

基于 casbin 进行封装，现支持 file 和 gorm 两种类型的 adapter，如果同时配置，file 类型生效

如何获取 Enforcer 实例：

注入类型：*casbin.Enforcer

例：

package permission

import "github.com/casbin/casbin/v2"

type Service struct {
    enforcer *casbin.Enforcer
}

func NewService(enforcer *casbin.Enforcer) *Service {
    return &Service{
        enforcer: enforcer,
    }
}

如何进行配置：

casbin:
  model: # casbin 模型
    path: "assets/casbin/rbac_model.conf"
  adapter: # 适配器配置
    file:
      path: "assets/casbin/rbac_policy.csv"
    gorm:
      tableName: "casbin_rules" # 数据表名称

如何自定义 casbin policy 的数据库存储模型：

在 internal/app/config/config.go 文件的 Loaded 函数中增加代码

func Loaded(hLogger log.Logger, cfg config.Config, conf *Config) error {
    // ...
    
    if conf.Casbin != nil {
        if conf.Casbin.Adapter != nil {
            if conf.Casbin.Adapter.Gorm != nil {
                conf.Casbin.Adapter.Gorm.SetMigration(func(db *gorm.DB) error {
                    return (&model.CasbinRule{}).Migrate(db)
                })
            }
        }
    }

    // ...
}

`Client`

`gRPC` 客户端

基于 kratos 的 gRPC 客户端进行封装，根据传入的地址自动判断是走直连还是服务发现

如何获取客户端实例：

注入类型：*grpc.Client

例：

package trace

import "go-scaffold/internal/app/component/client/grpc"

type Handler struct {
    grpcClient *grpc.Client
}

func NewHandler(
    grpcClient *grpc.Client,
) *Handler {
    return &Handler{
    	grpcClient: grpcClient,
    }
}

如何进行配置：

services:
  self: "127.0.0.1:9528"
  # self: "discovery:///go-scaffold" # 服务发现地址

`Discovery` 服务发现与注册

基于 kratos 的服务注册与发现进行封装，现支持 etcd 和 consul，可根据配置进行切换，如果同时配置，etcd 生效

如何获取 Discovery 实例：

注入类型：discovery.Discovery

例：

package transport

import "go-scaffold/internal/app/component/discovery"

type Transport struct {
    // ...
}

func New(discovery discovery.Discovery) *Transport {
    // ...
}

如何进行配置：

discovery:
  etcd:
    endpoints:
      - "localhost:12379"
  # consul:
  #   addr: "localhost:8500"
  #   schema: "http"

`Ent`

ent 组件基于 ent

如何获取 ent 客户端：

注入类型：*ent.Client

例：

package user

import "go-scaffold/internal/app/component/ent/ent"

type Repository struct {
    ent *ent.Client
}

func NewRepository(ent *ent.Client) *Repository {
    return &Repository{
        ent: ent,
    }
}

`orm`

orm 组件基于 gorm

如何获取 orm 实例：

注入类型：*gorm.DB

例：

package user

import "gorm.io/gorm"

type Repository struct {
    db *gorm.DB
}

func NewRepository(db *gorm.DB) *Repository {
    return &Repository{
        db: db,
    }
}

如何配置多数据库

参考：https://gorm.io/docs/dbresolver.html

etc/config.yaml:

db:
  driver: "mysql"
  host: "127.0.0.1"
  port: 13306
  database: "go-scaffold"
  username: "root"
  password: "root"
  options:
    - "charset=utf8mb4"
    - "parseTime=True"
    - "loc=Local"
  maxIdleConn: 5
  maxOpenConn: 10
  connMaxIdleTime: 120
  connMaxLifeTime: 120
  logLevel: "info"
  # 多数据库配置
  resolvers:
    - type: "replica" # source 或 replica
      host: "127.0.0.1"
      port: 13307
      database: "go-scaffold"
      username: "root"
      password: "root"
      options:
        - "charset=utf8mb4"
        - "parseTime=True"
        - "loc=Local"
    - type: "replica"
      host: "127.0.0.1"
      port: 13308
      database: "go-scaffold"
      username: "root"
      password: "root"
      options:
        - "charset=utf8mb4"
        - "parseTime=True"
        - "loc=Local"

internal/app/config/config.go:

func Loaded(hLogger log.Logger, cfg config.Config, conf *Config) error {
    // ...
	
    // 配置多数据库
    if conf.DB != nil {
        if len(conf.DB.Resolvers) > 0 {
            var (
                sources  = make([]gorm.Dialector, 0, len(conf.DB.Resolvers))
                replicas = make([]gorm.Dialector, 0, len(conf.DB.Resolvers))
            )
    
            for _, resolver := range conf.DB.Resolvers {
                dial, err := orm.BuildDialector(conf.DB.Driver, resolver.DSN)
                if err != nil {
                    return err
                }
                switch resolver.Type {
                case orm.Source:
                    sources = append(sources, dial)
                case orm.Replica:
                    replicas = append(replicas, dial)
                default:
                    return fmt.Errorf("unsupported resolver type %s", resolver.Type)
                }
            }
    
            conf.DB.Plugins = func(db *gorm.DB) ([]gorm.Plugin, error) {
                return []gorm.Plugin{
                    dbresolver.Register(dbresolver.Config{
                        Sources:  sources,
                        Replicas: replicas,
                        Policy:   dbresolver.RandomPolicy{},
                    }),
                }, nil
            }
        }
    }
	
    // ...
}

`Redis` 客户端

Redis 客户端基于 go-redis

如何获取 Redis 客户端：

注入类型：*redis.Client

例：

package user

import "github.com/go-redis/redis/v8"

type Repository struct {
    rdb *redis.Client
}

func NewRepository(rdb *redis.Client) *Repository {
    return &Repository{
        rdb: rdb,
    }
}

`trace`

脚手架基于 opentelemetry-go 实现了 OpenTelemetry 规范的链路追踪

transport 中 HTTP 和 gRPC 均已注册链路追踪的中间件

如何获取 tracerProvider 和 tracer：

注入类型：*redis.Client

例：

package trace

import "go-scaffold/internal/app/component/trace"

type Handler struct {
    trace *trace.Tracer
}

func NewHandler(
    trace *trace.Tracer,
) *Handler {
    return &Handler{
        trace: trace,
    }
}

`uid`

uid 组件是基于 snowflake 实现的 uid 生成器，可用于数据库主键

如何获取 uid 实例：

注入类型：uid.Generator

例：

package user

import "go-scaffold/internal/app/component/uid"

type Repository struct {
    id uid.Generator
}

func NewRepository(id uid.Generator) *Repository {
    return &Repository{
        id: id,
    }
}

`transport` 层

`HTTP`

响应

在 internal/app/transport/http/pkg/response 包中，对 JSON 响应进行了封装

成功响应示例：

func (h *Handler) Hello(ctx *gin.Context) {
    // ...

    response.Success(ctx, response.WithData(ret))
    return
}

错误响应示例：

func (h *Handler) Hello(ctx *gin.Context) {
    // ...
    
    ret, err := h.service.Hello(ctx.Request.Context(), *req)
        if err != nil {
        response.Error(ctx, err)
        return
    }
    
    // ...
}

`swagger` 文档生成

swagger 文档的生成基于 swag，统一生成到 internal/app/transport/http/api 目录下，否则无法访问

生成 swagger 文档的方式有三种

swag 命令方式

$ swag fmt -d internal/app -g app.go
$ swag init -d internal/app -g app.go -o internal/app/transport/http/api

make 方式

$ make doc

go generate 方式

$ go generate ./...

如何访问 `swagger` 文档

浏览器打开 <host>/api/docs

`service` 层

service 层处理业务逻辑 transport 层中的 HTTP 和 gRPC，或命令行都只是其中一个入口

参数的校验基于 ozzo-validation，统一放到 service 层

例：

type CreateRequest struct {
    Name  string `json:"name"`
    Age   int8   `json:"age"`
    Phone string `json:"phone"`
}

func (r CreateRequest) Validate() error {
    return validation.ValidateStruct(&r,
    	validation.Field(&r.Name, validation.Required.Error("名称不能为空")),
    	validation.Field(&r.Phone, validation.By(validator.IsMobilePhone)),
    )
}

type CreateResponse struct {
    Id    uint64 `json:"id"`
    Name  string `json:"name"`
    Age   int8   `json:"age"`
    Phone string `json:"phone"`
}

func (s *Service) Create(ctx context.Context, req CreateRequest) (*CreateResponse, error) {
    // 参数校验
    if err := req.Validate(); err != nil {
        return nil, errorsx.ValidateError(errorsx.WithMessage(err.Error()))
    }

    // ...
}

命令行功能模块

命令行功能模块基于 cobra

命令行功能被抽象为两部分，一部分称为“业务命令”（command），一部分称为“脚本”（script）

“业务命令”设计用于通过命令行的方式调用业务逻辑
“脚本”设计用于执行开发过程中的临时脚本任务，例如：进行数据修复
“业务命令”被注册为应用程序的 business 子命令，“脚本”被注册为应用程序的 script 子命令

命令行目录规范：

“业务命令”和“脚本”的注册位于 internal/app/command/command.go 文件中
“业务命令”部分：
- “业务命令”在 internal/app/command/handler 目录中进行定义
- 应按照不同的职责对包进行纵向拆分，例如：post、user、comment 三个业务模块，每一个模块都独立对外提供相应的功能
- 每个业务模块都是一个单独的包，对应 business 命令的子命令，例如：./bin/app business post
- 业务模块中的每个方法都抽离为一个单独的文件，对应业务模块命令的子命令，例如：./bin/app business post add
“脚本”部分：
- “脚本”在 internal/app/command/script 目录中进行定义
- 脚本文件的名称为 S+10 位时间戳，说明脚本的创建时间
- 文件中的结构体名称为脚本文件名，并且实现 Script 接口
- 结构体的注释应该说明此脚本的用途

注意：

不要通过系统的定时任务来频繁调用命令行功能的“业务命令”或“脚本”，因为每次执行都会初始化数据库连接、日志等资源，这可能会造成性能问题

如果需要频繁调用某个业务逻辑，可以考虑是否应该使用 cron 功能模块

`cron` 定时任务功能模块

定时任务功能模块基于 cron

其可以提供最小时间单位为秒的定时任务
可明确知道项目中有那些定时任务

定时任务规范：

任务在 internal/app/cron/cron.go 文件中进行注册
在 internal/app/cron/job 目录中进行定义
任务结构体的名称为任务文件名，并且实现 cron.Job 接口
结构体的注释应该说明此任务的用途

如何部署

`Dockerfile`

Dockerfile 文件位于项目根目录

`docker-compose`

docker-compose 编排文件位于 deploy/docker-compose 目录中

部署前根据需要将 docker-compose.yaml.example 或 docker-compose-dev.yaml.example 拷贝为 docker-compose.yaml，然后根据 docker-compose 运行

`Kubernetes`

Kubernetes 编排文件位于 deploy/kubernetes 目录中

Kubernetes 的方式基于 helm，部署前需要将 values.yaml.example 拷贝为 values.yaml

然后执行：

$ kubectl apply -Rf deploy/kubernetes

# 或

$ helm install go-scaffold kubernetes/

Name		Name	Last commit message	Last commit date
Latest commit History 301 Commits
.github/workflows		.github/workflows
assets/casbin		assets/casbin
bin		bin
cmd/app		cmd/app
deploy		deploy
docs/images		docs/images
etc		etc
internal/app		internal/app
logs		logs
pkg		pkg
proto		proto
.air.conf.example		.air.conf.example
.dockerignore		.dockerignore
.gitignore		.gitignore
.releaserc.json		.releaserc.json
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
go.mod		go.mod
go.sum		go.sum
openapi.yaml		openapi.yaml

License

Littleboyss/go-scaffold

Folders and files

Latest commit

History

Repository files navigation

介绍

架构图

生命周期

目录结构

如何运行

go build 或 go run

make

docker-compose

热重启

运行子命令或脚本

依赖注入

配置

配置模型

远程配置

监听配置变更

日志

错误处理

转换为 HTTP 状态码

将 GRPC 错误转换为 Error

组件

Casbin

Client

gRPC 客户端

Discovery 服务发现与注册

Ent

orm

如何配置多数据库

Redis 客户端

trace

uid

transport 层

HTTP

响应

swagger 文档生成

如何访问 swagger 文档

service 层

命令行功能模块

cron 定时任务功能模块

如何部署

Dockerfile

docker-compose

Kubernetes

About

Resources

License

Stars

Watchers

Forks

Releases

Packages 0

Languages

`go build` 或 `go run`

`make`

`docker-compose`

转换为 `HTTP` 状态码

将 `GRPC` 错误转换为 `Error`

`Casbin`

`Client`

`gRPC` 客户端

`Discovery` 服务发现与注册

`Ent`

`orm`

`Redis` 客户端

`trace`

`uid`

`transport` 层

`HTTP`

`swagger` 文档生成

如何访问 `swagger` 文档

`service` 层

`cron` 定时任务功能模块

`Dockerfile`

`docker-compose`

`Kubernetes`

Packages