gocanned

gocanned

Go Web 应用基础设施库，提供配置管理、日志、数据库、缓存、限流、数据库迁移、CLI 脚手架等通用组件。

安装

作为库引入

在消费方项目中添加 replace 指令指向本地路径：

cd your-project
go get github.com/CuratorC/gocanned

在 go.mod 中添加 replace 指令：

replace github.com/CuratorC/gocanned => ../gocanned

安装脚手架 CLI

# 从 gocanned 项目根目录执行
go install ./cmd/gocanned/

# 安装后可在任意目录使用
gocanned init myapp

安装后二进制位于 $GOPATH/bin/gocanned（通常为 ~/go/bin/gocanned），确保该路径在 PATH 中。

快速开始

创建项目

gocanned init myapp

# 如果需要覆盖已有文件
gocanned init myapp --force

启动项目

cd myapp
go mod tidy
go run main.go serve

项目默认监听 3000 端口，访问 http://localhost:3000/health-check 验证服务是否启动。

生成的项目结构

myapp/
├── main.go                              # 入口：Cobra 根命令
├── .env                                 # APP_ENV=local
├── go.mod                               # 含 replace gocanned 指令
├── bootstrap/                           # 初始化编排层
│   ├── bootstrap.go                     # SetupCommand / NewApp
│   ├── config.go                        # blank import 触发 config 和 migrations
│   ├── logger.go                        # logger.SetupLogger
│   ├── cache.go                         # cache.SetupRedis
│   ├── database.go                      # database.Connect
│   └── route.go                         # 全局中间件 + 路由注册 + 404
├── config/                              # 配置注册文件
│   ├── app.go                           # config.Add("app", ...)
│   ├── log.go                           # config.Add("log", ...)
│   ├── database.go                      # config.Add("database", ...)
│   └── redis.go                         # config.Add("redis", ...)
├── cmd/
│   └── serve.go                         # serve 子命令（优雅关停 + pprof）
├── internal/
│   ├── app/app.go                       # App 依赖注入结构体
│   ├── enum/database.go                 # DatabaseName 枚举
│   ├── http/middleware/                  # Gin 中间件
│   │   ├── logger.go                    # 请求日志
│   │   ├── recovery.go                  # Panic 恢复
│   │   └── limit.go                     # IP/路由 限流
│   ├── http/response/response.go        # 统一响应处理
│   ├── database/migrations/main/        # 数据库迁移文件
│   └── route/api.go                     # API 路由注册

配置管理

所有配置通过 .env 文件管理，配置键定义在 config/ 目录的 init() 函数中：

# .env
APP_ENV=local

配置值通过 config.Env("ENV_VAR", defaultValue) 绑定环境变量，通过点分路径读取：

config.GetString("app.port")         // "3000"
config.GetString("database.main.host") // "127.0.0.1"
config.GetInt("database.main.port")    // 3306

使用 --env 标志加载不同环境配置：

go run main.go serve --env=testing    # 加载 .env.testing

生成配置文件

go run main.go init                        # 生成全部预设模块
go run main.go init app redis              # 只生成指定模块
go run main.go init --force app            # 强制覆盖

数据库迁移

# 生成迁移文件
go run main.go migrate:make create_users --database=main

# 执行迁移
go run main.go migrate
go run main.go migrate --database=main

# 回滚最后一批
go run main.go migrate:rollback

# 查看状态
go run main.go migrate:status

迁移文件存放在 internal/database/migrations/{数据源}/ 下：

// internal/database/migrations/main/20260413_150000_create_users.go
package migrations

import "github.com/CuratorC/gocanned/migration"

func init() {
    migration.Register("main", &CreateUsers{})
}

type CreateUsers struct{}

func (m *CreateUsers) Up() string {
    return `
        CREATE TABLE users (
            id INTEGER PRIMARY KEY AUTOINCREMENT,
            name TEXT NOT NULL DEFAULT '',
            email TEXT NOT NULL DEFAULT '',
            created_at DATETIME,
            updated_at DATETIME
        )
    `
}

func (m *CreateUsers) Down() string {
    return `DROP TABLE IF EXISTS users`
}

子命令

依赖注入

生成的项目使用 internal/app.App 结构体实现依赖注入：

// bootstrap/bootstrap.go
func NewApp() (*app.App, error) {
    application := &app.App{}
    db, err := SetupDatabase(enum.DatabaseNameMain)
    application.DB = db
    return application, nil
}

// cmd/serve.go
application, err := bootstrap.NewApp()
bootstrap.SetupRoute(router, application)  // 将 app 传入路由层

全局标志

打包发布

# 编译脚手架工具
go build -o gocanned ./cmd/gocanned/

# 编译库（验证无编译错误）
go build ./...

# 运行测试
go test ./...