# README
Frame
noma frame.
框架优点
- 开发风格类似于Gin, 但包含了常用的外部连接库, 更易用
- 日志默认加上trace_id，故障排除更方便
- 业务指标暴露(Promehtues metrics)
框架功能特性
- 请求支持trace_id 联系上下文,支持快速的日志定位
- 默认采集http 的业务错误码到 prometheus metrics
- 集成 Mysql 客户端
- 集成 Redis 客户端
- 集成了 Http Do Request
- 支持自动创建数据库, 表
基于此框架项目启动说明
- 配置路径: 可以通过环境变量CONFPATH 指定, 如未指定默认: /conf/default.json , 配置内容可以在./docs/config.md 复制
- 基本框架支持 mysql 连接, redis 连接, log 格式化, prometheus 指标采集, 基本的链路追踪, 根据需要配置
- 在 handler 如果要获取 mysql 连接, 可使用 ctx.GetDB() 或 ctx.Redis()
启动示例
type User struct {
ID int `json:"id,omitempty"`
Name string `json:"name,omitempty"`
}
func main() {
app := frame.New()
app.GET("/hello", HelloWorld)
app.Run()
}
// HelloWorld hell world handler
func HelloWorld(c *frame.Context) {
db := c.GetDB("user")
// create user
user := User{Name: "test_user"}
result := db.Create(&user)
if result.Error != nil {
c.Fatalf("failed to create user: %v", result.Error)
}
c.Infof("created user: %v\n", user)
// send http
c.DoHTTP().R().Get("https://httpbin.org/uuid")
c.HTTPError2(http.StatusOK, "X0111", "normal error", errors.New("system panic"))
}
常用指令
- 构建服务
make build
- 启动服务
make run
- 构建build 镜像
build-min-docker
- 更多命令参照 Makefile
特性
git push提交代码时, 自动lint,test,push,docker build,docker push到dockerhub 镜像仓库- 当需要添加
tag时, 自动构建对应tag的docker image - docker image 遵从尽可能小为原则(基于多阶段构建,暂未使用压缩二进制手段), 最小镜像500KB
- 丰富的
makefile命令 - 基于
CodeCov自动生成测试覆盖率 - 将
commitid,BuildGoVersion,BuildSystem写入二进制中, 启动时日志可见,有利于版本和问题定位 runner无需Go环境仍可以正常构建镜像,基于docker多阶段构建- 镜像极小，镜像只有500KiB, 缺点是: 不可以exec 进入容器，在问题排查的时候可能会很困难，暂不适合于生产，如需要生产使用，替换基础镜像即可
如何使用?
使用此模板创建项目后:
-
执行
go mod init例如:go mod init github.com/normastars/frame -
修改
Makefile文件中的最顶端的变量PROJECT_NAME为go mod init指定的项目名字,例如:PROJECT_NAME := "github.com/normastars/frame" -
如需支持
特性5, 需要在对应仓库->Settings->Secrets创建秘钥CODECOV_TOKEN, 对应值请登录: https://www.codecov.io/ 使用GitHub 关联登录,然后导入对应仓库后自动生成值,然后回写至 github 仓库秘钥 -
修改相关配置
- 如需支持推送镜像到
dockerhub, 为对应仓库配置秘钥DOCKERHUB_USERNAME和DOCKERHUB_PASSWORD, - 在仓库配置秘钥
IMAGE_NAME来指定镜像名字，例如:imyuliz/template-go
- 如需支持推送镜像到
遇到问题如何处理?
- 主题思路请参考: https://gocn.vip/topics/9839
- 如想查找丰富的Action库,官方地址: https://github.com/marketplace?type=actions
- 如需基于此模板自定义action,请查看GitHub Actions Workflow 的完整语法: https://help.github.com/articles/workflow-syntax-for-github-actions
- 如需修改
docker镜像推送仓库或者触发配置等一些列问题(如推送到指定仓库)请查看 README: https://github.com/imyuliz/Publish-Docker-Github-Action - 如关注自动发布细节信息 https://github.com/marketplace/actions/goreleaser-action
- 如想讨论如何构建Go 最小镜像 https://juejin.im/post/6844904174396637197 https://juejin.im/post/6844904174396637197 https://gocn.vip/topics/10359
常见命令
- 手动测试镜像构建
docker build -t imagename:v0.0.1 -f build/docker/Dockerfile . - 发布新版本
git tag v1.0.0 && git push --tags
Git 提交规范
- 在提交 Commit message 信息时, 应该保证 message 能够简要说明此次变更的性质和作用域。 比如:
fix #issue: math/big: fix typo in documentation for Int.Exp
- 当代码变更需要引入第三方包时, 单独单独提交一个commit, 来说明对第三方包的变更, 通常, 会使用:
vendor: add package name的方式来提交 commit 信息。 这样有利于 code review。 - 提交代码时, 一个功能特性或者bug fix 应该独占一个 commit, 而不能把多个特性揉合成一个 commit 提交代码, 因为这要非常不利于 code review 和 代码追溯。
常用的一些提交术语:
feat: 新特性
fix: bug 被完全修复
update: issue/bug 只有部分被修复, 还需要提高和改善
docs: 文档变更
vendor: 代码的依赖包整理
style: 改变代码的风格但是未影响代码的功能和意义(比如对 空格, 格式化等的修改)
refactor: 既不修正错误也不添加功能的代码更改
perf: 提高代码的性能.
test: 对单元测试进行添加/删除/修改
build: 构建工具更新
conf: 运行时的配置变更(注: 通常应该配置分离)
cve: 对安全漏洞的修复
chore: 更改构建过程或辅助工具和库，例如生成文档
代码编写规范
- 使用 goreporter 或者相关系统做代码审查和质量评估
- 编程风格遵守vscode代码提示规范,尽可能的避免避免绿色波浪线
- 非内部方法一定有func注释
- 代码质量按照Goreport质量等级规范
- 使用sonar深度分析代码质量
- 使用火焰图性能调优
- 熟悉常见的代码性能分析知识
- 编译时, 把编译环境和
commitid写入程序中, 并通过日志打印出来,有利于问题排查
代码优化习惯
- 尽可能少的在循环体内部创建切片或者map,或者复杂对象,因为这样会造成性能不必要的损失。
- 当既可以使用slice又可以使用map的时候,如果不是非要使用map,那么我们可以多使用slice,因为map在在赋值的时候会信息hash判重,这是因为golang的map是又hashmap实现决定的,slice相当于map来说写入块，但是也比map更占用内存,所以,通常两者都可以的时候,取决于是时间换空间,还是空间换时间.