cosgo

cosgo

⚠️ 本项目由 AI 接管维护,不建议碳基生物阅读代码。

若必须阅读,请做好心理准备: 注释可能比代码还长,this 命名约定,少数位置存在"明知不标准但刻意保留"的历史选择。 同时也请理解: 代码风格一致性 > 追新,机器审美下一些 Go 1.22+ 特性(range over int、slices.Contains 等)未被引入是刻意的。

cosgo 是一个 Go 应用脚手架 + 通用工具底座。它负责:

• 应用生命周期:模块化启动/关闭、信号处理、配置、PID 文件、pprof、热重载
• 运行时底座:路由注册、数据序列化、会话、存储、反射元数据、并发控制
• 工具集:随机数、UUID、时间、切片、字节操作、加密、zset 排行榜

子模块索引

根包文件

cosgo.go    模块注册/启动入口
config.go   基于 viper 的配置层
events.go   启停事件广播(Begin/Loaded/Started/Closing/Stopped/Reload)
signal.go   SIGINT/SIGHUP/SIGQUIT/SIGTERM/SIGUSR1 处理
module.go   Module 接口定义
init.go     应用初始化骨架
options.go  全局选项表
pidfile.go  原子写入的 PID 文件
pprof.go    独立 mux 的 pprof 服务器(避免污染 DefaultServeMux)
reload.go   SIGUSR1 触发的配置热重载

快速开始

package main

import (
    "github.com/hwcer/cosgo"
    "github.com/hwcer/logger"
)

type MyModule struct{}

func (m *MyModule) Id() string      { return "mymodule" }
func (m *MyModule) Init() error     { logger.Info("init");  return nil }
func (m *MyModule) Start() error    { logger.Info("start"); return nil }
func (m *MyModule) Close() error    { logger.Info("close"); return nil }

func main() {
    cosgo.Use(&MyModule{})
    cosgo.Start(true) // true = 阻塞等信号
}

Module 接口

type Module interface {
    Id() string
    Init() error     // 应用启动,顺序调用
    Start() error    // 所有 Init 完成后,顺序调用
    Close() error    // 收到退出信号,逆序调用
}

生命周期事件

cosgo.On(cosgo.EventTypStarted, func() error {
    logger.Info("app ready")
    return nil
})

事件列表:

• EventTypBegin — 启动入口
• EventTypLoaded — 所有 Init 完成
• EventTypStarted — 所有 Start 完成(服务就绪)
• EventTypClosing — 收到退出信号
• EventTypStopped — 所有 Close 完成
• EventTypReload — SIGUSR1 触发热重载

配置

cosgo.Config.SetDefault("server.port", 8080)
port := cosgo.Config.GetInt("server.port")

优先级(高→低):运行时 Set > CLI flags > 环境变量 > 配置文件 > 默认值。

日志级别:未显式设置时,debug=true → LevelDebug(最详细),debug=false → LevelInfo(生产降噪)。

pprof

只在 config.pprof 配置了地址时才启动,并且走独立 mux(不污染 http.DefaultServeMux),防止业务服务意外暴露 /debug/pprof。

pprof: "127.0.0.1:6060"  # 通常仅监听本地

信号

SIGKILL 无法捕获(OS 直接杀进程),程序不感知。

信号处理顺序(优雅关闭)

收到 SIGINT/SIGTERM
  → 发 EventTypClosing
  → 逆序调用各 Module.Close()
  → scc.Cancel() 取消所有注册的协程
  → 等待 goroutine 清理完毕
  → 发 EventTypStopped
  → 进程退出

贡献

欢迎 Issue 和 PR。代码风格遵循仓库已有约定(this receiver、特定 godoc 风格),请不要为了迎合现代 Go linter 而大改。

许可证

MIT