feat: 统一的错误处理

Author: wsshow

README.md

@@ -327,19 +327,129 @@ fmt.Println(doc.Content)
 
 ## 错误处理
 
-所有读取操作都返回 error，建议进行适当的错误处理：
+库提供了统一的错误封装和类型检查功能，方便进行精确的错误处理。
+
+### 预定义错误类型
+
+```go
+var (
+    ErrUnsupportedFormat = errors.New("unsupported file format")  // 不支持的文件格式
+    ErrFileNotFound      = errors.New("file not found")           // 文件不存在
+    ErrFileOpen          = errors.New("failed to open file")      // 无法打开文件
+    ErrFileRead          = errors.New("failed to read file")      // 读取文件失败
+    ErrFileParse         = errors.New("failed to parse file")     // 解析文件失败
+    ErrInvalidFormat     = errors.New("invalid file format")      // 文件格式无效
+    ErrEmptyFile         = errors.New("file is empty")            // 文件为空
+    ErrSheetNotFound     = errors.New("sheet not found")          // 工作表不存在
+)
+```
+
+### 基本错误处理
 
 ```go
 doc, err := docreader.ReadDocument("file.docx")
 if err != nil {
+    log.Printf("读取文件失败: %v", err)
+    return
+}
+```
+
+### 使用错误类型检查
+
+```go
+doc, err := docreader.ReadDocument("file.unknown")
+if err != nil {
+    // 使用 errors.Is 进行错误类型判断
+    if errors.Is(err, docreader.ErrUnsupportedFormat) {
+        log.Println("不支持的文件格式")
+    } else if errors.Is(err, docreader.ErrFileNotFound) {
+        log.Println("文件不存在")
+    } else if errors.Is(err, docreader.ErrFileOpen) {
+        log.Println("无法打开文件")
+    } else {
+        log.Printf("其他错误: %v", err)
+    }
+    return
+}
+```
+
+### 使用辅助函数
+
+```go
+doc, err := docreader.ReadDocument("file.pdf")
+if err != nil {
+    // 使用辅助函数进行错误检查
+    if docreader.IsUnsupportedFormat(err) {
+        log.Println("不支持的文件格式")
+    } else if docreader.IsFileNotFound(err) {
+        log.Println("文件不存在")
+    } else if docreader.IsFileOpen(err) {
+        log.Println("无法打开文件")
+    } else if docreader.IsFileRead(err) {
+        log.Println("读取文件失败")
+    } else if docreader.IsFileParse(err) {
+        log.Println("解析文件失败")
+    } else {
+        log.Printf("未知错误: %v", err)
+    }
+    return
+}
+```
+
+### 获取详细错误信息
+
+```go
+doc, err := docreader.ReadDocument("file.docx")
+if err != nil {
+    // 错误信息包含操作名称和文件路径
+    // 格式: "操作名称: 文件路径: 错误详情"
+    log.Printf("详细错误: %v", err)
+    
+    // 使用 errors.Unwrap 获取原始错误
+    if unwrapped := errors.Unwrap(err); unwrapped != nil {
+        log.Printf("原始错误: %v", unwrapped)
+    }
+    return
+}
+```
+
+### 完整示例
+
+```go
+package main
+
+import (
+    "errors"
+    "log"
+    "github.com/yourusername/docreader"
+)
+
+func main() {
+    filePath := "document.pdf"
+    
+    doc, err := docreader.ReadDocument(filePath)
+    if err != nil {
+        handleError(err)
+        return
+    }
+    
+    log.Printf("成功读取文档，内容长度: %d", len(doc.Content))
+}
+
+func handleError(err error) {
     switch {
-    case strings.Contains(err.Error(), "不支持的文件格式"):
-        log.Println("文件格式不支持")
-    case strings.Contains(err.Error(), "无法打开"):
-        log.Println("文件不存在或无法访问")
+    case docreader.IsUnsupportedFormat(err):
+        log.Println("错误: 不支持的文件格式，请使用 .docx, .pdf, .xlsx, .pptx, .txt, .csv, .md 或 .rtf 格式")
+    case docreader.IsFileNotFound(err):
+        log.Println("错误: 文件不存在，请检查文件路径")
+    case docreader.IsFileOpen(err):
+        log.Println("错误: 无法打开文件，请检查文件权限")
+    case docreader.IsFileRead(err):
+        log.Println("错误: 读取文件失败，文件可能已损坏")
+    case docreader.IsFileParse(err):
+        log.Println("错误: 解析文件失败，文件格式可能不正确")
     default:
-        log.Printf("读取失败: %v", err)
+        log.Printf("错误: %v", err)
     }
-    return
 }
 ```

csv.go

@@ -15,7 +15,7 @@ func (r *CsvReader) ReadText(filePath string) (string, error) {
 	// 打开文件
 	file, err := os.Open(filePath)
 	if err != nil {
-		return "", fmt.Errorf("failed to open csv file: %w", err)
+		return "", WrapError("CsvReader.ReadText", filePath, ErrFileOpen)
 	}
 	defer file.Close()
 
@@ -25,7 +25,7 @@ func (r *CsvReader) ReadText(filePath string) (string, error) {
 	// 读取所有记录
 	records, err := reader.ReadAll()
 	if err != nil {
-		return "", fmt.Errorf("failed to read csv content: %w", err)
+		return "", WrapError("CsvReader.ReadText", filePath, ErrFileRead)
 	}
 
 	var builder strings.Builder
@@ -47,7 +47,7 @@ func (r *CsvReader) GetMetadata(filePath string) (map[string]string, error) {
 	// 打开文件
 	file, err := os.Open(filePath)
 	if err != nil {
-		return nil, fmt.Errorf("failed to open csv file: %w", err)
+		return nil, WrapError("CsvReader.GetMetadata", filePath, ErrFileOpen)
 	}
 	defer file.Close()
 
@@ -57,7 +57,7 @@ func (r *CsvReader) GetMetadata(filePath string) (map[string]string, error) {
 	// 读取所有记录
 	records, err := reader.ReadAll()
 	if err != nil {
-		return nil, fmt.Errorf("failed to read csv content: %w", err)
+		return nil, WrapError("CsvReader.GetMetadata", filePath, ErrFileRead)
 	}
 
 	metadata["rows"] = fmt.Sprintf("%d", len(records))
@@ -79,14 +79,14 @@ func (r *CsvReader) GetMetadata(filePath string) (map[string]string, error) {
 func (r *CsvReader) GetRecords(filePath string) ([][]string, error) {
 	file, err := os.Open(filePath)
 	if err != nil {
-		return nil, fmt.Errorf("failed to open csv file: %w", err)
+		return nil, WrapError("CsvReader.GetRecords", filePath, ErrFileOpen)
 	}
 	defer file.Close()
 
 	reader := csv.NewReader(file)
 	records, err := reader.ReadAll()
 	if err != nil {
-		return nil, fmt.Errorf("failed to read csv content: %w", err)
+		return nil, WrapError("CsvReader.GetRecords", filePath, ErrFileRead)
 	}
 
 	return records, nil

docx.go

@@ -3,7 +3,6 @@ package docreader
 import (
 	"archive/zip"
 	"encoding/xml"
-	"fmt"
 	"io"
 	"strings"
 )
@@ -50,7 +49,7 @@ func (r *DocxReader) ReadText(filePath string) (string, error) {
 	// 打开 zip 文件
 	zipReader, err := zip.OpenReader(filePath)
 	if err != nil {
-		return "", fmt.Errorf("failed to open docx file: %w", err)
+		return "", WrapError("DocxReader.ReadText", filePath, ErrFileOpen)
 	}
 	defer zipReader.Close()
 
@@ -60,25 +59,25 @@ func (r *DocxReader) ReadText(filePath string) (string, error) {
 		if file.Name == "word/document.xml" {
 			rc, err := file.Open()
 			if err != nil {
-				return "", fmt.Errorf("failed to open document.xml: %w", err)
+				return "", WrapError("DocxReader.ReadText", filePath, ErrFileRead)
 			}
 			documentXML, err = io.ReadAll(rc)
 			rc.Close()
 			if err != nil {
-				return "", fmt.Errorf("failed to read document.xml: %w", err)
+				return "", WrapError("DocxReader.ReadText", filePath, ErrFileRead)
 			}
 			break
 		}
 	}
 
 	if documentXML == nil {
-		return "", fmt.Errorf("document.xml not found")
+		return "", WrapError("DocxReader.ReadText", filePath, ErrInvalidFormat)
 	}
 
 	// 解析 XML
 	var doc WordDocument
 	if err := xml.Unmarshal(documentXML, &doc); err != nil {
-		return "", fmt.Errorf("failed to parse XML: %w", err)
+		return "", WrapError("DocxReader.ReadText", filePath, ErrFileParse)
 	}
 
 	// 提取文本
@@ -115,7 +114,7 @@ func (r *DocxReader) ReadText(filePath string) (string, error) {
 func (r *DocxReader) GetMetadata(filePath string) (map[string]string, error) {
 	zipReader, err := zip.OpenReader(filePath)
 	if err != nil {
-		return nil, fmt.Errorf("failed to open docx file: %w", err)
+		return nil, WrapError("DocxReader.GetMetadata", filePath, ErrFileOpen)
 	}
 	defer zipReader.Close()
 

errors.go

@@ -0,0 +1,95 @@
+package docreader
+
+import (
+	"errors"
+	"fmt"
+)
+
+// 预定义的错误类型
+var (
+	// ErrUnsupportedFormat 不支持的文件格式
+	ErrUnsupportedFormat = errors.New("unsupported file format")
+
+	// ErrFileNotFound 文件不存在
+	ErrFileNotFound = errors.New("file not found")
+
+	// ErrFileOpen 无法打开文件
+	ErrFileOpen = errors.New("failed to open file")
+
+	// ErrFileRead 读取文件失败
+	ErrFileRead = errors.New("failed to read file")
+
+	// ErrFileParse 解析文件失败
+	ErrFileParse = errors.New("failed to parse file")
+
+	// ErrInvalidFormat 文件格式无效
+	ErrInvalidFormat = errors.New("invalid file format")
+
+	// ErrEmptyFile 文件为空
+	ErrEmptyFile = errors.New("file is empty")
+
+	// ErrSheetNotFound 工作表不存在
+	ErrSheetNotFound = errors.New("sheet not found")
+)
+
+// DocumentError 文档错误结构
+type DocumentError struct {
+	Op       string // 操作名称
+	FilePath string // 文件路径
+	Err      error  // 原始错误
+}
+
+// Error 实现 error 接口
+func (e *DocumentError) Error() string {
+	if e.FilePath != "" {
+		return fmt.Sprintf("%s: %s: %v", e.Op, e.FilePath, e.Err)
+	}
+	return fmt.Sprintf("%s: %v", e.Op, e.Err)
+}
+
+// Unwrap 返回原始错误，支持 errors.Is 和 errors.As
+func (e *DocumentError) Unwrap() error {
+	return e.Err
+}
+
+// NewError 创建新的文档错误
+func NewError(op, filePath string, err error) error {
+	return &DocumentError{
+		Op:       op,
+		FilePath: filePath,
+		Err:      err,
+	}
+}
+
+// WrapError 包装错误并添加上下文信息
+func WrapError(op, filePath string, err error) error {
+	if err == nil {
+		return nil
+	}
+	return NewError(op, filePath, err)
+}
+
+// IsUnsupportedFormat 检查是否为不支持的格式错误
+func IsUnsupportedFormat(err error) bool {
+	return errors.Is(err, ErrUnsupportedFormat)
+}
+
+// IsFileNotFound 检查是否为文件不存在错误
+func IsFileNotFound(err error) bool {
+	return errors.Is(err, ErrFileNotFound)
+}
+
+// IsFileOpen 检查是否为文件打开错误
+func IsFileOpen(err error) bool {
+	return errors.Is(err, ErrFileOpen)
+}
+
+// IsFileRead 检查是否为文件读取错误
+func IsFileRead(err error) bool {
+	return errors.Is(err, ErrFileRead)
+}
+
+// IsFileParse 检查是否为文件解析错误
+func IsFileParse(err error) bool {
+	return errors.Is(err, ErrFileParse)
+}

md.go

@@ -13,7 +13,7 @@ func (r *MdReader) ReadText(filePath string) (string, error) {
 	// 读取文件内容
 	data, err := os.ReadFile(filePath)
 	if err != nil {
-		return "", fmt.Errorf("failed to read markdown file: %w", err)
+		return "", WrapError("MdReader.ReadText", filePath, ErrFileRead)
 	}
 
 	return string(data), nil
@@ -26,7 +26,7 @@ func (r *MdReader) GetMetadata(filePath string) (map[string]string, error) {
 	// 获取文件信息
 	fileInfo, err := os.Stat(filePath)
 	if err != nil {
-		return nil, fmt.Errorf("failed to get file info: %w", err)
+		return nil, WrapError("MdReader.GetMetadata", filePath, ErrFileNotFound)
 	}
 
 	metadata["size"] = fmt.Sprintf("%d", fileInfo.Size())

pdf.go

@@ -14,7 +14,7 @@ func (r *PdfReader) ReadText(filePath string) (string, error) {
 	// 打开 PDF 文件
 	f, reader, err := pdf.Open(filePath)
 	if err != nil {
-		return "", fmt.Errorf("failed to open PDF file: %w", err)
+		return "", WrapError("PdfReader.ReadText", filePath, ErrFileOpen)
 	}
 	defer f.Close()
 
@@ -47,7 +47,7 @@ func (r *PdfReader) ReadText(filePath string) (string, error) {
 func (r *PdfReader) GetMetadata(filePath string) (map[string]string, error) {
 	f, reader, err := pdf.Open(filePath)
 	if err != nil {
-		return nil, fmt.Errorf("failed to open PDF file: %w", err)
+		return nil, WrapError("PdfReader.GetMetadata", filePath, ErrFileOpen)
 	}
 	defer f.Close()