Key Source Files in JFrame: A Complete Guide to the Go Framework Architecture

The key source files in jframe are organized into six main areas: entry point (main.go), server command (cmd/server/server.go), configuration (conf/config.go), kernel (core/kernel/kernel.go), logging (core/logx/logger.go), and modules (mod/ directory), forming a modular Go framework for building services.

JFrame is a lightweight Go framework designed for building services through a command-line entry point and modular architecture. Understanding the key source files in jframe is essential for developers who want to extend the framework, debug issues, or implement custom modules. This guide breaks down the critical files that handle everything from CLI parsing to module lifecycle management.

Entry Point and CLI Structure

main.go - The Application Entry Point

The journey begins in main.go at the repository root. This file serves as the minimal entry point that immediately delegates to the Cobra-based command system.

// main.go
package main

import "github.com/juanjitech/jframe/cmd"

func main() {
    cmd.Execute()
}

This delegation pattern keeps the root main.go clean while allowing the cmd/ package to handle all CLI logic.

cmd/server/server.go - Server Command Implementation

The cmd/server/server.go file contains the primary server command implementation. This is where the framework boots up and orchestrates all components.

Key responsibilities of this file include:

• Loading configuration via conf.LoadConfig()
• Initializing optional dependencies like Sentry error tracking
• Creating a TCP listener and cmux multiplexer for protocol routing
• Constructing the kernel instance
• Registering modules from modList.ModList
• Starting the server loop via kernel.StartModule()

Configuration Management

conf/config.go - Viper-Based Configuration Loading

Configuration in jframe is handled by Viper through conf/config.go. This file defines the GlobalConfig struct and provides the LoadConfig() function.

The configuration system:

• Reads from config.yaml (or a custom file specified via -c flag)
• Watches for file changes at runtime
• Unmarshals data into the global configuration accessible via conf.Get()

// Example configuration access
config := conf.Get()
port := config.Server.Port

Core Kernel Architecture

core/kernel/kernel.go - The Framework Heart

The core/kernel/kernel.go file implements the kernel, which is the central orchestrator of the jframe framework. This is arguably the most critical source file in jframe.

The kernel manages:

• Context management: Creates a cancellable root context for graceful shutdowns
• Dependency injection: Uses github.com/juanjiTech/inject/v2 to map objects like the TCP listener and cmux multiplexer
• Module lifecycle: Orchestrates the execution of lifecycle hooks in strict order
• Dynamic configuration: Unmarshals module-specific configuration sections using mapstructure tags

The kernel stores registered modules in a thread-safe map and exposes RegMod() for registration.

core/kernel/module.go - Module Interface Definition

The core/kernel/module.go file defines the Module interface that all jframe modules must implement. This interface establishes the contract for the lifecycle hooks:

• Name() string - Returns the module identifier
• Config() interface{} - Returns a pointer to the module's configuration struct
• PreInit(*hub.Hub) error - Early initialization before dependencies are ready
• Init(*hub.Hub) error - Main initialization with access to injected dependencies
• PostInit(*hub.Hub) error - Post-initialization cleanup
• Load(*hub.Hub) error - Loading phase for data preparation
• Start(*hub.Hub) error - Starts the module's background operations
• Stop(*sync.WaitGroup, context.Context) error - Graceful shutdown handling

Logging Infrastructure

core/logx/logger.go - Centralized Logging with Zap

The core/logx/logger.go file provides the centralized logging abstraction built on Zap. This utility ensures consistent logging across all modules.

Key features:

• PreInit() configures a simple console logger for early boot messages
• Init(level) builds the production logger with optional file rotation via lumberjack and Tencent Cloud CLS integration
• NameSpace(name) returns a Zap SugaredLogger scoped to a specific module, creating prefixed log lines like module.myservice

// Usage inside a module
log := logx.NameSpace("module.myservice")
log.Infow("initialising", "config", cfg)

Module System and Examples

mod/example/mod.go - Reference Module Implementation

The mod/example/mod.go file serves as the canonical reference for implementing jframe modules. It demonstrates the proper structure including:

• Implementing the Module interface
• Defining configuration structs
• Creating service layers, models, and DAOs
• Proper lifecycle method implementations

Developers should study this file when creating custom modules to ensure compliance with jframe conventions.

cmd/server/modList/list.go - Module Registry

The cmd/server/modList/list.go file acts as the central registry for all active modules. It contains the ModList slice that the server command iterates over during kernel initialization.

To activate a new module, developers simply append their module instance to this list:

var ModList = []kernel.Module{
    &example.Example{},
    &myservice.MyService{}, // Add your module here
}

Utility Packages

pkg/utils/ and pkg/ip/ - Helper Functions

The pkg/utils/ directory contains generic helper functions including HTTP client wrappers, pagination utilities, cryptography helpers, and random ID generators.

The pkg/ip/ip.go file specifically handles local network interface discovery, helping the framework display accessible server addresses on startup.

These utility packages are designed to be lightweight with no external side effects, making them safe to import from any module without creating circular dependencies.

Summary

• main.go delegates to the Cobra CLI, keeping the entry point minimal and clean.
• cmd/server/server.go orchestrates the entire boot process, from config loading to kernel initialization.
• conf/config.go manages Viper-based configuration with hot-reload capabilities.
• core/kernel/kernel.go serves as the framework heart, managing dependency injection and module lifecycles.
• core/kernel/module.go defines the interface contract that all modules must implement.
• core/logx/logger.go provides centralized Zap-based logging with namespace scoping.
• mod/example/mod.go offers a reference implementation for custom modules.
• cmd/server/modList/list.go acts as the central registry for active modules.

Frequently Asked Questions

What is the purpose of the kernel in jframe?

The kernel in core/kernel/kernel.go serves as the central orchestrator that manages the entire application lifecycle. It handles dependency injection using github.com/juanjiTech/inject/v2, maintains a cancellable root context for graceful shutdowns, and executes module lifecycle hooks in strict order from PreInit through Stop.

How does jframe handle configuration changes at runtime?

JFrame uses Viper through conf/config.go to watch configuration files for changes. The LoadConfig() function sets up file watchers on config.yaml (or custom specified files), allowing the framework to unmarshal updated values into the global GlobalConfig struct without requiring a server restart.

Where should I register a new module in jframe?

New modules must be registered in cmd/server/modList/list.go by appending an instance of your module to the ModList slice. This central registry is iterated by the server command during kernel initialization in cmd/server/server.go, ensuring your module receives all lifecycle callbacks.

What logging library does jframe use?

JFrame uses Uber Zap for structured logging, abstracted through core/logx/logger.go. The framework provides namespace scoping via logx.NameSpace(), which returns a Zap SugaredLogger prefixed with the module name, enabling easy log filtering and optional integration with Tencent Cloud CLS and file rotation via lumberjack.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}