jframe CLAUDE.md

CLAUDE.md — jframe 项目 Agent 开发指南

项目概述

jframe 是一个基于模块化内核的 Go 应用脚手架框架。所有功能以 kernel.Module 为单位组织，通过依赖注入容器 (inject/v2) 在模块间传递依赖，实现零耦合。

仓库: github.com/juanjiTech/jframe Go 版本: 1.23+ 入口: main.go → cmd.Execute() → Cobra 子命令

核心架构

模块系统

所有功能都封装为 kernel.Module（定义在 core/kernel/module.go）。

Module 接口:

Name() string                           — 唯一标识符，同时作为配置 YAML key
Config() any                            — 返回配置结构体指针，nil 表示无配置
PreInit(*Hub) / Init(*Hub) / PostInit(*Hub) / Load(*Hub) — 4 个顺序初始化阶段
Start(*Hub)                             — 在独立 goroutine 中运行（长驻任务）
Stop(*sync.WaitGroup, context.Context)  — 优雅关闭（并发执行，必须 defer wg.Done()）

生命周期执行顺序:

1. Config 反序列化（遍历所有模块）
2. PreInit（遍历所有模块）— 创建资源，Map 到 DI 容器
3. Init（遍历所有模块）— 校验依赖
4. PostInit（遍历所有模块）— 跨模块装配
5. Load（遍历所有模块）— 注册路由、启用插件
6. Start（每个模块一个 goroutine）— 长驻服务

所有模块必须嵌入 kernel.UnimplementedModule，这是 gRPC 风格的前向兼容模式（mustEmbedUnimplementedModule() 未导出方法强制嵌入）。

依赖注入 (DI)

基于 github.com/juanjiTech/inject/v2，一个反射驱动的类型映射容器。

Hub 结构体（core/kernel/module.go:10）包装了 inject.Injector + *zap.SugaredLogger，传入每个生命周期方法。

核心 DI 操作:

• hub.Map(&value) — 注册依赖（按指针类型作为 key），一个类型只能存一个值
• hub.Load(&variable) — 获取依赖（必须检查 error）
• hub.Invoke(func(dep Type) { ... }) — 函数参数自动注入
• hub.Value(reflect.Type) — 底层按类型直接查找

重要规则:

• Map 总是传指针：hub.Map(&db) 不是 hub.Map(db)
• Load 只能获取已被其他模块 Map 过的类型
• 同类型只能存一个值，需要多个相同类型用包装结构体区分
• 内核在所有模块之前 Map 了 *net.Listener 和 cmux.CMux

配置系统

全局配置: conf/vars.go 的 GlobalConfig 结构体，通过 conf.Get() 获取。

模块配置: 每个模块的 Config() 返回自定义结构体指针。内核使用 reflect.StructOf 动态构建包含 mapstructure tag 的结构体，由 Viper 按 Name() 自动映射：

// 内核内部操作 (kernel.go:69-85)
structType := reflect.StructOf([]reflect.StructField{{
    Name: "Config",
    Type: reflect.TypeOf(moduleConfig),
    Tag:  reflect.StructTag(`mapstructure:"moduleName"`),
}})
instance := reflect.New(structType)
instance.Elem().Field(0).Set(reflect.ValueOf(moduleConfig))
viper.Unmarshal(instance.Interface())