kindness

Kindness Framework

🎉 一个基于 Laravel 思想、使用 Go 1.24 泛型构建的现代化 Web 框架

📑 目录

• 特性
• 安装
• 快速开始
• 核心功能
  • 1. IoC 容器
  • 2. 路由系统
  • 3. Eloquent 风格 ORM
  • 4. 数据验证
  • 5. 配置管理
  • 6. 日志系统
  • 7. 中间件
  • 8. 模板引擎
  • 9. Artisan 命令
  • 10. Support 组件
  • 11. 缓存系统
• 12. 队列与任务
• 13. 事件系统
• 14. 任务调度
• 15. WebSocket
• 16. 认证与权限
• 17. Kitex RPC
• 18. 微服务
• 19. GraphQL
• 20. 分布式追踪
• 项目结构
• 完整示例
• 依赖包
• 贡献
• 许可证
• 特别说明

✨ 特性

• 🔧 IoC 容器 - 类型安全的依赖注入，充分利用 Go 泛型
• 🎭 门面模式 - Laravel 风格的静态访问接口
• 🛣️ 优雅路由 - 基于 Gin 的 Laravel 风格路由系统
• 💾 Eloquent ORM - 基于 GORM 的链式查询构建器
• ✅ 数据验证 - Laravel 风格的验证规则
• 📝 日志系统 - 集成 Zap 的高性能结构化日志
• ⚙️ 配置管理 - 基于 Viper 的灵活配置系统
• 🎨 模板引擎 - 支持自定义函数的 HTML 模板
• ⚡ 中间件 - 可扩展的请求处理管道
• 🔨 Artisan CLI - 基于 Cobra 的命令行工具
• 📦 Support 组件 - Laravel 风格的 Collection、Str、Arr、Carbon 辅助函数
• 💾 缓存系统 - 多驱动支持（Memory、File），具备 Remember、Pull、Increment 等高级功能
• ⚡ 异步队列 - 支持延迟任务、重试机制
• 🔔 事件系统 - 基于观察者模式的事件分发
• ⏰ 任务调度 - 支持 Cron 表达式的定时任务
• 🔌 WebSocket - 实时双向通信支持
• 🛡️ 认证授权 - JWT、OAuth 2.0 及 RBAC 权限管理
• 🚀 Kitex RPC - 字节跳动高性能 RPC 框架集成
• 🌐 GraphQL - 现代化查询语言支持
• 📉 链路追踪 - 集成 OpenTelemetry 分布式追踪

📦 安装

go get github.com/kindness8023/kindness

🚀 快速开始

创建应用

package main

import (
    "github.com/kindness8023/kindness/foundation"
    "github.com/kindness8023/kindness/router"
    "github.com/kindness8023/kindness/middleware"
)

func main() {
    // 创建应用实例
    app := foundation.New(".")
    
    // 获取路由器
    r := app.Router()
    
    // 添加中间件
    r.Middleware(middleware.Logger(), middleware.Recovery())
    
    // 注册路由
    r.Get("/", func(c *router.Context) {
        c.Success(map[string]interface{}{
            "message": "Hello Kindness!",
        })
    })
    
    // 启动服务器
    app.Run(":8080")
}

📖 核心功能

1. IoC 容器（泛型支持）

import "github.com/kindness8023/kindness/container"

// 注册单例服务
container.Singleton[*MyService](app.Container(), func(c *container.Container) *MyService {
    return &MyService{}
})

// 解析服务（类型安全）
service, err := container.Make[*MyService](app.Container())

// 或使用门面
service := facade.MustMake[*MyService]()

2. 路由系统

r := app.Router()

// 基础路由
r.Get("/users", listUsers)
r.Post("/users", createUser)
r.Put("/users/:id", updateUser)
r.Delete("/users/:id", deleteUser)

// 路由分组
r.Group("/api", func(api *router.Router) {
    api.Middleware(middleware.Auth())
    
    api.Get("/profile", getProfile)
    api.Post("/logout", logout)
})

// 中间件
r.Get("/admin", adminHandler).Middleware(middleware.Auth())

3. Eloquent 风格 ORM（泛型）

Kindness 提供了基于 GORM 封装的泛型查询构建器，支持链式调用、类型安全和丰富的查询功能。

定义模型

继承 database.Model 以自动获得 ID, CreatedAt, UpdatedAt, DeletedAt 字段。

type User struct {
    database.Model
    Name  string `json:"name"`
    Email string `json:"email"`
    Age   int    `json:"age"`
}

数据库配置

支持 MySQL 和 SQLite。

import "github.com/kindness8023/kindness/database"

db := database.New()
err := db.AddConnection("default", database.Config{
    Driver:   "mysql",
    Host:     "127.0.0.1",
    Port:     3306,
    Database: "kindness",
    Username: "root",
    Password: "password",
    Charset:  "utf8mb4",
})

基础查询

// 创建构建器
builder := database.NewBuilder[User](facade.DB.Connection())

// 查找单个
user, err := builder.Find(1)
user, err := builder.Where("email", "alice@example.com").First()

// 获取所有
users, err := builder.Where("age", ">", 18).Get()

// 分页查询
pagination, err := builder.Paginate(1, 15)
// pagination.Data, pagination.Total, pagination.TotalPages

高级查询

builder.
    WhereIn("status", []int{1, 2, 3}).
    WhereBetween("age", 18, 30).
    WhereNull("confirmed_at").
    OrderBy("created_at", "DESC").
    Limit(10).
    Get()

事务处理

err := facade.Query[User]().Transaction(func(tx *database.Builder[User]) error {
    if err := tx.Create(&User{Name: "Bob"}); err != nil {
        return err // 自动回滚
    }
    return nil // 自动提交
})

分块处理 (Chunk)

用于处理大数据量，避免内存溢出。

facade.Query[User]().Chunk(100, func(users []User) error {
    for _, user := range users {
        // 处理用户...
    }
    return nil
})

软删除

默认使用软删除（如果模型包含 DeletedAt）。

// 软删除
facade.Query[User]().Where("id", 1).Delete()

// 永久删除
facade.Query[User]().Where("id", 1).ForceDelete()

4. 数据验证

import "github.com/kindness8023/kindness/validation"

// 创建验证器
validator := validation.Make(map[string]interface{}{
    "name": "Alice",
    "email": "alice@example.com",
    "age": 25,
}, map[string]string{
    "name": "required|min:3|max:50",
    "email": "required|email",
    "age": "required|numeric",
})

// 执行验证
if !validator.Validate() {
    errors := validator.Errors()
    // 处理错误
}

// 获取第一个错误
firstError := validator.First()

5. 配置管理

import "github.com/kindness8023/kindness/facade"

// 获取配置
appName := facade.Config.GetString("app.name")
debug := facade.Config.GetBool("app.debug")
port := facade.Config.GetInt("server.port")

// 获取环境变量
dbHost := facade.Config.Env("DB_HOST", "localhost")

// 设置配置
facade.Config.Set("custom.key", "value")

6. 日志系统

import (
    "github.com/kindness8023/kindness/facade"
    "github.com/kindness8023/kindness/log"
)

// 基础日志
facade.Log.Info("User logged in")
facade.Log.Error("Failed to connect database")

// 带字段的结构化日志
facade.Log.Info("User created", 
    log.String("name", "Alice"),
    log.Int("age", 25),
    log.String("email", "alice@example.com"),
)

// 错误日志
facade.Log.Error("Database error", log.Error(err))

// 创建带上下文的日志器
logger := facade.Log.With(
    log.String("request_id", "abc123"),
    log.String("user_id", "1"),
)
logger.Info("Processing request")

7. 中间件

import "github.com/kindness8023/kindness/middleware"

// 内置中间件
r.Middleware(
    middleware.Logger(),      // 请求日志
    middleware.Recovery(),    // 错误恢复
    middleware.CORS(),        // 跨域支持
    middleware.Auth(),        // 认证
    middleware.Throttle(60, time.Minute), // 限流
)

// 自定义中间件
func CustomMiddleware() router.HandlerFunc {
    return func(c *router.Context) {
        // 前置处理
        start := time.Now()
        
        c.Next()
        
        // 后置处理
        duration := time.Since(start)
        facade.Log.Info("Request completed", 
            log.String("duration", duration.String()),
        )
    }
}

8. 模板引擎

import "github.com/kindness8023/kindness/view"

// 创建引擎
engine := view.New("./resources/views")
engine.Load()

// 渲染模板
html, _ := engine.Render("welcome", map[string]interface{}{
    "title": "Welcome",
    "name": "Alice",
})

// 在路由中使用
r.Get("/welcome", func(c *router.Context) {
    engine, _ := router.Make[*view.Engine](c)
    html, _ := engine.Render("welcome", map[string]interface{}{
        "name": "Guest",
    })
    c.HTML(200, html, nil)
})

9. Artisan 命令

import "github.com/kindness8023/kindness/console"

// 创建命令
cmd := console.NewCommand("make:controller", "Create a controller", 
    func(cmd *cobra.Command, args []string) error {
        name := args[0]
        // 创建控制器逻辑
        return nil
    },
)

// 注册命令
app.Console().Register(cmd.Command)

// 运行控制台
app.RunConsole()

10. Support 组件

Collection - 集合操作:

import "github.com/kindness8023/kindness/support"

// 创建集合
numbers := support.Collect([]int{1, 2, 3, 4, 5})

// Filter - 过滤
evens := numbers.Filter(func(n int) bool {
    return n%2 == 0
})

// Map - 映射转换
squared := support.Map(numbers, func(n int) int {
    return n * n
})

// 统计
sum := support.SumInt(numbers)      // 求和
avg := support.AvgInt(numbers)      // 平均值
max, _ := support.MaxInt(numbers)   // 最大值

// 链式操作
result := numbers.Take(3).Reverse().All()

Str - 字符串辅助:

str := support.StringHelper

// 命名风格转换
str.Snake("HelloWorld")        // "hello_world"
str.Camel("hello_world")       // "helloWorld"
str.Studly("hello_world")      // "HelloWorld"
str.Kebab("HelloWorld")        // "hello-world"

// 字符串操作
str.Limit("长文本", 10, "...")   // 限制长度
str.Slug("Hello World!")       // "hello-world"
str.Before(url, "/path")       // 获取之前
str.After(url, "//")           // 获取之后

// 验证
str.IsEmail("test@example.com") // true
str.IsURL("https://example.com") // true

Arr - 数组辅助:

arr := support.ArrayHelper

// 嵌套数组操作（点号路径）
data := map[string]interface{}{
    "user": map[string]interface{}{
        "name": "Alice",
        "profile": map[string]interface{}{
            "age": 25,
        },
    },
}

arr.Get(data, "user.profile.age")           // 25
arr.Set(data, "user.profile.city", "Beijing")
arr.Has(data, "user.name")                  // true

// 数组操作
arr.Only(map, "name", "email")   // 只保留指定键
arr.Except(map, "password")      // 排除指定键
arr.Pluck(users, "name")         // 提取字段

// 集合操作
arr.Diff(arr1, arr2)      // 差集
arr.Intersect(arr1, arr2) // 交集
arr.Union(arr1, arr2)     // 并集

Helper - 辅助函数:

import "github.com/kindness8023/kindness/support"

// Optional 可选值
opt := support.NewOptional(value)
if opt.IsPresent() {
    fmt.Println(opt.Get())
}

// Tap - 执行回调但返回原值
result := support.Tap(value, func(v string) {
    fmt.Println(v)
})

// 环境变量
dbHost := support.Env("DB_HOST", "localhost")
debug := support.EnvBool("DEBUG", false)
port := support.EnvInt("PORT", 8080)

// 调试
support.Dump(data)    // 打印调试信息
support.DD(data)      // Dump and Die

// 检查
support.Blank("")     // true
support.Filled("hi")  // true

Carbon - 日期时间:

import "github.com/kindness8023/kindness/support"

// 创建时间
now := support.Now()                        // 当前时间
today := support.Today()                    // 今天零点
tomorrow := support.Tomorrow()              // 明天
yesterday := support.Yesterday()            // 昨天

// 创建指定时间
birthday := support.Create(1990, 5, 15, 10, 30, 0)
timestamp := support.CreateFromTimestamp(1640000000)

// 格式化
now.ToDateString()         // "2024-01-15"
now.ToTimeString()         // "15:04:05"
now.ToDateTimeString()     // "2024-01-15 15:04:05"
now.Format("2006年01月02日") // 自定义格式

// 时间计算
now.AddDays(7)             // +7天
now.SubMonths(3)           // -3个月
now.AddHours(5)            // +5小时

// 时间比较
now.IsToday()              // 是否为今天
now.IsFuture()             // 是否为未来
now.IsWeekend()            // 是否为周末
now.Between(start, end)    // 是否在范围内

// 时间范围
now.StartOfDay()           // 当天零点
now.EndOfMonth()           // 月末
now.StartOfWeek()          // 周一零点

// 人类可读
now.DiffForHumans()        // "5分钟前" / "2小时后"
now.DiffInDays(other)      // 相差天数

// Getter/Setter
now.GetYear()              // 获取年份
now.SetMonth(12)           // 设置月份

11. 缓存系统 (Cache)

多驱动支持:

import "github.com/kindness8023/kindness/cache"

// 内存缓存
memDriver := cache.NewMemoryDriver()
store := cache.NewStore(memDriver, "app")

// 文件缓存
fileDriver, _ := cache.NewFileDriver("./storage/cache")
fileStore := cache.NewStore(fileDriver, "file")

// 缓存管理器（多驱动）
manager := cache.NewManager()
manager.AddStore("default", store)
manager.AddStore("file", fileStore)

基础操作:

// Put/Get
store.Put("key", "value", 5*time.Minute)
if value, ok := store.Get("key"); ok {
    fmt.Println(value)
}

// Forever 永久存储
store.Forever("config", map[string]interface{}{
    "app": "Kindness",
})

// Has/Forget
if store.Has("key") {
    store.Forget("key")
}

// Flush 清空
store.Flush()

高级功能:

// Remember - 缓存穿透防护
data, _ := store.Remember("users", 5*time.Minute, func() interface{} {
    // 只在缓存不存在时执行
    return fetchUsersFromDB()
})

// Pull - 获取并删除
value, _ := store.Pull("temp")

// Add - 仅当不存在时添加
success := store.Add("key", "value", 5*time.Minute)

// Increment/Decrement
store.Put("counter", int64(10), 0)
store.Increment("counter", 5)  // 15
store.Decrement("counter", 3)  // 12

// 批量操作
store.PutMultiple(map[string]interface{}{
    "key1": "value1",
    "key2": "value2",
}, 5*time.Minute)
values := store.GetMultiple([]string{"key1", "key2"})

// 类型化获取
age, ok := store.GetInt("age")
price, ok := store.GetFloat("price")
active, ok := store.GetBool("active")

门面使用:

import "github.com/kindness8023/kindness/facade"

// 基础操作
facade.Cache.Put("key", "value", 5*time.Minute)
value, _ := facade.Cache.Get("key")

// 切换驱动
facade.Cache.Store("file").Put("key", "value", 10*time.Minute)

// Remember
data, _ := facade.Cache.Remember("key", 5*time.Minute, func() interface{} {
    return expensiveOperation()
})

12. 队列与任务 (Queue)

Kindness 提供了一个强大的异步队列系统，支持多种驱动、延迟任务和自动重试。

import (
    "github.com/kindness8023/kindness/facade"
    "github.com/kindness8023/kindness/queue"
)

// 定义任务处理器
handler := func(job *queue.Job) error {
    var data map[string]interface{}
    job.UnmarshalPayload(&data)
    fmt.Printf("Processing job: %v\n", data)
    return nil
}

// 推送任务到队列
facade.Queue.Push(queue.NewJob("default", map[string]string{
    "user_id": "123",
}))

// 延迟任务
facade.Queue.Later(queue.NewJob("default", "payload"), 10*time.Minute)

// 在 Worker 中消费
worker := queue.NewWorker(facade.Queue.Driver())
worker.Start("default")

13. 事件系统 (Event)

基于观察者模式的解耦利器。

import "github.com/kindness8023/kindness/facade"

// 监听事件
facade.Event.Listen("user.registered", func(event event.Event) {
    user := event.Data().(*User)
    fmt.Printf("Welcome %s!\n", user.Name)
})

// 触发事件
facade.Event.Dispatch(event.NewBaseEvent("user.registered", user))

14. 任务调度 (Schedule)

支持 Cron 格式的定时任务管理。

import "github.com/kindness8023/kindness/facade"

// 注册定时任务
facade.Schedule.EveryMinute("check_status", func() {
    // 执行逻辑
})

facade.Schedule.DailyAt("report", 23, 59, func() {
    // 生成日报
})

// 启动调度器
facade.Schedule.Start()

15. WebSocket

内置基于 Gorilla WebSocket 的实时通信支持。

import "github.com/kindness8023/kindness/websocket"

// 注册 WebSocket 路由
hub := websocket.NewHub()
go hub.Run()

r.Get("/ws", websocket.HandleWebSocket(hub))

// 广播消息
hub.Broadcast([]byte("Hello everyone!"))

16. 认证与权限 (Auth)

集成了 JWT、OAuth 2.0 和 RBAC 权限管理。

// JWT 认证
token, _ := facade.Auth.JWT().GenerateToken("user_123", "alice", "alice@example.com")

// RBAC 权限验证
if facade.Auth.RBAC().HasPermission("user_123", "post.delete") {
    // 允许操作
}

17. Kitex RPC

字节跳动高性能 RPC 框架集成，完全替代传统 gRPC。

import "github.com/kindness8023/kindness/rpc"

// 创建 Kitex 服务器
svr := rpc.NewServer(":8888")
svr.Run()

// 客户端调用
client, _ := rpc.NewClient("user-service")

18. 微服务 (Microservice)

提供服务注册发现、负载均衡和配置中心。

import "github.com/kindness8023/kindness/microservice"

// 服务注册
registry := microservice.NewMemoryRegistry()
registry.Register(&microservice.ServiceInstance{
    Name: "order-service",
    Address: "192.168.1.10",
    Port: 8081,
})

19. GraphQL

import "github.com/kindness8023/kindness/graphql"

// 定义 Schema 并运行
builder := graphql.NewBuilder()
builder.Query("hello", &graphql.Field{
    Type: "String",
    Resolve: func(ctx context.Context, args map[string]interface{}) (interface{}, error) {
        return "world", nil
    },
})

r.Post("/graphql", graphql.NewServer(builder.Build()).Handler())

20. 分布式追踪 (Tracing)

集成 OpenTelemetry 和 Jaeger。

import "github.com/kindness8023/kindness/tracing"

ctx, span := tracing.StartSpan(ctx, "GetUserInfo")
defer span.End()

// 后续逻辑...

🏗️ 项目结构

your-project/
├── main.go              # 应用入口
├── config.json          # 配置文件
├── routes/              # 路由定义
├── app/
│   ├── controllers/     # 控制器
│   ├── models/          # 模型
│   ├── middleware/      # 中间件
│   └── services/        # 服务
├── resources/
│   └── views/           # 模板文件
├── database/
│   └── migrations/      # 数据库迁移
└── storage/
    ├── logs/            # 日志文件
    └── cache/           # 缓存文件

🔥 完整示例

查看 examples/ 目录获取完整的示例代码：

• examples/webserver/main.go - Web 应用与路由示例
• examples/database/main.go - 数据库 ORM 操作全集示例
• examples/cache/main.go - 缓存系统使用示例
• examples/carbon/main.go - 时间处理示例
• examples/support/main.go - 集合与辅助函数示例

📚 依赖包

• github.com/gin-gonic/gin - HTTP 路由
• github.com/spf13/cobra - CLI 工具
• github.com/spf13/viper - 配置管理
• go.uber.org/zap - 高性能日志
• gorm.io/gorm - ORM 数据库