gitee.com/woood2/luca@v1.0.4/docs/README.md

### 概述
LUCA Enterprise Framework（简称luca）是一款支持多入口、开箱即用的企业级Golang框架。
在设计哲学上，luca更接近于 [整洁架构](https://book.douban.com/subject/30333919/) ，而非 [Spring](https://spring.io/) 这种包办一切的大管家。
- 支持4种作业类型：Restful服务、微服务、定时任务、队列消费。
- 配套设施整合：注册/配置中心、链路追踪、日志收集、指标监控、熔断器、API文档。
- 程序设计实践：错误处理、分层、依赖注入、数据库、缓存、多环境、优雅关闭、灰度发布、单元测试。

![avatar](https://gitee.com/woood2/luca/raw/master/docs/overview.png)

### 初始化
```
wget https://gitee.com/woood2/luca/raw/master/scripts/gen.sh
chmod +x ./gen.sh
./gen.sh
```

### 目录结构
遵循：[社区规范](https://github.com/golang-standards/project-layout/blob/master/README_zh.md)  

``` 
├── cmd
│   ├── backend                     Restful服务
│   │   ├── README.md
│   │   ├── docs                    swagger文档
│   │   │   ├── docs.go
│   │   │   ├── swagger.json
│   │   │   └── swagger.yaml
│   │   ├── internal
│   │   │   ├── assembly            装配器
│   │   │   │   ├── route.go
│   │   │   │   └── sdk.go
│   │   │   ├── controller          C层
│   │   │   │   └── app.go
│   │   │   └── middleware          中间件
│   │   │       ├── auth.go
│   │   │       ├── metrics.go
│   │   │       ├── oplog.go
│   │   │       ├── perm.go
│   │   │       └── trace.go
│   │   └── main.go
│   ├── consumer                    队列消费
│   │   ├── internal
│   │   │   ├── alarm               告警
│   │   │   │   ├── alarm.go
│   │   │   │   └── watcher.go
│   │   │   ├── handler             C层
│   │   │   │   ├── greet_one.go
│   │   │   │   ├── greet_two.go
│   │   │   │   └── groups.go
│   │   │   ├── middleware          中间件
│   │   │   │   ├── logging.go
│   │   │   │   ├── metrics.go
│   │   │   │   └── trace.go
│   │   │   └── subscriber          订阅者
│   │   │       ├── chain.go
│   │   │       ├── msg_handler.go
│   │   │       ├── retry_consumer.go
│   │   │       └── subscriber.go
│   │   └── main.go
│   ├── cron                        定时任务
│   │   ├── internal
│   │   │   ├── handler             C层
│   │   │   │   ├── greet.go
│   │   │   │   ├── hello.go
│   │   │   │   └── set.go
│   │   │   ├── job                 作业
│   │   │   │   ├── chain.go
│   │   │   │   ├── job.go
│   │   │   │   └── list.go
│   │   │   └── middleware          中间件
│   │   │       ├── logging.go
│   │   │       └── trace.go
│   │   └── main.go
│   └── micro                       微服务
│       ├── internal
│       │   ├── endpoint            C层
│       │   │   ├── check_perm.go
│       │   │   ├── check_token.go
│       │   │   └── validate.go
│       │   ├── grpc                通信层
│       │   │   ├── check_perm.go
│       │   │   ├── check_token.go
│       │   │   ├── grpc_health_v1
│       │   │   │   ├── health.pb.go
│       │   │   │   ├── health.proto
│       │   │   │   ├── health_grpc.pb.go
│       │   │   │   ├── health_impl.go
│       │   │   │   └── protoc.sh
│       │   │   ├── pb
│       │   │   │   ├── protoc.sh
│       │   │   │   ├── server.pb.go
│       │   │   │   ├── server.proto
│       │   │   │   └── server_grpc.pb.go
│       │   │   └── set.go
│       │   ├── middleware          中间件
│       │   │   ├── auth
│       │   │   │   ├── context.go
│       │   │   │   ├── middleware.go
│       │   │   │   ├── option.go
│       │   │   │   └── token.go
│       │   │   ├── chain.go
│       │   │   ├── logging
│       │   │   │   └── middleware.go
│       │   │   └── metrics
│       │   │       └── middleware.go
│       │   ├── output              输出
│       │   │   └── format.go
│       │   └── param               参数
│       │       ├── check_perm.go
│       │       └── check_token.go
│       ├── main.go
│       └── pkg                     SDK
│           ├── check_perm.go
│           ├── check_token.go
│           ├── err.go
│           └── sdk.go
├── configs                         配置文件
│   ├── application-example.yml
│   └── application.yml
├── deployments                     部署
│   ├── docker
│   │   ├── docker-compose-example.yml
│   │   ├── docker-compose.yml
│   │   ├── prometheus-example.yml
│   │   └── prometheus.yml
│   ├── nav-example.html
│   └── nav.html
├── docs                            文档
├── go.mod
├── go.sum
├── internal
│   ├── cache                       缓存
│   │   ├── cache.go
│   │   ├── dict.go         
│   │   ├── key.go
│   │   ├── local.go
│   │   ├── local_test.go
│   │   ├── miss.go
│   │   ├── nop.go
│   │   ├── protector.go
│   │   ├── redis.go
│   │   ├── redis_test.go
│   │   └── serialization.go
│   ├── conf                        配置
│   │   └── attr.go
│   ├── db                          数据库
│   │   ├── gorm.go
│   │   ├── mongo.go
│   │   └── zapgorm2
│   │       └── zapgorm2.go
│   ├── discovery                   服务发现
│   │   └── consul.go
│   ├── errcode                     错误
│   │   ├── business.go
│   │   ├── micro.go
│   │   ├── resp.go
│   │   └── restful.go
│   ├── layer                       分层
│   │   ├── controller.go
│   │   ├── repository.go
│   │   └── service.go
│   ├── log                         日志
│   │   └── zap.go
│   ├── mq                          消息
│   │   ├── greet.go
│   │   └── greet_test.go
│   ├── producer                    队列生产
│   │   ├── sarama_producer.go
│   │   └── scram_client.go
│   ├── repository                  DAO层
│   │   ├── app.go
│   │   ├── app_test.go
│   │   ├── student.go
│   │   └── student_test.go
│   ├── sdk                         SDK引用
│   │   └── demo.go
│   ├── service                     service层
│   │   ├── acl.go
│   │   ├── app.go
│   │   └── app_test.go
│   ├── status                      状态
│   │   ├── ginpprof.go
│   │   ├── hystrix.go
│   │   └── prometheus.go
│   ├── trace                       链路追踪
│   │   └── zipkin.go
│   └── util                        工具
│       ├── file.go
│       ├── jsontime.go
│       ├── md5.go
│       └── test.go
├── scripts                         脚本
│   ├── init.sql
│   ├── init.sh
└── test
    └── grpc_client                 微服务本地测试
        └── main.go
```
    
### 多入口
[cmd/](https://gitee.com/woood2/luca/tree/master/cmd) 默认拥有4个子目录，对应4个入口、4种作业类型。
```
├── cmd
│   ├── backend                     Restful服务
│   │   ├── README.md
│   │   ├── docs                    
│   │   ├── internal
│   │   └── main.go
│   ├── consumer                    队列消费
│   │   ├── internal
│   │   └── main.go
│   ├── cron                        定时任务
│   │   ├── internal
│   │   └── main.go
│   └── micro                       微服务
│       ├── internal
│       ├── main.go
│       └── pkg                     
```

入口专用的代码存放于 [cmd/](https://gitee.com/woood2/luca/tree/master/cmd) 的子目录中，跨入口公用的代码存放于 [internal/](https://gitee.com/woood2/luca/tree/master/internal) 下，例如：
- backend Controller层代码：[cmd/backend/internal/controller/](https://gitee.com/woood2/luca/tree/master/cmd/backend/internal/controller)
- Service层代码：[internal/service/](https://gitee.com/woood2/luca/tree/master/internal/service)
- Repository层代码：[internal/repository/](https://gitee.com/woood2/luca/tree/master/internal/repository)

同一种作业类型，可以创建多个入口。例如：项目中允许存在`backend`与`frontend`两个Restful服务。

示例1：添加`frontend`入口
1. 复制目录：`cp -a cmd/backend cmd/frontend`
2. 在 `cmd/frontend` 路径下批量替换：`backend=>frontend`、`Backend=>Frontend`
3. 修改配置：[internal/conf/attr.go](https://gitee.com/woood2/luca/tree/master/internal/conf/attr.go) 、[configs/application-example.yml](https://gitee.com/woood2/luca/tree/master/configs/application-example.yml) 

示例2：删除`frontend`入口
1. 删除目录：`rm -rf cmd/frontend`
2. 修改配置：[internal/conf/attr.go](https://gitee.com/woood2/luca/tree/master/internal/conf/attr.go) 、[configs/application-example.yml](https://gitee.com/woood2/luca/tree/master/configs/application-example.yml)

### 运行
步骤1：安装Go环境以及所依赖的服务，详见 [deployments/README.md](https://gitee.com/woood2/luca/tree/master/deployments/README.md) 。
  
步骤2：执行init脚本，键入本机IP，生成 `configs/application.yml`。
```
cd scripts
./init.sh
``` 

步骤3：按需修改 `configs/application.yml`。

步骤4：执行 `go run cmd/{xyz}/main.go`。
    
### 配置
文件路径
- 本地开发：`configs/application.yml`
- 远程部署：`程序运行目录/application.yml`

文件结构
- stub：用于设置本机host以及配置类型。
- detail：可供多个go程序实例复用的详细配置，根据stub设置决定其存放位置。

stub详解

|  一级   | 二级  | 说明  | 示例  |
|  ----  | ----  | ----  | ----  |
| host  |  | 本机IP地址 | 192.168.1.100 |
| configType  |  | file:本地文件 consul:配置中心 | consul |
| dataKey  |  | consul kv键名 | config/luca/attr |
| consul  |  |  |  |
|   | host | consul主机 | 192.168.1.100 |    
|   | port | consul端口 | 8500 |    
    
本地文件示例
```
application.yml

# === stub part ===
host: {ip}
configType: file
dataKey: 
consul:
  host: 
  port: 
# === detail part ===
project: luca
mysql:
  user: root
  pwd: '123456'
  host: {ip}
  port: 3306
  db: luca
```

配置中心示例
```
application.yml

# === stub part ===
host: {ip}
configType: consul
dataKey: config/luca/attr
consul:
  host: {ip}
  port: 8500

访问consul后台，配置KV字典如下：
< Key/Values < config < luca 
attr 

Value 
    # === detail part ===
    project: luca
    mysql:
      user: root
      pwd: '123456'
      host: {ip}
      port: 3306
      db: luca
```
    
detail详解

|  一级   | 二级  | 说明  | 示例  |
|  ----  | ----  | ----  | ----  |
| project  |  | 项目名 | luca |
| env  |  | 环境:dev/demo/test/pre/pro | dev |
| consoleLog  |  | true:控制台日志<br/>false:文件日志 | true |
| pprof  |  |  | |
|   | user | 用户名 | qjs |
|   | pwd | 密码 | 731 |
| mysql  |  |  | |
|   | user | 用户名 | root |
|   | pwd | 密码 | 123456 |
|   | host | 主机 | 192.168.1.100 |
|   | port | 端口 | 3306 |
|   | db | 数据库 | luca |
|   | maxOpenConns | 最大连接数 | 30 |
|   | maxIdleConns | 最大空闲连接数 | 10 |
| mongo  |  |  | |
|   | user | 用户名 | woood2 |
|   | pwd | 密码 | 123456 |
|   | host | 主机 | 192.168.1.100 |
|   | port | 端口 | 27017 |
|   | db | 数据库 | luca |
|   | maxPoolSize | 最大连接数 | 30 |
|   | minPoolSize | 最小连接数 | 10 |
| redis  |  |  | |
|   | addr | 地址 | 192.168.1.100:6379 |
|   | pwd | 密码 |  |
|   | poolSize | 最大连接数 | 30 |
|   | minIdleConns | 最小空闲连接数 | 10 |
| zipkin  |  |  | |
|   | reporterAddr | 上报地址（允许为空）| 192.168.1.100:6379 |
| kafka  |  |  | |
|   | version | 版本 | 2.5.0 |
|   | brokers | broker地址（允许多个） | 192.168.1.100:9092 |
|   | enableSASL | 是否开启SASL | true |
|   | user | 用户名 | qjs |
|   | password | 密码 | 731 |
|   | algorithm | 算法 | sha256 |
| backend  |  |  | |
|   | addr | Restful服务地址 | :8080 |
|   | register | 是否注册到consul | true |
|   | pprofAddr | pprof地址 | :6059 |
|   | metricsAddr | metrics地址 | :8082 |
|   | hystrixPort | hystrix端口 | 8282 |
|   | allowOrigins | 允许来源（允许多个） | * |
| micro  |  |  | |
|   | port | 端口 | 8081 |
|   | register | 是否注册到consul | true |
|   | pprofAddr | pprof地址 | :6060 |
|   | metricsAddr | metrics地址 | :6061 |
|   | hystrixPort | hystrix端口 | 8283 |
| consumer  |  |  | |
|   | pprofAddr | pprof地址 | :6064 |
|   | metricsAddr | metrics地址 | :6063 |
|   | hystrixPort | hystrix端口 | 8084 |
| cron  |  |  | |
|   | pprofAddr | pprof地址 | :6065 |
|   | hystrixPort | hystrix端口 | 8085 |

### 错误处理
luca倡导在项目中基于 [github.com/pkg/errors](https://github.com/pkg/errors) 传递 error，而非使用 panic-recover。

统一的错误字典
- Restful服务通用错误：[internal/errcode/restful.go](https://gitee.com/woood2/luca/tree/master/internal/errcode/restful.go)
- 微服务通用错误：[internal/errcode/micro.go](https://gitee.com/woood2/luca/tree/master/internal/errcode/micro.go)
- 业务逻辑错误：[internal/errcode/business.go](https://gitee.com/woood2/luca/tree/master/internal/errcode/business.go)

为了对调用者友好，微服务SDK冗余了一份错误字典
- 微服务通用错误：[cmd/micro/pkg/err_micro.go](https://gitee.com/woood2/luca/tree/master/cmd/micro/pkg/err_micro.go)
- 业务逻辑错误：[cmd/micro/pkg/err_business.go](https://gitee.com/woood2/luca/tree/master/cmd/micro/pkg/err_business.go)

更新方式
```
cd cmd/micro/pkg
./update_err.sh
```

Resp结构体：[internal/errcode/resp.go](https://gitee.com/woood2/luca/tree/master/internal/errcode/resp.go)
```
package errcode
//4 restful & micro service
type Resp struct {
	ErrCode string      `json:"errCode"`
	ErrMsg  string      `json:"errMsg"`
	Data    interface{} `json:"data"`
	TraceID string      `json:"traceID"` //only 4 restful
	Stack   string      `json:"stack"`   //only 4 restful, non-pro env
}
```

一次`Restful请求`的错误处理
- 当程序走入错误分支或者发生内部错误，一个`error`对象被逐层传递到最上层的`controller`中。
- 持有这个`error`对象的`controller`前往`错误字典`查找对应的`错误代码`，并封装成`Resp`对象作为http返回值。
- 每个`错误代码`对应一条程序分支，通常由用户的错误操作引发，例如"用户名或密码错误"，无需记录日志，`http code`为200。
- 找不到`错误代码`的`error`统一归为`errcode.ServerErr`并且记录一条error等级的日志，`http code`为500。
- 顺利走完程序主分支的成功请求，`Resp.ErrCode`与`Resp.ErrMsg`均为空值，`Resp.Data`携带返回值正文，`http code`为200。

一次`微服务调用`的错误处理
- 当程序走入错误分支或者发生内部错误，一个`error`对象被逐层传递到最上层的`endpoint`中。
- 持有这个`error`对象的`endpoint`前往`错误字典`查找对应的`错误代码`，并封装成`Resp`对象作为返回值。
- 每个`错误代码`对应一条程序分支，通常由client的非法调用引发，例如"非法的鉴权凭证"，无需记录日志，无需对接`hystrix`。
- 找不到`错误代码`的`error`需要记录一条error等级的日志，并且对接`hystrix`。
- 顺利走完程序主分支的成功调用，`Resp.ErrCode`与`Resp.ErrMsg`均为空值，`Resp.Data`携带返回值正文。

Crash-free
- 尽管luca不主张使用`panic-recover`，但无法保证第三方库没有`panic`，必须在`goroutine`级别进行`recover`，保障整个进程的运行安全。
- 捕获`panic`后，任何作业类型均会记录一条error等级的日志。
- Restful请求中发生`panic`，`http code`为500。
- 微服务调用中发生`panic`，需要对接`hystrix`，error日志由调用端（SDK）负责记录。
    
### Restful服务
luca基于 [gin](https://github.com/gin-gonic/gin) 提供Restful服务。

示例
- 认证：[cmd/backend/internal/middleware/auth.go](https://gitee.com/woood2/luca/tree/master/cmd/backend/internal/middleware/auth.go)
- 授权：[cmd/backend/internal/middleware/perm.go](https://gitee.com/woood2/luca/tree/master/cmd/backend/internal/middleware/perm.go)
- validator：[cmd/backend/internal/controller/app.go](https://gitee.com/woood2/luca/tree/master/cmd/backend/internal/controller/app.go)
- CRUD：[cmd/backend/internal/controller/app.go](https://gitee.com/woood2/luca/tree/master/cmd/backend/internal/controller/app.go)

基于 [gin-contrib/cors](https://github.com/gin-contrib/cors) 支持CORS。
    
允许多个来源：
```
backend:  
  allowOrigins:
    - "http://google.com"
    - "http://facebook.com"    
```
允许任意来源：
```
backend:  
  allowOrigins:
    - "*"       
```

基于 [swaggo/swag](https://github.com/swaggo/swag/blob/master/README_zh-CN.md) 支持API文档。  
示例
- 全局注释：[cmd/backend/main.go](https://gitee.com/woood2/luca/tree/master/cmd/backend/main.go) 
- API注释：[cmd/backend/internal/controller/app.go](https://gitee.com/woood2/luca/tree/master/cmd/backend/internal/controller/app.go)
- 更新命令：`cd cmd/backend && swag init`

### 微服务
luca 基于 [go-kit](https://github.com/go-kit/kit) 提供micro service。 
 
详细选型
- 通信：[gRPC](https://doc.oschina.net/grpc) 
- 注册/配置中心：[consul](https://developer.hashicorp.com/consul/docs/architecture) 
- 熔断器：[hystrix](https://pkg.go.dev/github.com/afex/hystrix-go/hystrix) 
- validator：[go-playground/validator](https://github.com/go-playground/validator) 

API示例
- [cmd/micro/internal/grpc/check_perm.go](https://gitee.com/woood2/luca/tree/master/cmd/micro/internal/grpc/check_perm.go)
- [cmd/micro/internal/grpc/check_token.go](https://gitee.com/woood2/luca/tree/master/cmd/micro/internal/grpc/check_token.go)

SDK示例
- [cmd/micro/pkg/check_perm.go](https://gitee.com/woood2/luca/tree/master/cmd/micro/pkg/check_perm.go)
- [cmd/micro/pkg/check_token.go](https://gitee.com/woood2/luca/tree/master/cmd/micro/pkg/check_token.go)

本地测试
- [test/grpc_client/main.go](https://gitee.com/woood2/luca/tree/master/test/grpc_client/main.go) 

### 定时任务
luca基于 [robfig-cron](https://github.com/robfig/cron) 提供定时任务。  

基于redis实现`Secondary Nodes`模式的高可用，详见 [main.go](https://gitee.com/woood2/luca/tree/master/cmd/cron/main.go) 中的`campaign()`与`renew()`。

job示例
- [cmd/cron/internal/handler/greet.go](https://gitee.com/woood2/luca/tree/master/cmd/cron/internal/handler/greet.go)
- [cmd/cron/internal/handler/hello.go](https://gitee.com/woood2/luca/tree/master/cmd/cron/internal/handler/hello.go)

### 消息队列
luca 基于 [Shopify/sarama](https://github.com/Shopify/sarama) 支持 Kafka。 

application.yml
```
kafka:
  version: 2.5.0
  brokers:
    - {ip}:9092
  enableSASL: true
  user: qjs
  password: '731'
  algorithm: sha256
```

示例
- topic：[internal/mq/greet.go](https://gitee.com/woood2/luca/tree/master/internal/mq/greet.go)
- 生产：[internal/mq/greet_test.go](https://gitee.com/woood2/luca/tree/master/internal/mq/greet_test.go)
- 消费：[cmd/consumer/internal/handler/greet_one.go](https://gitee.com/woood2/luca/tree/master/cmd/consumer/internal/handler/greet_one.go)

### 分层
推荐方案
![avatar](https://gitee.com/woood2/luca/raw/master/docs/layer.png)

controller层包括：
- Restful服务中的 [Controller](https://gitee.com/woood2/luca/tree/master/cmd/backend/internal/controller)
- 微服务中的 [Endpoint](https://gitee.com/woood2/luca/tree/master/cmd/micro/internal/endpoint)
- 定时任务中的 [Handler](https://gitee.com/woood2/luca/tree/master/cmd/cron/internal/handler)
- 队列消费中的 [Handler](https://gitee.com/woood2/luca/tree/master/cmd/consumer/internal/handler)

[service](https://gitee.com/woood2/luca/tree/master/internal/service) 层涵盖：
- Service: CRUD场景常见的服务层
- Domain: [《领域驱动设计》](https://book.douban.com/subject/5344973/) 描绘的领域层

[repository](https://gitee.com/woood2/luca/tree/master/internal/repository) 层负责操作ORM层，luca选择 [GORM](https://gorm.io/zh_CN/docs/index.html)  作为ORM框架。

[sdk](https://gitee.com/woood2/luca/tree/master/internal/sdk) 或 [kafka producer](https://gitee.com/woood2/luca/tree/master/internal/producer/sarama_producer.go) 可视作远程service。

### 依赖注入
在luca中，依赖注入随处可见：

|  被依赖的对象   | 接收注入的对象  |
|  ----  | ----  |
| logger  | 任何需要记录日志的代码 |
| db(mysql、redis、mongo等)  | repository |
| consul client  | sdk |
| kafka producer  | controller、service |
| sdk  | controller、service |
| service  | controller |
| repository  | service |

在Spring的世界中，使用`@Autowired`即可自动装配。但是在luca中，我们需要在以下位置手动装配：
- [cmd/backend/internal/assembly/route.go](https://gitee.com/woood2/luca/tree/master/cmd/backend/internal/assembly/route.go)
- [cmd/micro/internal/grpc/set.go](https://gitee.com/woood2/luca/tree/master/cmd/micro/internal/grpc/set.go)
- [cmd/cron/internal/handler/set.go](https://gitee.com/woood2/luca/tree/master/cmd/cron/internal/handler/set.go)
- [cmd/consumer/internal/handler/groups.go](https://gitee.com/woood2/luca/tree/master/cmd/consumer/internal/handler/groups.go)

### Mysql
luca选择 [GORM](https://gorm.io/zh_CN/docs/index.html) 作为ORM框架。

application.yml
```
mysql:
  user: root
  pwd: '123456'
  host: {ip}
  port: 3306
  db: luca
  maxOpenConns: 30
  maxIdleConns: 10
```

示例
- CRUD：[internal/repository/app.go ](https://gitee.com/woood2/luca/tree/master/internal/repository/app.go)  
- 事务：[AppServiceImpl.Twins](https://gitee.com/woood2/luca/tree/master/internal/service/app.go) 

### MongoDB
luca 基于 [mongo-go-driver](https://github.com/mongodb/mongo-go-driver) 操作MongoDB。
 
application.yml
```
mongo:
  user: woood2
  pwd: '123456'
  host: {ip}
  port: 27017
  db: luca
  maxPoolSize: 30
  minPoolSize: 10
```

示例
- [internal/repository/student.go](https://gitee.com/woood2/luca/tree/master/internal/repository/student.go)

### 缓存
luca提供了统一的 [Cache](https://gitee.com/woood2/luca/tree/master/internal/cache/cache.go) 接口以及3种默认实现：
- [LocalCache](https://gitee.com/woood2/luca/tree/master/internal/cache/local.go)：基于本地内存的cache实现，性能水平100w/sec。
- [RedisCache](https://gitee.com/woood2/luca/tree/master/internal/cache/redis.go) ：基于redis的cache实现，性能水平1w/sec。
- [NopCache](https://gitee.com/woood2/luca/tree/master/internal/cache/nop.go)：基于「无」的cache实现。

其中，[RedisCache](https://gitee.com/woood2/luca/tree/master/internal/cache/redis.go) 基于 [go-redis](https://github.com/go-redis/redis) 操作Redis，对应配置：
```
redis:
  addr: {ip}:6379
  pwd: ''
  poolSize: 30
  minIdleConns: 10
```

默认采用json序列化，允许修改 [serialization.go](https://gitee.com/woood2/luca/tree/master/internal/cache/serialization.go) 替换成其它序列化算法。

示例
- Local: [local_test.go](https://gitee.com/woood2/luca/tree/master/internal/cache/local_test.go)
- Redis: [redis_test.go](https://gitee.com/woood2/luca/tree/master/internal/cache/redis_test.go)
- 防雪崩：[AppServiceImpl.GetByKeyFromCacheSafely](https://gitee.com/woood2/luca/tree/master/internal/service/app.go)

### logger
日志维度

|  日志维度   | 说明  |  日志库   | 输出  | 接入 [zipkin](https://zipkin.io/)  | 接入 [EFK](https://blog.csdn.net/easylife206/article/details/112057417)  |
|  ----  | ----  |  ----  | ----  |  ----  | ----  |
|  服务日志   | 服务运行周期中的启动、关闭和状态日志 |  标准库 [log](https://pkg.go.dev/log)   | stdout/stderr  |  否   | 否  |
|  请求日志   | 请求/作业周期内产生的日志  |  [uber-go/zap](https://github.com/uber-go/zap)  | stdout/stderr或者./zap.log文件  |  是   | 是  |

application.yml（zap配置）

|  名称   | 说明  |
|  ----  | ----  |
| env  | pro: 日志等级Info<br/>其它: 日志等级Debug |
| consoleLog  | true: 控制台日志<br/>false: 文件日志（./zap.log） |

内置日志点（zap logger）

|  围绕   | 类型  | 说明  | 等级  |
|  ----  | ----  | ----  | ----  |
| 请求/作业 |  |  |  |
|  | access日志 | 覆盖所有作业类型 | info |
|  | error日志  | 覆盖所有作业类型 | error |
|  | oplog日志  | 用于Restful服务 | info |
| GORM |  |  |  |
|   | sql日志   |  | debug |
|   | slow日志  |  | warn |
|   | error日志 |  | error |
| SDK |  |  |  |
|  | call日志  |  | debug |
|  | error日志 |  | error |

### 链路追踪
luca 选择 [zipkin](https://zipkin.io/) 作为链路追踪的实现引擎。

跟踪范围
- Restful请求
- 微服务调用
- 定时任务作业
- 队列消费作业
- 其它，如单元测试

从 gin.Context 提取 TraceID:
```
func (ctr AnyController) Demo(c *gin.Context) {
    traceID := trace.GinID(c)
    ...
}
```

从 context.Context 提取 TraceID:
```
func(ctx context.Context){
    traceID := trace.ID(ctx)
    ...
}
```

向 GORM logger 传递 TraceID:
```
func (repo *AppRepoImpl) Create(ctx context.Context, app *App) (int, error) {
    result := repo.DB.WithContext(ctx).Create(app)
    ...
}
```

向 Restful 请求返回 TraceID:
```
package errcode

type Resp struct {
    ErrCode string      `json:"errCode"`
    ErrMsg  string      `json:"errMsg"`
    Data    interface{} `json:"data"`
    TraceID string      `json:"traceID"` 
    Stack   string      `json:"stack"`   
}
```

application.yml

|  一级   | 二级  | 说明  | 示例  |
|  ----  | ----  | ----  | ----  |
| zipkin |  |  |  |
|  | reporterAddr | 上报地址（允许为空） | http://192.168.0.100:9411/api/v2/spans |

zipkin server
- 安装：[deployments/README.md](https://gitee.com/woood2/luca/tree/master/deployments/README.md)
- 访问：`deployments/nav.html`
- 为性能考虑，生产环境建议关闭zipkin server，只需要将Zipkin.ReporterAddr设置为空。

### 日志收集
luca 选择 [EFK](https://blog.csdn.net/easylife206/article/details/112057417) 日志收集方案：
- 通过 [fluentd](https://docs.fluentd.org) 从 ./zap.log 文件中读取日志。
- 将收集来的日志数据存入 [elastic search](https://www.elastic.co/cn/what-is/elasticsearch) 。
- 通过 [Kibana](https://www.elastic.co/cn/kibana/) 界面查询日志。

EFK 安装、使用
- 详见 [deployments/EFK.md](https://gitee.com/woood2/luca/tree/master/deployments/EFK.md)

### pprof
支持 [pprof](https://pkg.go.dev/net/http/pprof) 的Go进程：
- Restful服务
- 微服务
- 定时任务
- 队列消费

application.yml
```
pprof:
  user: qjs
  pwd: '731'

backend:  
  pprofAddr: ":6059"
  
micro:
  pprofAddr: ":6060"
  
consumer:
  pprofAddr: ":6064"

cron:
  pprofAddr: ":6065"
```

访问
- 详见 `deployments/nav.html`

### metrics
luca 为3种作业类型接入 [prometheus](https://prometheus.io/) 指标统计：
- Restful请求
- 微服务调用
- 队列消费作业

application.yml
```
backend:  
  metricsAddr: ":8082"
  
micro:
  metricsAddr: ":6061"
  
consumer:  
  metricsAddr: ":6063"  
```

安装 prometheus
- 详见 [deployments/README.md](https://gitee.com/woood2/luca/tree/master/deployments/README.md)

访问 prometheus
- 详见 `deployments/nav.html`

### 多环境
推荐方案

|  环境   | env  | 部署位置 | 部署套数 | 用途  |git分支 | zap等级 | swagger |
|  ----  | ----  | ----  | ----  | ---- | ---- | ---- | ---- |
| 本机 | dev  | 本机  | 1/每人 | 开发 | 个人、feature、fixbug | Debug | 开启 | 
| dev | dev | 远程 | 1 | 联调 | dev | Debug | 开启 |
| demo | demo | 远程 | 1 | 对客演示 | demo | Debug | 开启 |  
| test | test | 远程 | \>=1 | 测试 | test | Debug | 开启 |   
| pre | pre | 远程 | 1 | 发版演练 | pre | Debug | 开启 |  
| pro | pro | 远程 | \>=1 | 生产 | master | Info | 关闭 |  

本机 & dev
- 允许本机环境与dev环境共用同一套资源，如数据库、消息队列等。
- 允许本机程序单向依赖dev环境的微服务，只需在本机配置dev环境的consul地址，并且将Backend.Register、Micro.Register设置为false。

demo
- 假如demo环境的使用频率较低，建议按需构建。
- 考虑到demo环境的不确定性，暂不纳入 `git 分支策略`。

git 分支策略
![avatar](https://gitee.com/woood2/luca/raw/master/docs/git-branch.png)

git 分支命名

|  分支   | 命名规则  | 示例 |
|  ----  | ----  | ----  |
| 主分支 | master  | -  |
| 开发 | dev  | -  |
| 演示 | demo  | -  |
| 测试 | test  | -  |
| 预生产 | pre  | -  |
| feature | {name}-feature  | first-feature、second-feature  |
| fixbug | {name}-fixbug  | stackoverflow-fixbug  |
| 个人 | 姓名全拼、缩写  | qiujiashu、qjs  |
 
### 优雅关闭
支持优雅关闭的Go进程
- Restful服务
- 微服务
- 定时任务
- 队列消费

工作原理
1. 接收来自kill命令的信号量。
2. 停止接收新的作业。
3. 等待正在进行中的作业完成或者超时（默认：5秒）。
4. 关闭进程。

### 灰度发布 
luca支持微服务及Restful服务的灰度发布，以实现程序的不停服更新。

前提
- 不论是Restful服务还是微服务，运行的实例数量必须是两个及以上，单机模式不支持灰度发布。
- Restful服务需要前置一个nginx反向代理，并且借助consul-template监视实例列表的变化。详见：[Load Balancing with NGINX and Consul Template](https://developer.hashicorp.com/consul/tutorials/load-balancing/load-balancing-nginx)

工作原理
- 发布程序的新版本时，分批重启集群中的实例。
- 实例重启前通知consul注销自己，将流量导向其它运行中的实例。
- 等待实例重启完成，再次注册到consul上迎回流量。
- 发布过程中，始终有实例运行，提供连续服务。

### 单元测试
luca鼓励开发者采用主流的`table driven`模式进行单元测试。

单元测试的优先目标是计算逻辑，而不是IO。对于一般的CRUD，单元测试意义不大，API测试是更适合的选择。

luca支持在CI/CD中跳过指定的单元测试：
```
CLI
    CI=true go test -v -cover ./...

internal/util/test.go
    package util

    import (
        "os"
        "testing"
    )

    func CI() bool {
        return os.Getenv("CI") != ""
    }

    func SkipCI(t *testing.T) {
        if CI() {
            t.Skip("Skipping testing in CI environment")
        }
    }

xxx_test.go
    func TestMain(m *testing.M) {
        if !util.CI() {
            attr := conf.Load("application.yml", "configs/application.yml")
            ..
        }
        m.Run()
    }

    func TestXXX(t *testing.T) {
        util.SkipCI(t)
        ..
    }