ego

README

Ego Framework

Ego 是一个基于 Go 语言的高性能、微内核、模块化应用程序框架。它以依赖注入 (DI) 为核心，提供了卓越的开发者体验 (DX) 和强大的扩展能力，旨在帮助开发者快速构建可维护、可测试的现代化应用。

✨ 特性

• 微内核架构: 核心仅包含 DI 容器和生命周期管理，极度轻量。
• 高性能 DI: 专为 Go 优化的依赖注入系统，支持构造函数注入、结构体指针注入、接口绑定、集合注入等。
• 模块化设计: 标准化的模块 (Module) 定义，支持功能即插即用。
• 配置管理: 支持静态配置映射和动态配置监听 (Monitor)，类型安全且支持热重载。
• 开发者体验:
  • 代码即文档: 内置 OpenAPI/Swagger 自动生成系统，无需编写额外 YAML。
  • 统一接口: 所有组件 (Web, gRPC, Cron, Redis, DB) 遵循统一的生命周期和配置模式。
• 全功能扩展: 内置 Web (Gin), gRPC, Cron, Redis, Database (GORM), MongoDB (Mgo) 等常用组件。

🚀 快速开始

安装

go get github.com/gocrud/ego

Hello World

创建一个简单的 Web 服务：

package main

import (
	"github.com/gocrud/ego"
	"github.com/gocrud/ego/ext/web"
)

func main() {
	app := ego.New(
		// 导入 Web 模块
		ego.Load(web.New().
			WithConfig(web.Config{Addr: ":8080"}).
			Module()),
		
		// 注册控制器
		ego.Provide(NewHelloController),
	)

	if err := app.Run(); err != nil {
		panic(err)
	}
}

type HelloController struct{}

func NewHelloController() *HelloController { return &HelloController{} }

func (c *HelloController) RegisterRoute(r *web.Router) {
	r.GET("/", func(ctx *web.Context) {
		ctx.JSON(200, map[string]string{"message": "Hello Ego"})
	})
}

📖 文档目录

• 依赖注入 (DI): 核心 DI 容器的使用详解，包括注册、注入、生命周期等。
• 配置系统 (Config): 静态配置与动态热重载配置的使用。
• 组件扩展 (Extensions):
  • Web 服务
  • gRPC 服务
  • Cron 任务
  • MongoDB
  • Redis & Database
• 文档系统 (OpenAPI): 代码优先的 API 文档生成与 Swagger UI 集成。
• 业务开发指南: 模块化开发最佳实践与自定义组件扩展。

🛠️ 示例

完整的示例代码可以在 example/ 目录下找到：

• example/simple: 基础 Web 服务
• example/modular: 模块化应用结构
• example/config_bind: 配置绑定与热重载
• example/auth: 认证与文档安全方案
• example/web_features: Web 组件高级特性

📄 License

MIT License

Documentation

Index

• type Host
  • func New(opts ...Option) *Host
  • func NewHost(opts ...Option) *Host
  • func (h *Host) InjectAuto(target any) error
  • func (h *Host) Invoke(fn any) error
  • func (h *Host) Lifecycle() Lifecycle
  • func (h *Host) Provide(target any, opts ...di.Option) error
  • func (h *Host) Run() error
• type Kernel
  • func NewKernel() Kernel
• type Lifecycle
  • func NewLifecycle() Lifecycle
• type Module
  • func NewModule(name string) *Module
  • func (m *Module) Options(opts ...Option) *Module
  • func (m *Module) Provide(provider any) *Module
  • func (m *Module) Runner(provider any) *Module
• type Option
  • func Import(m *Module) Option
  • func Load(m *Module) Option
  • func Provide(target any, opts ...di.Option) Option
  • func ProvideConfig[T any](key string, defaultVal *T) Option
  • func ProvideMonitor[T any](key string, defaultVal *T) Option
  • func ProvideValue[T any](val T, opts ...di.Option) Option
  • func Runner(target any, opts ...di.Option) Option
  • func WithConfig(file string) Option
• type Runnable
• type State

Types

type Host

type Host struct {
	// contains filtered or unexported fields
}

Host 是应用的通用宿主，负责组合 Kernel 和编排多个 Runnable

func New

func New(opts ...Option) *Host

New 创建一个新的宿主 (NewHost 的别名)

func NewHost

func NewHost(opts ...Option) *Host

NewHost 创建一个新的宿主

func (*Host) InjectAuto

func (h *Host) InjectAuto(target any) error

InjectAuto 从容器中解析服务并填充到 target 指针中

func (*Host) Invoke

func (h *Host) Invoke(fn any) error

Invoke 调用函数并注入依赖

func (*Host) Lifecycle

func (h *Host) Lifecycle() Lifecycle

Lifecycle 获取生命周期接口

func (*Host) Provide

func (h *Host) Provide(target any, opts ...di.Option) error

Provide 注册服务到 DI 容器的快捷方法

func (*Host) Run

func (h *Host) Run() error

Run 启动宿主并阻塞，直到接收到退出信号

type Kernel

type Kernel interface {
	// GetContainer 获取依赖注入容器，用于注册或解析服务
	GetContainer() di.Container

	// GetLifecycle 获取生命周期管理器，用于注册启动/停止钩子
	GetLifecycle() Lifecycle

	// Boot 启动内核
	// 1. 锁定容器（不再允许注册）
	// 2. 构建依赖图
	// 3. 执行所有 OnStart 钩子
	Boot() error

	// Shutdown 停止内核
	// 1. 执行所有 OnStop 钩子（倒序）
	// 2. 释放资源
	Shutdown() error

	// State 返回当前状态
	State() State
}

Kernel 定义了应用核心的最小能力集 它是无状态的（相对于业务逻辑），负责资源管理和生命周期管理

func NewKernel

func NewKernel() Kernel

NewKernel 创建一个新的默认内核

type Lifecycle

type Lifecycle interface {
	OnStart(fn func(context.Context) error)
	OnStop(fn func(context.Context) error)
	Start(ctx context.Context, container di.Container) error
	Stop(ctx context.Context) error
}

Lifecycle 管理应用程序的生命周期

func NewLifecycle

func NewLifecycle() Lifecycle

NewLifecycle 创建新的生命周期管理器

type Module

type Module struct {
	// contains filtered or unexported fields
}

Module 定义了一个功能模块

func NewModule

func NewModule(name string) *Module

NewModule 创建一个新的模块

func (*Module) Options

func (m *Module) Options(opts ...Option) *Module

Options 添加模块选项 (如 ego.ProvideConfig)

func (*Module) Provide

func (m *Module) Provide(provider any) *Module

Provide 注册服务提供者

func (*Module) Runner

func (m *Module) Runner(provider any) *Module

Runner 注册并运行组件 (Provide + Mount)

type Option

type Option func(*Host)

Option 配置 Host 的函数选项

func Import

func Import(m *Module) Option

Import 导入模块到 Host Deprecated: Use Load instead.

func Load

func Load(m *Module) Option

Load 加载模块到 Host

func Provide

func Provide(target any, opts ...di.Option) Option

Provide 返回一个 Option，用于将服务注册到 Host 的 DI 容器中。 target 支持构造函数、结构体指针等。

func ProvideConfig

func ProvideConfig[T any](key string, defaultVal *T) Option

ProvideConfig 注册一个静态配置对象到 DI 容器。 返回的是 *T，不支持热重载。

示例:

ego.ProvideConfig("server", &ServerConfig{Port: 8080})

func ProvideMonitor

func ProvideMonitor[T any](key string, defaultVal *T) Option

ProvideMonitor 注册一个动态配置引用 (Monitor[T])。 返回 config.Monitor[T]，支持热重载。当配置文件变更时，Monitor.Value() 会自动更新。

示例:

ego.ProvideMonitor("feature_flags", &Flags{EnableX: false})
// Use: monitor.Value().EnableX

func ProvideValue

func ProvideValue[T any](val T, opts ...di.Option) Option

ProvideValue 注册一个静态值到 DI 容器。 它本质上是 Provide(func() T { return val }) 的语法糖。

func Runner

func Runner(target any, opts ...di.Option) Option

Runner 注册并运行一个组件。 它是 Provide 和 Mount 的组合。 target: 构造函数或结构体指针。

func WithConfig

func WithConfig(file string) Option

WithConfig 加载配置文件。 file: 完整路径，如 "config.yaml"。 如果 file 为空，默认尝试加载 "config.yaml"。 如果文件不存在，将降级为仅使用环境变量。

type Runnable

type Runnable interface {
	// Start 启动服务
	// 该方法应在新的 goroutine 中执行长驻任务，或者在执行完毕后返回
	// 如果是长驻服务 (如 HTTP Server)，Start 通常是阻塞的
	// Host 会在 goroutine 中调用 Start
	Start(ctx context.Context) error

	// Stop 停止服务
	// 该方法用于通知服务停止，并释放资源
	Stop(ctx context.Context) error

	// Name 返回组件名称，用于日志和调试
	Name() string
}

Runnable 代表一个可以独立启动和停止的服务单元 (如 WebServer, GrpcServer, JobWorker)

type State

type State int

State 定义内核状态

const (
	StateInitialized State = iota
	StateBooted
	StateRunning
	StateStopped
)