Go Engineering - CLI
应用框架
命令行参数解析 - Pflag
配置文件解析 - Viper
应用的命令行框架 - Cobra
命令需要具备 help 功能
命令需要能够解析命令行参数和配置文件
命令需要能够初始化业务代码,并最终启动业务进程
Pflag
命令行参数解析工具 - Kubernetes / Istio / Helm / Docker / Etcd / …
Flag
一个命令行参数会被解析成一个 Flag 类型的变量
1234567891011121314// A Flag represents the state of a flag.type Flag struct { Name string // name as it appears on command line Shorthand string // one-letter abbreviated flag Usage string ...
Go Engineering - Log
功能设计基础功能
支持基本的日志信息 - 时间戳、文件名、行号、日志级别、日志信息
支持不同的日志级别 - Debug / Info / Warn / Error / Panic / Fatal
logrus 支持 Trace 日志级别,Trace 不是必须的
Trace 和 Panic 是可选的级别
支持自定义配置 - 不同的环境采用不同的配置
开发环境的日志级别为 Debug,而生产环境的日志级别为 Info
通过配置,可以在不重新编译代码的情况下,改变记录日志的行为
支持输出到标准输出和文件
至少实现 6 个日志级别
日志调用时的属性
输出级别
glog.Info(“This is info message”)
开关级别
启动程序时,期望哪些输出级别的日志会被打印
glog -v=L - 只有输出级别 ≥L 的日志才会被打印
高级功能
支持多种日志格式 - TEXT / JSON / …
开发环境采用 TEXT 格式,生产环境采用 JSON 格式
按日志级别分类输出 - Error 级别日志可 ...
Go Engineering - Error Code
预期功能
有业务 Code 码标识 - HTTP Code 码有限
安全 - 对内对外展示不同的错误信息
设计方式
无论请求成功与否,都返回 200,在 HTTP Body 中包含错误信息
HTTP Code 通常代表 HTTP Transport 层的状态信息
缺点:性能不佳(需解析 Body) + 对客户端不友好
返回 4xx or 5xx,并在 Body 中返回简单的错误信息
返回 4xx or 5xx,并在 Body 中返回详细的错误信息 - 推荐
设计思路
区别于 http status code,业务码需要有一定的规则,可以通过业务码判断出是哪类错误
请求出错时,可以通过 http status code,直接感知到请求出错
需要在请求出错时,返回详细的信息:Code + Message + Reference(Optional)
返回的错误信息,需要是可以直接展示给用户的安全信息,不能包含敏感信息
但同时也要有内部更详细的错误信息,方便 Debug
返回的数据格式应该是固定的,规范的
错误信息要保持简洁,并提供有用的信息
Biz Code
纯数字表示,不同部位代表不同的服务,不 ...
Go Engineering - Doc
Swagger
Swagger 是一套围绕 OpenAPI 规范构建的开源工具
Component
Desc
Swagger Editor
基于浏览器的编辑器,可以编写 OpenAPI 规范,并实时预览
Swagger UI
将 OpenAPI 规范呈现为交互式 API 文档
Swagger Codegen
根据 OpenAPI 规范,生成服务器存根和客户端代码库,涵盖 40 多种语言
OpenAPI
OpenAPI 是一个 API 规范,其前身为 Swagger 规范
通过定义一种用来描述 API 格式或者 API 定义的 DSL,来规范 RESTful API 的开发过程
OpenAPI 3.0 ≈ Swagger 2.0
API 基本信息
对 API 的描述,介绍 API 可以实现的功能
每个 API 上可用的 Path 和 Method
每个 API 的输入和返回参数
验证方法
联系信息、许可证、使用条款和其它信息
OpenAPI 是一个 API 规范,而 Swagger 是实现该 API 规范的工具
go-swagger特性
功能强大、高性能、可以根据代码注释 ...
Go Engineering - Lint
golangci-lint
使用最多
优点
Advantage
Desc
速度快
基于 gometalinter 开发,但比 gometalinter 快 5 倍原因:并行检查 + 复用 go build 缓存 + 缓存分析结果
可配置
支持 YAML 格式的配置文件
IDE 集成
Goland / VS Code
linter 聚合器
不需要单独安装
最少误报数
调整了所集成 linter 的默认配置,大幅度减少误报
良好的输出
颜色、行号等
迭代快
不断有新的 linter 被集成到 golangci-lint 中
选项
配置
同时出现 - 命令行选项 / 配置文件
bool/string/int - 命令行选项
slice - 合并
命令行选项
golangci-lint run -h
Flag
Desc
–print-issued-lines
Print lines of code with issue (default true)
–print-linter-name
Print linter ...
Go Engineering - Makefile
基础语法
https://github.com/seisman/how-to-write-makefile
规则语法
伪目标
变量赋值
特殊变量
自动化变量
功能设计Target
Target
Desc
gen
Generate all necessary files, such as error code files.
format
Gofmt (reformat) package sources (exclude vendor dir if existed).
lint
Check syntax and styling of go sources.
test
Run unit test.
cover
Run unit test and get test coverage.
build
Build source code for host platform.
build.multiarch
Build source code for multiple platforms. See option PLATFORMS.
image
Build docker image ...
Go Engineering - RPC API
RPC
Client Stub / Server Skeleton
Client 通过本地调用,调用 Client Stub
Client Stub 将参数打包(Marshalling)成一个消息,并发送这个消息
Client 所在的 OS 将消息发送给 Server
Server 端接收到消息后,将消息传递给 Server Stub
Server Stub 将消息解包(Unmarshalling)得到参数
Server Stub 调用服务端子函数,处理完毕后,将最终结果按相反步骤返回给 Client
gRPC
Google Remote Procedure Call
简介
由 Google 开发的高性能、开源、跨语言的通用 RPC 框架
基于 HTTP 2.0 协议 + 默认采用 Protocol Buffers 数据序列化协议
特征
支持多语言 - Go、Java、C++、Node.js、Python 等
基于 IDL - Interface Definition Language 文件定义服务
通过 proto3 工具生成指定语言的数据结构、Server API 以及 Cli ...
Go Engineering - RESTful API
概念
Representational State Transfer
REST 只是一种软件架构风格
REST 有一系列规范,满足这些规范的 API 称为 RESTful API
REST 规范将所有内容都视为资源,REST 架构对资源的操作对应 HTTP 协议提供的方法
REST 风格适用于很多传输协议,并且 REST 天生与 HTTP 协议相辅相成
HTTP 协议成为了实现 RESTful API 的事实标准
REST 是一种规范,而 RESTful API 是满足 REST 规范的 API 接口
RESTful API 的核心是规范
特点
以资源为中心,所有东西都抽象成资源,所有行为都应该在资源上的 CRUD 操作
资源对应 OOP 中的对象
资源使用 URI 标识,每个资源实例都有唯一的 URI 标识
资源是有状态的,使用 JSON/XML 等在 HTTP Body 里表征资源的状态
客户端通过 HTTP 动词,对服务端资源进行操作,实现 Representational State Transfer
操作是无状态的,每个 RESTful API 请求都包含了所 ...
Go Engineering - Design Pattern
设计模式
创建型模式
提供了一种在创建对象的同时隐藏创建逻辑的方式
单例模式饿汉方式
在包被加载时创建
12345678910package singletontype Singleton struct {}var instance *Singleton = &Singleton{}func GetInstance() *Singleton { return instance}
懒汉方式
在第一次使用时创建 - 使用最多,但非并发安全,需要加锁
不加锁1234567891011121314package singletontype Singleton struct {}var instance *Singleton// GetInstance is not thread-safefunc GetInstance() *Singleton { if instance == nil { instance = &Singleton{} ...
Go Engineering - Elegant Project
优雅项目
Go 应用
代码结构
按功能拆分 - Kubernetes / Docker / Helm / Prometheus
代码规范
编码规范 - https://github.com/xxjwxc/uber_go_guide_cn
静态代码检查 - https://github.com/golangci/golangci-lint
最佳实践
https://go.dev/doc/effective_go
https://go.dev/wiki/CodeReviewComments
https://rakyll.org/style-packages/
代码质量
单元测试
可测试
将依赖的数据库等抽象成接口,在被测代码中调用接口的方法,在测试时传入 Mock 类型
尽量减少 function 中的依赖 + 依赖是容易 Mock 的
高覆盖率
Code Review
Mock 工具
https://github.com/golang/mock
官方 Mock 框架,与 Golang 内置的 testing 包集成,最常用
实现基于 interface 的 ...