Freedom Framework

FShop is a complete e-commerce system example demonstrating how to build enterprise-level applications using the Freedom Framework and Domain-Driven Design (DDD) principles. It covers core scenarios like products, shopping carts, orders, and shipping.

Project Structure

• adapter/ (Adapter Layer): Handles external interfaces such as HTTP controllers, repository implementations, and event consumers.
• domain/ (Domain Layer): The core business logic layer. It contains aggregates (using CQS pattern), entities, persistence objects (PO), value objects (VO), domain events, and dependency interfaces. It does not depend on external implementations.
• infra/ (Infrastructure Layer): Provides common capabilities like event handling, caching, and transaction management.

The Worker runtime is a core mechanism in the Freedom framework that provides an independent runtime environment for every request. It enables request-level dependency injection and lifecycle management, allowing developers to share request context across the entire call chain without manually passing context.Context objects.

Key features include:

• Request Isolation: Each request has its own independent Worker instance.
• Automatic Injection: The framework automatically injects the Worker into components.
• Lifecycle Management: The Worker's lifecycle is tied to the request.
• Non-intrusive Propagation: Avoids manual context passing.
• Request-level Storage: Provides a dedicated storage space for the duration of the request.

Freedom is a Go framework based on Domain-Driven Design (DDD) principles. It uses a hexagonal architecture (ports and adapters) to maintain clear separation of concerns. The project structure is organized into several layers:

• domain/: The core business logic layer containing aggregate, entity, event, vo (Value Objects), po (Persistence Objects), and domain services.
• adapter/: The ports and adapters layer. controller acts as the input adapter (handling external requests), and repository acts as the output adapter (persisting domain objects).
• config/: Application configuration management.
• infra/: Infrastructure components providing technical support.

This architecture ensures that business logic is decoupled from technical implementation details like databases or web frameworks.

Freedom uses dependency injection to manage Service dependencies. For injection to work, dependency fields in your Service struct must be exported (start with an uppercase letter).

Supported injectable types include:

• freedom.Worker: The request runtime (one instance per request).
• Repository interfaces: For data access (e.g., dependency.CartRepo).
• Factory pointers: For creating aggregates (e.g., *aggregate.CartFactory).
• Infrastructure components: Such as *domainevent.EventTransaction for transaction management.

The framework encourages an interface-based dependency injection pattern. Define your business logic in interfaces, implement them in repositories or services, and inject the interface into your service structs.

// 1. 定义接口
type GoodsInterface interface {
    GetGoods(goodsID int) vo.GoodsModel
}

// 2. 注入服务
type ShopService struct {
    Worker freedom.Worker
    Goods  repository.GoodsInterface  // 注入接口
}

// 3. 实现接口
type GoodsRepository struct {
    freedom.Repository
}

func (repo *GoodsRepository) GetGoods(goodsID int) vo.GoodsModel {
    // 实现细节
}

Generated PO structs include a private changes map used for change tracking. Instead of updating all fields in a database row, the PO tracks which fields have been modified via Set or Update methods.

When GetChanges() is called, it returns the map of modified fields and clears the internal tracker. This allows the repository to perform efficient updates using only the changed columns.

// Example of the internal change tracking structure
type User struct {
    ID        int       `gorm:"primaryKey;column:id"` 
    Name      string    `gorm:"column:name"` 
    // ... other fields
    changes   map[string]interface{}
}

func (obj *User) Update(name string, value interface{}) {
    if obj.changes == nil {
        obj.changes = make(map[string]interface{})
    }
    obj.changes[name] = value
}

The following table summarizes the core Domain-Driven Design (DDD) abstractions used in the framework:

Freedom uses a middleware system to provide request processing capabilities like logging, monitoring, and retries. Middleware is installed globally using requests.InstallMiddleware(...).

Middleware Interface

To implement a custom middleware, satisfy the Middleware interface:

• Next(): Continue to the next middleware/request.
• Stop(err ...error): Halt execution and return errors.
• GetRequest(): Access the current *http.Request.
• GetRespone(): Access the *Response object.
• Context(): Access the request context.Context.

type Middleware interface {
    Next()                      
    Stop(err ...error)         
    GetRequest() *http.Request 
    GetRespone() *Response     
    Context() context.Context  
}

// Global installation
requests.InstallMiddleware(
    NewLogMiddleware(),
    NewTraceMiddleware(),
    NewRetryMiddleware(3),
)

Aggregates are designed using the CQS (Command Query Separation) principle. An Aggregate Root composes entities rather than inheriting from freedom.Entity.

Command (Write Operations)

• Purpose: Change the system state.
• Return Value: Typically returns an error.
• Execution: Uses a Run() method.
• Side Effects: Has side effects (e.g., updating a database).

Query (Read Operations)

• Purpose: Read data.
• Return Value: Returns data.
• Execution: Uses custom methods (e.g., VisitAllItem()).
• Side Effects: No side effects.

Key Rules

• Aggregate roots should inherit from an Entity, not freedom.Entity.
• Commands and Queries must be strictly separated.
• Commands must ensure atomicity.
• Avoid direct references across different aggregates.
• Define clear aggregate boundaries.