Go语言包装数据库错误的最佳实践：避免暴露底层存储细节

你的当前实现不符合Go 1.13错误处理的核心建议，主要问题是丢失了原始错误上下文，且返回的错误信息过于模糊，上层调用方无法准确判断错误类型。下面是具体问题分析和地道的实现方式：

当前实现的问题 #

• 丢失原始错误链：直接返回新的字符串错误，没有保留底层的pgconn.PgError或原始错误信息，导致上层无法用errors.As/errors.Is进一步判断错误类型，也不利于调试（无法看到原始错误的详细堆栈或代码）。
• 错误信息过于笼统：所有非23505的PostgreSQL错误都返回"unknown error"，上层无法区分是查询错误、扫描错误还是其他数据库问题。
• 无自定义错误类型：调用方只能通过字符串匹配判断错误，这是脆弱的（字符串变更会导致判断失效）。

地道的实现方式 #

1. 定义自定义错误类型 #

为store包明确自定义错误类型，包含原始错误和可枚举的错误类型标识：

package store

import (
	"errors"
	"fmt"
	"github.com/jackc/pgconn"
)

// StoreError 存储层自定义错误，包含原始错误和分类
type StoreError struct {
	Err  error       // 原始错误，用于错误链传递
	Type ErrorType   // 错误类型，方便上层判断
}

// ErrorType 存储层错误类型枚举
type ErrorType int

const (
	ErrorTypeUnknown ErrorType = iota
	ErrorTypeDuplicateRecord // 唯一键冲突（PostgreSQL码23505）
	ErrorTypeQueryFailed      // SQL查询执行失败
	ErrorTypeScanFailed       // 查询结果扫描失败
)

// Error 实现error接口，返回业务友好的错误信息
func (e *StoreError) Error() string {
	switch e.Type {
	case ErrorTypeDuplicateRecord:
		return "record already exists"
	case ErrorTypeQueryFailed:
		return fmt.Sprintf("query failed: %v", e.Err)
	case ErrorTypeScanFailed:
		return fmt.Sprintf("scan failed: %v", e.Err)
	default:
		return fmt.Sprintf("unknown store error: %v", e.Err)
	}
}

// Unwrap 实现errors.Unwrap接口，支持错误链解析
func (e *StoreError) Unwrap() error {
	return e.Err
}

2. 改进错误包装逻辑 #

包装错误时保留原始错误链，同时针对特定PostgreSQL错误码覆盖错误类型：

func newStoreError(err error, errType ErrorType) error {
	// 检查是否是PostgreSQL特定错误，匹配错误码更新类型
	var pgErr *pgconn.PgError
	if errors.As(err, &pgErr) {
		switch pgErr.Code {
		case "23505":
			errType = ErrorTypeDuplicateRecord
		}
	}

	return &StoreError{
		Err:  err,
		Type: errType,
	}
}

3. 业务代码中使用 #

调用时明确传递当前错误场景的类型：

rows, err := s.db.Query(context.Background(), stmt, ...args)
if err != nil {
    return nil, newStoreError(err, ErrorTypeQueryFailed)
}

if err := pgxscan.ScanOne(entity, rows); err != nil {
    return nil, newStoreError(err, ErrorTypeScanFailed)
}

4. 上层调用方的错误处理 #

上层通过errors.As获取自定义错误，根据类型做不同处理：

entity, err := store.Get(ctx, id)
if err != nil {
	var storeErr *store.StoreError
	if errors.As(err, &storeErr) {
		switch storeErr.Type {
		case store.ErrorTypeDuplicateRecord:
			// 处理重复记录业务逻辑，比如返回HTTP 409
			http.Error(w, "该记录已存在", http.StatusConflict)
		case store.ErrorTypeQueryFailed:
			http.Error(w, "数据库查询失败", http.StatusInternalServerError)
		default:
			http.Error(w, "服务器错误", http.StatusInternalServerError)
		}
		// 调试时可打印原始错误
		log.Printf("store error detail: %v", storeErr.Err)
		return
	}
	// 处理非存储层错误
	http.Error(w, "服务器错误", http.StatusInternalServerError)
}

符合Go 1.13错误处理的核心原则 #

• 保留错误链：通过Unwrap接口和自定义错误的Err字段，完整保留原始错误信息，支持调试和上层进一步解析。
• 明确错误类型：用枚举类型代替字符串匹配，判断逻辑更健壮。
• 内外分离：对外暴露业务友好的错误信息，内部保留原始错误用于问题排查。
• 兼容标准库：支持errors.As/errors.Is等标准错误处理工具。

内容的提问来源于stack exchange，提问作者ga9isdjf21