Go-BackendServerTemplate

Golang 后端服务 模板程序 - 简单版

使用 Golang 实现的后端服务模板程序。

介绍

本模板程序旨在实现一个 Golang 的后端服务，可以是 Http 也可以是其他。为了完成这个目的，我设计了一部分基础套件。

• 日志（支持投递到标准输出、文件、日期切割的文件、自定义输出、多输出合并）
• 命令行参数（支持string、bool、uint、int）
• 配置文件（支持json和yaml格式，也可以自定义解析器）
• 退出信号量捕获（在posix系统上可以使用信号量捕获退出信号，并做清理操作。在win32上，命令行的ctrl+c也可被捕获，但当程序作为服务在后台运行时，相关停止、重启操作暂未内捕获）
• 全局变量和资源（打包了Version、License、Name、Report等变量）
• 服务模式（可使用控制单元启动多服务，或直接启动单服务）

入口

入口文件在src/cmd下，目前分别有两个程序：lionv1和tigerv1。

• lionv1 是使用控制单元的多服务演示程序。
• tigerv1 是直接运行服务的单服务演示程序。

入口程序不直接包含太多的实际代码，真正的main函数位于src\mainfunc下。 程序的返回值代表程序的Exit Code。 一般采用0表示正确结束。

编译

生成

每次编译器请先运行go generate命令，生成编译所需要的文件。

编译所需要的文件：

• build_data.txt 构建日期（Unix 时间戳，单位：秒）
• commit_data.txt 构建的git（若有）的commit所对应的hash值（完整）。
• tag_data.txt 构建时最新的git（若有）的标签名（若有），用于作为语义化版本。可以以v或V开头，后接语义化版本号。若非语义化版本号，则标签数据会忽略（相当于无标签）。
• tag_commit_data.txt 上述（tag_data.txt）对标签（若有）所指的commit的hash值（完整）。若该值与commit_data.txt不同，则版本号会加上+dev标识。
• random_data.txt 一串随机数（40个字符，和commit的hash长度相同，由数字和小写字母组成）。

在项目根目录下执行：

$ go generate ./...

其中，./...表示执行当前目录下的所有（含本目录和递归的子目录）go:generate命令。

编译

使用go build指令进行编译。如何包位于github.com/SongZihuan/BackendServerTemplate/src/cmd/下，例如github.com/SongZihuan/BackendServerTemplate/src/cmd/lionv1

所以，编译命令如下（以lionv1为例）：

$ go build github.com/SongZihuan/BackendServerTemplate/src/cmd/lionv1

若用于开发环境，可以按如下方式编译：

$ go build -o lionv1 -trimpath -ldflags='-s -w -extldflags "-static"' -gcflags='-O4 -inline=1' github.com/SongZihuan/BackendServerTemplate/src/cmd/lionv1

其中：

• -o lionv1 表示输出二进制文件的路径和名称
  • Windows： -o lionv1.exe
  • Linux/MacOS：-o lionv1
• -trimpath 表示擦除二进制文件中关于源码目录的信息，可以压缩二进制文件体积和包含隐私。
• -ldflags='-s -w' 是传递给链接器的参数。
  • -s 表示去掉符号和调试信息，可以减少二进制文件大小，同时增加反编译的难度。
  • -w 表示去掉DWARF调试信息，可以减少二进制文件大小，同时增加反编译的难度。
  • -extldflags "-static" 是传递给外部链接器的参数。
    • -static 表示外部链接器生成静态链接文件（实际上我几乎从真正看过这个参数的作用，因为go本身就会优先以静态形式链接库文件，这个参数可能和cgo搭配更合适）。
• -gcflags='-O4 -inline=1' 是传递给编译器的参数。
  • -O4 启用最大优化。
  • -inline=1 内联的积极程度。支持-1、0、1、2、3。数值越大约积极，-1为禁止内联，0为默认模式。内联越积极，可以提高一定性能，但可能让二进制文件膨胀变大。

运行

执行编译好地可执行文件即可。 注意编译时选择的目标平台要与运行平台一致。

运行参数

• -h、--help 输出帮助文档（Usage）。（终止运行参数）。
• -v、--version 输出版本号。（终止运行参数）。
• -l、--license 输出软件协议。（终止运行参数）。
• -r、--report 输出程序反馈、报告方式文档。（终止运行参数）。
• -n、--name 设置项目名称（需要一个字符串参数）
• -c、--config 配置文件位置（可提供一个字符串参数作为路径指向配置文件，默认值为：config.yaml）。
• -o、--output-config 反向输出配置文件（默认不输出，若提供一个路径则会输出到该路径所指处）。未知配置项不会输出，未设定配置项则以默认值（若有）输出。前提：配置文件被正确导入和识别。

终止运行参数：当命令行出现这些参数时，将只执行参数对应的功能，执行完成后不会继续运行后续服务。

配置文件

# 等同于命令行参数的 --name ，但优先级高于命令行参数。
name: Backend-Server-Template

# 运行模式：debug、release、test。默认为debug。
mode: debug

# 时间地区，例如：UTC、Local（默认）、Asia/Shanghai
time-zone: local

# utc-date 和 timestamp 并非真实参数，而是启用 --output-config时反向输出的参数、表示配置文件的读取时间。
utc-date: "2025-04-15 15:33:37"
timestamp: 1744731217

# 日志记录器的配置
logger:
    log-level: debug  # 日志记录等级：debug（输出debug和以上的） < info （输出info和以上的）< warn < error < panic < none（什么都不输出）
    log-tag: enable  # 是否输出tag调试日志。
    
    warn-writer:  # debug、tag、info、warn日志的输出器
        write-to-std: stdout  # 输出到标准输出或标准错误输出（为空则不启用）
        write-to-file: ""  # 输出到固定文件（append）模式
        write-to-dir-with-date: ""  # 输出到指定目录，并按日期分割，此处为输出路径
        write-with-date-prefix: ""  # 配合 write-to-dir-with-date ，表示文件的输出前缀
        
    error-writer:  # error、panic日志的输出器，含义同上
        write-to-std: stdout
        write-to-file: ""
        write-to-dir-with-date: ""
        write-with-date-prefix: ""

signal: # 信号除了机制（管理接收程序退出信号）。sigkill 等信号是不可捕获的，是强制退出的，因此此处无法控制这类信号。虽然windows本身不具有Linux这种信号机制，但是Go在信号方面做了一层模拟，使得控制它ctrl+c可以转换为相应信号。
    sigint-exit: enable  # 收到 sigint 信号后退出
    sigterm-exit: enable  # 收到 sigterm 信号后退出
    sighup-exit: enable  # 收到 sighup 信号后退出
    sigquit-exit: enable  # 收到 sigquit 信号后退出

server:  # 系统执行服务所需要的参数
    stop-wait-time: 10s  # 服务退出时，等待清理结束的最长时间。

一些值的设定

• Name 系统名称：
  • 第一优先级：配置文件中的设定
  • 第二优先级：命令行参数
  • 最后优先级：项目根目录下Name文件（仅第一行有效、不包含换行符）
• SemanticVersioning 语义化版本号：
  • 第一优先级：项目根目录下的Version文件，可以v或V开头，后接语义化版本号，否则视为不满足要求进入第二优先级。
  • 第二优先级：读取git中最新的tag，可以v或V开头，后接语义化版本号，否则视为不满足要求进入第二优先级。 若最新的tag对应的提交不是当前的提交（且无dev标识），则添加+dev-时间戳-当前版本提交的哈希值到语义化版本号中。
  • 第三优先级：若无tag，但有当前提交记录的哈希值，则版本号为0.0.0+dev-时间戳-当前版本提交的哈希值。
  • 最后优先级：使用随机版本号，版本号为0.0.0+dev-时间戳-随机值，随机值在执行go generate时生成（位于文件random_data.txt中），go build后固定。
• Version 版本号：SemanticVersioning前添加v的字符串。

日后升级计划

1. Windows的Console机制的利用。
2. 单元测试
3. GitHub Action

协议

本软件基于 MIT LICENSE 发布。 了解更多关于 MIT LICENSE，请 点击此处 。