3. 报表模块的通用架构：分层架构在 Go 中的实现概览

在构建企业级报表模块时，分层架构是最成熟、最稳定的选择。它将关注点分离为四个清晰的层次：接口层、应用层、领域层和基础设施层。每一层都有明确的职责边界，依赖关系严格遵循“外层依赖内层”的原则。

3.1 四层职责与边界

3.2 分层依赖关系与数据流向

下图展示了报表模块的完整分层结构以及请求/响应的流动路径。注意：领域层处于最内层，不依赖任何外部包；基础设施层位于最外层，实现领域层定义的接口。

3.3 各层在 Go 中的典型代码结构

3.3.1 领域层：核心实体与接口

领域层只包含纯 Go 结构体和接口，不导入任何 ORM、Web 框架或数据库驱动。

// domain/report.go
package domain

import "time"

// Report 是报表聚合根
type Report struct {
    ID        string
    Name      string
    DataSet   DataSet
    Filters   []Filter
    CreatedAt time.Time
}

// DataSet 值对象：数据源定义
type DataSet struct {
    SourceID   string
    Query      string
    Aggregator Aggregator
}

// Aggregator 值对象：聚合方式
type Aggregator struct {
    Type  string // "SUM" | "AVG" | "COUNT"
    Field string
}

// ReportRepository 接口：由基础设施层实现
type ReportRepository interface {
    Save(report *Report) error
    FindByID(id string) (*Report, error)
    Delete(id string) error
}

3.3.2 应用层：用例编排

应用层负责协调领域对象完成一个完整的用户故事，不包含业务规则。

// application/report_service.go
package application

import "your-project/domain"

type ReportAppService struct {
    repo domain.ReportRepository
}

func NewReportAppService(repo domain.ReportRepository) *ReportAppService {
    return &ReportAppService{repo: repo}
}

func (s *ReportAppService) CreateReport(name, sourceID, query string) (*domain.Report, error) {
    report := &domain.Report{
        Name: name,
        DataSet: domain.DataSet{
            SourceID: sourceID,
            Query:    query,
        },
    }
    if err := s.repo.Save(report); err != nil {
        return nil, err
    }
    return report, nil
}

3.3.3 接口层：HTTP Handler

接口层将外部请求转换为应用层可处理的 DTO，并返回响应。

// interface/http/report_handler.go
package http

import (
    "net/http"
    "github.com/gin-gonic/gin"
    "your-project/application"
)

type ReportHandler struct {
    svc *application.ReportAppService
}

func (h *ReportHandler) Create(c *gin.Context) {
    var req struct {
        Name     string `json:"name" binding:"required"`
        SourceID string `json:"source_id" binding:"required"`
        Query    string `json:"query" binding:"required"`
    }
    if err := c.ShouldBindJSON(&req); err != nil {
        c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
        return
    }
    report, err := h.svc.CreateReport(req.Name, req.SourceID, req.Query)
    if err != nil {
        c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
        return
    }
    c.JSON(http.StatusOK, report)
}

3.3.4 基础设施层：实现领域接口

基础设施层依赖具体的数据库驱动，但只通过领域接口暴露给上层。

// infrastructure/mysql/report_repo.go
package mysql

import (
    "database/sql"
    "your-project/domain"
)

type MySQLReportRepo struct {
    db *sql.DB
}

func NewMySQLReportRepo(db *sql.DB) *MySQLReportRepo {
    return &MySQLReportRepo{db: db}
}

func (r *MySQLReportRepo) Save(report *domain.Report) error {
    // 实现 INSERT 或 UPDATE 逻辑
    _, err := r.db.Exec("INSERT INTO reports ...")
    return err
}

func (r *MySQLReportRepo) FindByID(id string) (*domain.Report, error) {
    // 实现 SELECT 逻辑
    return &domain.Report{}, nil
}

func (r *MySQLReportRepo) Delete(id string) error {
    _, err := r.db.Exec("DELETE FROM reports WHERE id = ?", id)
    return err
}

3.4 分层架构的收益与常见陷阱

3.5 依赖注入与模块初始化

在 Go 中，推荐使用 构造函数注入 来组装各层。以下是一个典型的 main 函数组装示例：

// cmd/report-server/main.go
package main

import (
    "database/sql"
    "your-project/application"
    "your-project/domain"
    "your-project/infrastructure/mysql"
    httpHandler "your-project/interface/http"
)

func main() {
    // 1. 初始化基础设施
    db, _ := sql.Open("mysql", "dsn")
    repo := mysql.NewMySQLReportRepo(db)

    // 2. 确保 repo 实现了领域接口（编译期检查）
    var _ domain.ReportRepository = repo

    // 3. 初始化应用层
    svc := application.NewReportAppService(repo)

    // 4. 初始化接口层
    handler := httpHandler.NewReportHandler(svc)

    // 5. 启动 HTTP 服务
    // router := gin.Default()
    // router.POST("/reports", handler.Create)
    // router.Run()
}

3.6 分层架构的变体：六边形架构（端口与适配器）

对于更复杂的报表系统，可以在分层架构基础上演变为六边形架构。其核心思想是：领域层通过“端口”（接口）与外界通信，基础设施层提供“适配器”实现这些端口。下图展示了这种演进关系：

六边形架构的优势在于：每个适配器都可以独立替换、独立测试。例如，将报表导出从 Excel 切换为 PDF 时，只需新增一个 PDFExporter 适配器，领域层和应用层完全不受影响。