framework

Leeforge Framework

Leeforge Framework 是 Leeforge 后端服务的通用技术内核，提供认证授权、HTTP 工具、日志、缓存、插件系统等基础设施能力。

模块路径

module github.com/leeforge/framework

安装

# 使用发布版本（推荐）
go get github.com/leeforge/[email protected]

Monorepo 本地联调，在 server/backend/go.mod 中添加：

require github.com/leeforge/framework v0.0.0

replace github.com/leeforge/framework => ../framework

模块速览

快速开始

1. 初始化日志

import "github.com/leeforge/framework/logging"

logger := logging.NewLogger(logging.DefaultConfig())

2. 加载配置

import "github.com/leeforge/framework/config"

cfg, err := config.NewConfig()
var appCfg AppConfig
cfg.BindWithDefaults(&appCfg)

3. 初始化鉴权（Casbin）

import frameAuth "github.com/leeforge/framework/auth"

core, err := frameAuth.Setup(ctx, frameAuth.Config{
    DatabaseURL: appCfg.Database.DSN,
    AutoMigrate: true,
    EnableCache: true,
})

4. 实现并注册插件

import "github.com/leeforge/framework/plugin"

type UserPlugin struct{}

func (p *UserPlugin) Name() string { return "users" }
func (p *UserPlugin) Dependencies() []string { return []string{"auth"} }

func (p *UserPlugin) Setup(ctx context.Context, app plugin.AppContext) error {
    app.Router().Route("/users", func(r chi.Router) {
        permission.Get(r, "/", listHandler, permission.Private("列表", "users:read"))
    })
    return nil
}

5. 启动运行时

import "github.com/leeforge/framework/runtime"

rt := runtime.New(appCtx)
rt.Register(&AuthPlugin{})
rt.Register(&UserPlugin{})

rt.Bootstrap(ctx)
rt.Wait()
rt.Shutdown(ctx)

响应格式契约

所有 API 响应统一使用以下结构（通过 http/responder 输出）：

{
  "data": {},
  "error": null,
  "meta": { "traceId": "req-abc", "took": 12 }
}

架构规则

• 权限决策必须通过 Casbin/RBAC 管理器，禁止在 handler 中硬编码权限逻辑
• API 响应统一使用 http/responder，禁止直接 json.Marshal
• 业务编排留在上层插件，不进入 framework 核心层
• UUID 主键统一使用 entities.NewUUID()（UUID v7），禁止使用其他 UUID 库
• 错误处理使用 fmt.Errorf("context: %w", err) 包装，保留错误链