Go 中 REST API 的分层架构与 DTO/Entity 分离实践-Golang-PHP中文网

Go 中 REST API 的分层架构与 DTO/Entity 分离实践

本文介绍 go 项目中如何通过清晰的三层架构（http 处理层、业务逻辑层、数据访问层）解耦 api 响应与数据库结构，避免因数据库变更导致接口破坏，并说明何时及如何合理使用 dto 结构体。

本文介绍 go 项目中如何通过清晰的三层架构（http 处理层、业务逻辑层、数据访问层）解耦 api 响应与数据库结构，避免因数据库变更导致接口破坏，并说明何时及如何合理使用 dto 结构体。

在 Go 生态中，不强制要求像 C# 那样严格区分 Entity、DTO 和 ViewModel，但这不意味着可以忽视关注点分离。恰恰相反，Go 的简洁性更依赖显式的职责划分——尤其当你的 REST API 需长期演进、频繁应对业务变更时，盲目复用数据库结构体（如直接 json.Marshal(entity)）会迅速导致技术债累积：字段重命名、权限控制缺失、敏感字段泄露、序列化格式不兼容等问题将直击 API 稳定性。

✅ 推荐实践：三层解耦 + 按需映射

我们推荐采用 Clean Architecture 思想驱动的轻量分层，而非照搬 ORM 范式。核心是定义清晰的接口契约，让各层仅依赖抽象，而非具体实现：

层级	职责	是否需要独立结构体？	关键原则
HTTP Handler	解析请求、调用 Use Case、序列化响应	✅ 建议定义 `ResponseDTO`（含 `json` tag）	不含业务逻辑；错误需转为 HTTP 状态码/标准错误体
Use Case / Interactor	实现业务规则、协调数据获取与转换	⚠️ 可复用领域结构体（如 `usecases.User`），但禁止暴露数据库细节	结构体属于业务语义，非存储语义；无 `db` 或 `gorm` 等标签
Data Repository	执行 SQL、映射行数据 → 领域结构体	✅ 必须使用 `sqlx`/`pgx` 等支持的 struct（含 `db:"column_name"` tag）	对外只暴露 `DataRepository` 接口；实体字段名可与 DB 完全不同

? 关键洞察：DTO 不是“冗余结构体”，而是 API 合约的具象化表达。即使某次 DTO 与领域结构体字段一致，也应显式声明——这是对前端、文档、OpenAPI 规范的承诺。

Figma REST API 资产导出器
使用 GET /v1/files/:key 和 /v1/images/:key 端点从 Figma 文件中导出设计资源。支持 SVG、PNG 和 PDF 导出，并可设置缩放和格式参数。

下载

? 示例：用户查询场景（精简可运行）

// 1. DTO —— API 响应契约（/api/v1/users）
type UserResponse struct {
    ID       string `json:"id"`
    Name     string `json:"name"`
    Email    string `json:"email"`
    IsActive bool   `json:"is_active"`
}

// 2. 领域结构体（Use Case 层使用）
type User struct {
    Identifier string
    FullName   string
    Contact    string // 业务语义，非 DB 字段名
    Status     string // "active"/"inactive"
}

// 3. 数据库实体（Repository 层使用）
type UserRow struct {
    ID        int64  `db:"id"`
    Name      string `db:"full_name"`
    Email     string `db:"contact_email"`
    IsDeleted bool   `db:"is_deleted"`
}

// Use Case 层：专注业务转换
func (u *UserInteractor) GetUserByID(id int64) (*User, error) {
    row, err := u.repo.FindByID(id)
    if err != nil {
        return nil, fmt.Errorf("user not found: %w", err)
    }
    // 显式转换：屏蔽 DB 细节（如 is_deleted → status）
    status := "inactive"
    if !row.IsDeleted {
        status = "active"
    }
    return &User{
        Identifier: fmt.Sprintf("%d", row.ID),
        FullName:   row.Name,
        Contact:    row.Email,
        Status:     status,
    }, nil
}

// Handler 层：DTO 映射 + 序列化
func (h *UserHandler) Get(w http.ResponseWriter, r *http.Request) {
    id, _ := strconv.ParseInt(chi.URLParam(r, "id"), 10, 64)
    user, err := h.Interactor.GetUserByID(id)
    if err != nil {
        http.Error(w, "User not found", http.StatusNotFound)
        return
    }
    // 映射到 DTO（可借助 mapstructure 或手写）
    dto := UserResponse{
        ID:       user.Identifier,
        Name:     user.FullName,
        Email:    user.Contact,
        IsActive: user.Status == "active",
    }
    json.NewEncoder(w).Encode(dto)
}

⚠️ 注意事项与最佳实践

不要过度设计：小项目可暂省略 DTO，但一旦出现以下任一情况，立即拆分：
- 前端要求字段别名（如 user_name → name）
- 需隐藏敏感字段（如 password_hash）
- 同一实体需多种序列化形态（JSON API vs CSV 导出）
避免“影子 DTO”：若 DTO 与领域结构体 100% 一致，仍建议保留独立类型，并添加注释说明其契约性质（如 // UserResponse defines the public API contract for /users）。
映射工具选择：小规模项目推荐手写映射（清晰、可控、无反射开销）；大规模可选 mapstructure 或 copier，切勿用 reflect 动态映射带 db tag 的结构体到 JSON 输出（易泄露字段）。
SQL 标签隔离：db:"xxx" 仅存在于 Repository 层结构体；DTO 和领域结构体绝不包含任何数据库相关 tag，确保编译期隔离。