leeframe

如何运行

独立部署运行

安装依赖

依赖go1.17、mysql、redis，需要自行安装。

导入表和数据

执行sql目录下的全部sql文件进行表创建和数据导入。

编辑配置

复制configs目录下的配置模板mode_configs.toml.example并重命名为dev_configs.toml文件到configs目录

环境配置mode命名规则说明：

• dev: 开发环境
• fat: 测试环境
• uat: 预上线环境
• pro: 正式环境

自行修改服务端口、mysql、redis等连接信息，如：

[server]
  HttpPort = 8000

[language]
  local = "zh-cn"

[mysql]
  Host = "127.0.0.1:3306"
  Name = "lee"
  Password = "123456"
  User = "root"

[redis]
  Host = "127.0.0.1:6379"

启动服务

go run直接运行

执行go run main.go或者go run main.go --env dev将会读取dev_configs.toml配置启动服务 由于使用了pflag包解析命令行，所以需要写为--env，而不是-env参考pflag的"Shorthand"说明

• 可以通过环境变量（env）修改配置值： SERVER_HTTPPORT=9998 go run main.go

• 可以通过参数（flag）修改配置值： go run main.go --env dev --Server.HttpPort=8888 --Mysql.Host=127.0.0.1:3306

• 可以通过环境变量（env）和参数（flag）结合修改配置值 SERVER_HTTPPORT=9998 go run main.go --env dev --Server.HttpPort=8888 --Mysql.Host=127.0.0.1:3306 不同系统设置环境变量的方式不同，此示例为Linux环境下的环境变量设置，其他系统需要自行根据需要配置

make运行

执行make run将会读取dev_configs.toml配置启动服务

访问系统

系统默认访问地址http://localhost:8000/

swagger文档默认访问地址http://localhost:8000/swagger/index.html

docker-compose部署运行

当前仅限dev环境和验证功能使用docker-compose方式部署。

构建镜像

# 构建镜像
docker build -t leeframe:v1.0 .

编辑docker-compose配置

• 可以在environment中设置环境变量（env）修改配置值：

    environment:
      SERVER_HTTPPORT: '8000'
      MYSQL_HOST: 'mysql:3306'
      MYSQL_USER: 'root'
      MYSQL_PASSWORD: '123456'
      MYSQL_NAME: 'leeframe'
      REDIS_HOST: 'redis:6379'
      REDIS_PASSWORD: ''

• 可以在command中设置参数（flag）修改配置值： 由于使用了pflag包解析命令行，所以需要写为--env，而不是-env参考pflag的"Shorthand"说明

    command:
      - --env=dev
      - --Server.HttpPort=8000
      - --Mysql.Host=mysql:3306

启动服务

# 启动mysql、redis、api服务，初次启动或后续启动
docker-compose up -d
# Creating network "leeframe_app-network" with driver "bridge"
# Creating leeframe_mysql_1 ... done
# Creating leeframe_redis_1 ... done
# Creating leeframe_api_1   ... done

访问系统

系统默认访问地址http://localhost:8000/

swagger文档默认访问地址http://localhost:8000/swagger/index.html

mysql默认连接信息：端口3305，用户root，密码123456，连接命令mysql -P 3305 -u root -p

redis默认连接信息：端口6378，连接命令redis-cli -p 6378

停止服务

# 停止mysql、redis、api服务
# 只会停止容器，数据不会清除
docker-compose stop
# Stopping leeframe_api_1   ... done
# Stopping leeframe_mysql_1 ... done
# Stopping leeframe_redis_1 ... done

# 停止并删除mysql、redis、api容器
# 注意：这一步会删除所有数据
docker-compose down
# Stopping leeframe_api_1   ... done
# Stopping leeframe_mysql_1 ... done
# Stopping leeframe_redis_1 ... done
# Removing leeframe_api_1   ... done
# Removing leeframe_mysql_1 ... done
# Removing leeframe_redis_1 ... done
# Removing network leeframe_app-network

框架目录结构说明

• assets 静态资源， 如没有可不要
• build 打包和持续集成，shell脚本等文件
• configs 项目配置，配置文件以及系统常量定义，进行配置读取
• docs 文档目录，如swagger文件等
• initialize 项目初始化
• internal 项目内部代码
  • controller controller层，包含controller文件等;根据业务划分文件，如用户为user.go， open为对外提供的controller
  • middleware 项目中间件， 如JWT，Cors等
  • model model层，包含表对应结构体，以及数据库操作等;根据业务划分，如用户为user.go，数据库通用操作封装在common.go文件中
  • pkg 项目依赖如数据库，缓存以及日志包，工具包，验证器，请求和响应方法封装等
    • redis redis缓存的初始化以及基本操作的封装
    • http 请求和返回体的封装， 错误码等
    • logger 日志配置
    • mysql mysql数据库初始化等相关操作
    • utils 工具类，如加解密，数字，字符串的处理等
  • router 路由目录，包含接口路径的注册，分组等
  • schema 出参，入参结构体定义，如req，resp等，通用参数结构体封装在common.go文件中
  • service 业务包，处理项目的业务逻辑等;根据业务划分，如用户为user_service/user.go，open为对外提供的service
  • third_party 云对象存储，SMS等第三方外部接口
• output 其他输出文件目录，如makefile编译的中间文件等
  • bin 可执行文件
• runtime 运行时目录，日志文件等
  • logs 日志目录
• sql sql文件目录
• test 测试文件目录
• Makefile Makefile文件
• Dockerfile Dockerfile文件

代码编写规范

文件和目录规范

参考框架目录结构说明

命名规范

• 变量：使用驼峰形式，如CreatedAt、userID、Username
• 文件名和目录名：使用小写+下划线形式，如third_party、user_service
• 包名：尽量与目录名一致，如package model、package user_service
• 专有名词：id、url这种专有名词尽量使用全小写或全大写，如ID、URL或id、url，少使用Id、Url这种写法

变量命名尽量见名知意，非常用缩写字符尽量备注

注释规范

尽量使用//双斜线+空格这种形式，如

// List
// @Author: lee

编码规范

方法和函数说明

每个方法或函数前面至少包含方法名、作者、时间、描述四行描述。如：

// List
// @Author: lee
// @Date: 2021-11-29 16:42:48
// @Description: 获取用户列表
func (t *User) List() (list []*User, err error) {}

逻辑说明

尽量在程序代码中说明使用一些特殊逻辑或者magic参数的原因和目的，如

// 添加 1=1 是为了方便组合where条件查询语句
where := `1=1`

submitReq := &schema.SubmitReq{
	Query:      strCreateSQL, // 建表sql，已基于base64解码转成string
	Prefix:     "",           // 不需要前缀
	Anonymized: false,        // 不需要脱敏
}

swag注释规范

至少需要包含方法名、描述、tag分类、接收数据类型、返回数据类型、请求参数（如有），响应信息，路由，http请求方法。如：

// Info 获取用户详情
// @Summary 获取用户详情
// @Description 获取用户详情
// @Tags 公共接口
// @Accept mpfd
// @Produce json
// @Param Request query schema.UserInfoReq true "请求信息"
// @Success 200 {object} http.Response{data=schema.UserInfoData}
// @Router /api/user/info [get]
// @Author: lee
// @Date: 2021-11-30 11:19:28
func (a *userApi) Info(c *gin.Context) {}

api接口统一响应方法

尽量使用同一个方法返回，如http包中的Response：

// package http
// Response setting gin.JSON
func (g *Gin) Response(code int, msg string, data interface{}) {
	g.C.JSON(200, Response{
		Code: code,
		Msg:  msg,
		Data: data,
	})
}

错误码定义

尽量在同一个文件里定义好常用大类错误码，细分错误码和错误提示文本（国际化支持）需要统一定义，如：

package http

const (
	SUCCESS = 200
	ERROR   = 500

	//常用大类的错误码在此定义
	InvalidParams = 400
)

方法返回值

尽量命名方法返回值，如

func (t *User) Create(username string) (id int, err error) {}

mysql和redis公共操作方法

mysql、redis公共方法分别封装在pkg/mysql、pkg/redis里

可以使用公共方法，也可以根据需要在model文件自定义实现

日志记录

尽量在日志中记录方法调用和接口访问的入参和返回值，方便排查和定位问题

尽量在日志中记录error信息和其他有用的信息（用户名、执行的sql等）

尽量使用英文提示（国际化支持）

如：

logger.Info(username, " exec sql: ", sql)
logger.Error("get user info err: ", validation.Error(err))

git规范

分支规范

默认基于dev分支进行开发，也可以创建自己的开发分支或feature分支。

实际项目中，master应设置为保护分支，不能直接提交代码到master，只能从其他分支提PR后merge到master。

可根据需要选择不同的git flow规范。

提交规范

尽量描述清楚本次提交的变动信息，如：

git commit -m "docs(swagger): add user list api"

每次提交代码之前需要生成swagger文档，确保swagger文档能正确生成和保持最新，与代码一并提交。

其他事项

特殊组件版本

依赖swagger 2.0、GORM v2

生成swagger文档

swag init

如没有swag命令需要安装一下。参考：

• 安装swag

go get github.com/swaggo/swag/cmd/swag

时间与时区

由于项目存在跨时区的情况，前后端最好通过unix毫秒时间进行传输，如果必须传输时间字符串，请使用带时区信息的UTC时间。

	// go1.17
	// int64毫秒时间转time.Time
	startTime := time.UnixMilli(req.StartTime)

	// time.Time转int64毫秒时间
	detail = &schema.Detail{
		CreatedAt: one.CreatedAt.UnixMilli(),
	}

http请求方法

由于部分项目可能需要接入工作台，而工作台对部分http请求方法的支持不完善，所以实际项目中强制规定，只能使用GET和POST，不允许使用PUT、PATCH、DELETE等方法。

// 用户
user := api.Group("/user")
{
  // 新建
  user.POST("/create", controller.User.Create)
  // 列表
  user.GET("/list", controller.User.List)
}