hwf

HWF: 轻量 Go Web 框架

项目介绍

HWF (Hello Web Framework) 是一个轻量级的 Go Web 框架，旨在提供简洁、易用且功能完善的 Web 开发体验。框架遵循模块化设计理念，支持项目与模块生命周期管理、INI 配置、路由绑定与校验、定时任务、钩子机制、统一上下文、日志按天滚动等核心功能。

核心思想

• 模块化设计：将应用拆分为多个独立模块，每个模块拥有自己的生命周期、路由、模型和定时任务
• 自动数据库表创建：基于 GORM 模型自动创建和迁移数据库表，简化数据库操作
• 统一上下文：提供统一的 Context 对象，方便在请求处理过程中访问日志、ORM 事务等资源
• 灵活配置：支持 INI 格式配置文件，可通过命令行参数指定配置文件
• 丰富的中间件支持：提供路由级中间件，支持统一处理请求日志、鉴权等功能

快速使用

安装 CLI 工具

 go install gitee.com/hwfo/hwf/cmd/hwf@latest

创建新项目

hwf new myapp
cd myapp

创建模块

# 在项目根目录下执行
hwf module user

运行项目

# 使用默认配置文件 (config.ini)
go run main.go

# 使用指定配置文件
go run main.go config.prod.ini

最小项目示例

package main

import (
    "github.com/hwf"
)

type MyApp struct{}

func (a *MyApp) Name() string { return "myapp" }
func (a *MyApp) Install(ctx *hwf.HwfCtx) error { return nil }
func (a *MyApp) Init(ctx *hwf.HwfCtx) error { return nil }
func (a *MyApp) Modules() []hwf.Module { return []hwf.Module{} }
func (a *MyApp) Config() any { return nil }

func main() {
    app := &MyApp{}
	err := hwf.Run(app)
	if err != nil {
		log.Fatalln(err.Error())
	}
}

项目结构

HWF 推荐的项目目录结构如下：

├── config.ini              # 主配置文件
├── main.go                 # 应用入口
├── internal/               # 模块代码根目录
│   └── <module1>/           # 模块目录
│   └── <module2>/           # 模块目录
├── resource/               # 嵌入式资源目录 (go:embed)
├── static/                 # 静态资源目录
├── runtime/                # 运行时目录
├── logs/                   # 日志目录
├── manifest/               # 部署相关文件
├── pkg/                    # 项目内通用工具包
└── go.mod                  # Go 模块文件

应用接口实现

应用需要实现 hwf.App 接口：

type App interface {
    // Name 返回项目名称
    Name() string
    // Install 首次运行时执行 (当 runtime/install.lock 不存在时)
    Install(ctx *HwfCtx) error
    // Init 每次运行时执行
    Init(ctx *HwfCtx) error
    // Route 注册路由
    Route(r Router)
    // Modules 返回需要注册的模块列表
    Modules() []Module
    // Config 返回项目配置结构体指针,可读取ini配置文件中[app]部分的配置
    Config() any
}

可选接口

• AppTLSConfiger: 提供 TLS 配置
• AppJSONFormatter: 自定义 JSON 输出格式
• AppPackResourcer: 提供嵌入式资源文件系统
• ConfigFiler: 提供配置文件路径

模块接口

模块是框架的基本功能单元，每个模块需要实现 hwf.Module 接口：

type Module interface {
    // Name 返回模块名称
    Name() string
    // Install 首次运行时执行
    Install(ctx *HwfCtx) error
    // Init 每次运行时执行
    Init(ctx *HwfCtx) error
    // Models 返回 GORM 模型结构体，用于自动创建数据库表
    Models() []any
    // Route 注册模块路由
    Route(r Router)
    // Cron 注册定时任务
    Cron(c CronJob)
    // Triggers 声明模块可能触发的钩子名称
    Triggers(h Hooks)
    // Config 返回模块配置结构体指针，可读取配置文件中[module.模块Name()]部分的配置数据
    Config() any
}

模块目录结构

internal/<module>/
├── init.go              # 模块入口，实现 Module 接口
├── define/              # 常量与配置类型
├── model/               # 持久化模型 (GORM)
├── dto/                 # 领域对象与 DTO
├── api/                 # 接口契约与协定
├── control/             # 路由与控制器
├── service/             # 业务服务
├── cron/                # 定时任务实现
└── pkg/                 # 模块内通用工具

配置文件

HWF 使用 INI 格式的配置文件，支持多节配置和内联注释。

配置文件位置

• 默认配置文件：config.ini
• 可通过命令行参数指定：go run main.go custom.ini
• 可通过 ConfigFiler 接口自定义配置文件路径

核心配置节

[logging]
retention_days = 7          # 日志保留天数
log_level = info            # 日志级别: debug|info|warn|error|off
request_log_enabled = true  # 是否记录请求日志
console_enable = true       # 是否输出日志到控制台

[web]
addr = :8080                # 监听地址
read_timeout = 10           # 读取超时时间 (秒)
write_timeout = 10          # 写入超时时间 (秒)
idle_timeout = 60           # 空闲超时时间 (秒)
static_dir = static         # 静态文件目录
static_prefix = /static     # 静态文件前缀

[paths]
logs_dir = logs             # 日志目录
runtime_dir = runtime       # 运行时目录

[database]
driver = sqlite             # 数据库驱动: sqlite|mysql|postgres
dsn = file:app.db?_pragma=busy_timeout(5000)  # 数据源名称
max_open = 25               # 最大打开连接数
max_idle = 25               # 最大空闲连接数
log_sql = false             # 是否记录 SQL 语句

模块配置

模块配置使用 [module.<模块名>] ,可在Module接口的Config中读取

[module.user]
enable_email_verify = true
password_min_length = 8

路由注册

基本路由

func (m *UserModule) Route(r hwf.Router) {
    // 基本路由
    r.GET("/users", m.ListUsers)
    r.POST("/users", m.CreateUser)
    r.GET("/users/:id", m.GetUser)
    r.PUT("/users/:id", m.UpdateUser)
    r.DELETE("/users/:id", m.DeleteUser)
  
    // 匹配所有 HTTP 方法
    r.Any("/health", m.HealthCheck)
}

路由组

func (m *UserModule) Route(r hwf.Router) {
    // 创建路由组
    api := r.Group("/api/v1")
  
    // 路由组中间件
    api.Use(m.AuthMiddleware)
  
    // 组内路由
    api.GET("/users", m.ListUsers)
    api.POST("/users", m.CreateUser)
}

静态文件

// 在模块路由中注册
func (m *StaticModule) Route(r hwf.Router) {
    r.Static("/static", "static")
    r.File("/favicon.ico", "static/favicon.ico")
}

// 或通过配置文件自动注册 (推荐)
// [web]
// static_dir = static
// static_prefix = /static

Context 使用

func (m *UserModule) GetUser(c *hwf.ReqCtx) {
    // 获取用户 ID
    id := c.Query("id")
  
    // 访问框架上下文
    ctx := c.Context()
  
    // 记录日志
    ctx.Log().Infof("获取用户信息: %s", id)
  
    // 数据库事务
    err := ctx.Transaction(func(tx *hwf.ORM) error {
        // 数据库操作...
        return nil
    })
  
    // 返回 JSON 响应
    c.JSON(200, map[string]interface{}{
        "id":   id,
        "name": "张三",
    })
}

数据绑定

基本绑定

func (m *UserModule) CreateUser(c *hwf.ReqCtx) {
    var user dto.User
  
    // 绑定 JSON 请求体
    if err := c.BindJSON(&user); err != nil {
        c.JSON(400, map[string]string{"error": err.Error()})
        return
    }
  
    // 绑定 URL 查询参数
    // if err := c.BindQuery(&user); err != nil {
    //     c.JSON(400, map[string]string{"error": err.Error()})
    //     return
    // }
  
    // 绑定表单数据
    // if err := c.BindForm(&user); err != nil {
    //     c.JSON(400, map[string]string{"error": err.Error()})
    //     return
    // }
  
    // 绑定请求头
    // if err := c.BindHeader(&user); err != nil {
    //     c.JSON(400, map[string]string{"error": err.Error()})
    //     return
    // }
  
    // 处理业务逻辑...
    c.JSON(200, map[string]string{"message": "用户创建成功"})
}

数据校验

package entity

type User struct {
    Username string `json:"username" validate:"required;min=3;max=20" msg:"required=用户名必填;min=用户名长度不能小于3个字符;max=用户名长度不能大于20个字符"`
    Email    string `json:"email" validate:"required;email" msg:"required=邮箱必填;email=邮箱格式不正确"`
    Password string `json:"password" validate:"required;password=strong" msg:"required=密码必填;password=密码强度不足，需至少10位并包含大小写字母、数字和特殊字符"`
    Age      int    `json:"age" validate:"ge=18;le=100" msg:"ge=必须年满18岁;le=年龄不能超过100岁"`
}

校验规则

自定义错误消息

type User struct {
    Username string `json:"username" validate:"required;min=3" msg:"required=用户名不能为空;min=用户名至少需要3个字符"`
}

钩子

注册钩子

func (m *UserModule)Triggers(h hwf.Hooks) {
    // 注册用户创建后的钩子
    h.On("user.created", func(ctx *hwf.Context, payload any) error {
        user := payload.(*entity.User)
        ctx.Log().Infof("用户创建成功，发送欢迎邮件: %s", user.Email)
        // 发送欢迎邮件逻辑...
        return nil
    })
}

触发钩子

func (m *UserService) CreateUser(user *entity.User) error {
    // 保存用户到数据库
    if err := m.DB.Create(user).Error; err != nil {
        return err
    }
  
    // 触发用户创建钩子
    ctx := hwf.NewContext()
    return hwf.GetHooks().Put("user.created", ctx, user)
}

定时任务

注册定时任务

func (m *UserModule) Cron(c hwf.CronJob) {
    // 每 5 秒执行一次
    c.Add("*/5 * * * * *", func(ctx *hwf.Context) {
        ctx.Log().Println("每 5 秒执行一次的任务")
    })
  
    // 每小时执行一次
    c.Add("0 0 * * * *", func(ctx *hwf.Context) {
        ctx.Log().Println("每小时执行一次的任务")
    })
  
    // 每天凌晨 2 点执行
    c.Add("0 0 2 * * *", func(ctx *hwf.Context) {
        ctx.Log().Println("每天凌晨 2 点执行的任务")
        // 执行数据备份...
    })
}

Cron 表达式格式

HWF 支持 6 段 Cron 表达式（含秒）：

秒 分 时 日 月 星期

日志

基本日志

// 在请求处理中
func (m *UserModule) GetUser(c *hwf.ReqCtx) {
    ctx := c.Context()
    ctx.Log().Debugf("调试信息: %s", c.R.URL.Path)
    ctx.Log().Infof("普通信息: %s", c.R.URL.Path)
    ctx.Log().Warnf("警告信息: %s", c.R.URL.Path)
    ctx.Log().Errorf("错误信息: %s", c.R.URL.Path)
}

// 在服务层
func (s *UserService) GetUser(id string) (*entity.User, error) {
    ctx := hwf.NewContext()
    ctx.Log().Infof("查询用户: %s", id)
    // ...
}

请求日志

启用请求日志记录：

[logging]
request_log_enabled = true

请求日志格式：

2023-10-01 12:00:00 [INFO] [GET] /api/v1/users 127.0.0.1 200 15ms

日志配置

[logging]
retention_days = 7         # 日志保留天数
log_level = info           # 日志级别: debug|info|warn|error|off
request_log_enabled = true # 是否记录请求日志
console_enable = true    # 是否输出到控制台

[paths]
logs_dir = logs            # 日志目录

日志文件

日志文件按天生成，格式为 YYYY-MM-DD.log，存储在 logs 目录下（可通过配置修改）。

数据库操作

模型定义

package model

import (
    "github.com/hwf"
    "gorm.io/gorm"
)

type User struct {
    gorm.Model
    Username string `gorm:"unique;size:20" json:"username"`
    Email    string `gorm:"unique;size:100" json:"email"`
    Password string `gorm:"size:100" json:"-"`
}

func (u *User) TableName() string { return "users" }

自动迁移

框架会在首次启动时自动迁移所有模块的模型：

func (m *UserModule) Models() []any {
    return []any{&model.User{}}
}

事务处理

func (s *UserService) CreateOrder(c *hwf.ReqCtx, order *model.Order) error {
    return c.Context().Transaction(func(tx *hwf.ORM) error {
        // 创建订单
        if err := tx.Create(order).Error; err != nil {
            return err
        }
  
        // 更新库存
        if err := tx.Model(&model.Product{}).Where("id = ?", order.ProductID).Update("stock", gorm.Expr("stock - ?", order.Quantity)).Error; err != nil {
            return err
        }
  
        return nil
    })
}

中间件

自定义中间件

func (m *AuthModule) AuthMiddleware(c *hwf.ReqCtx) {
    // 从请求头获取 token
    token := c.R.Header.Get("Authorization")
  
    // 验证 token
    if token == "" || !m.ValidateToken(token) {
        c.AbortWithStatusJSON(401, map[string]string{"error": "未授权"})
        return
    }
  
    // 继续执行后续中间件和处理函数
    c.Next()
}

注册中间件

func (m *AuthModule) Route(r hwf.Router) {
    // 全局中间件
    r.Use(m.LogMiddleware)
  
    // 路由组中间件
    api := r.Group("/api")
    api.Use(m.AuthMiddleware)
  
    // 特定路由中间件
    api.GET("/admin", m.AdminMiddleware, m.AdminHandler)
}

高级特性

JSON 格式统一

// 实现 AppJSONFormatter 接口
func (a *MyApp) JSONFormat(ctx *hwf.ReqCtx, v ...any) {
    var code int
    var data any
    var message string
  
    // 根据参数数量和类型统一格式化
    switch len(v) {
    case 1:
        data = v[0]
        code = 200
        message = "success"
    case 2:
        code = v[0].(int)
        data = v[1]
        message = "success"
    case 3:
        code = v[0].(int)
        data = v[1]
        message = v[2].(string)
    }
  
    // 统一响应格式
    ctx.JSON(code, map[string]any{
        "code":    code,
        "message": message,
        "data":    data,
        "time":    time.Now().Unix(),
    })
}

// 使用统一格式
func (m *UserModule) GetUser(c *hwf.ReqCtx) {
    user := &entity.User{ID: 1, Username: "张三"}
    c.JSONF(200, user, "获取用户成功")
    // 输出: {"code":200,"message":"获取用户成功","data":{"id":1,"username":"张三"},"time":1633046400}
}

反向代理

func (m *ProxyModule) Route(r hwf.Router) {
    // 注册反向代理
    r.Proxy("/api", "http://localhost:9000")
}

// 或在请求处理中动态代理
func (C *DynamicController) ProxyHandler(c *hwf.ReqCtx) {
    // 动态计算目标地址
    target := "http://localhost:9000"
  
    // 反向代理
    err := c.Proxy(target, func(p *httputil.ReverseProxy) {
        // 自定义代理配置
        p.ModifyResponse = func(resp *http.Response) error {
            resp.Header.Set("X-Proxy", "HWF")
            return nil
        }
    })
  
    if err != nil {
        c.AbortWithStatusJSON(500, map[string]string{"error": err.Error()})
    }
}

中间件

HWF 提供了丰富的中间件支持，帮助你快速实现常见功能：

工具包

HWF 提供了一系列实用工具包，可独立使用：

贡献

欢迎提交 Issue 和 Pull Request！

许可证

MIT License