本文介绍 go 项目中如何通过清晰的三层架构（http 处理层、业务逻辑层、数据访问层）解耦 api 响应与数据库结构，避免因数据库变更导致接口破坏，并说明何时及如何合理使用 dto 结构体。
本文介绍 go 项目中如何通过清晰的三层架构（http 处理层、业务逻辑层、数据访问层）解耦 api 响应与数据库结构，避免因数据库变更导致接口破坏，并说明何时及如何合理使用 dto 结构体。
在 Go 生态中，不强制要求像 C# 那样严格区分 Entity、DTO 和 ViewModel，但这不意味着可以忽视关注点分离。恰恰相反，Go 的简洁性更依赖显式的职责划分——尤其当你的 REST API 需长期演进、频繁应对业务变更时，盲目复用数据库结构体（如直接 json.Marshal(entity)）会迅速导致技术债累积：字段重命名、权限控制缺失、敏感字段泄露、序列化格式不兼容等问题将直击 API 稳定性。
✅ 推荐实践：三层解耦 + 按需映射
我们推荐采用 Clean Architecture 思想驱动的轻量分层，而非照搬 ORM 范式。核心是定义清晰的接口契约，让各层仅依赖抽象，而非具体实现：
Figma REST API 资产导出器
下载
使用 GET /v1/files/:key 和 /v1/images/:key 端点从 Figma 文件中导出设计资源。支持 SVG、PNG 和 PDF 导出，并可设置缩放和格式参数。
| 层级 | 职责 | 是否需要独立结构体？ | 关键原则 |
|---|---|---|---|
| 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 规范的承诺。
? 示例：用户查询场景（精简可运行）
// 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动态映射带dbtag 的结构体到 JSON 输出（易泄露字段）。 -
SQL 标签隔离：
db:"xxx"仅存在于 Repository 层结构体；DTO 和领域结构体绝不包含任何数据库相关 tag，确保编译期隔离。
✅ 总结
Go 的“简单”不是放弃设计，而是用接口和组合代替继承与框架约束。通过明确分层、按需定义结构体、显式映射，你既能获得 C# 式的松耦合收益，又保持 Go 的轻量与可测试性。记住：DTO 是 API 的宪法，Entity 是数据库的方言，而 Use Case 是二者之间严谨的翻译官。
