feat: 增强错误处理与示例

errors.go

@@ -0,0 +1,231 @@
+package reflux
+
+import (
+	"errors"
+	"fmt"
+	"reflect"
+)
+
+// 预定义的基础错误
+
+// ErrEmptyPath 表示路径为空
+var ErrEmptyPath = errors.New("rfx: empty path")
+
+// ErrAppendNotSupported 表示 Append 操作不支持当前类型
+var ErrAppendNotSupported = errors.New("rfx: Append only supports slice type")
+
+// ErrAppendNilValue 表示无法向 nil 值追加
+var ErrAppendNilValue = errors.New("rfx: cannot append to nil value")
+
+// ErrNilPointerInPath 表示路径中存在 nil 指针或接口
+var ErrNilPointerInPath = errors.New("rfx: nil pointer/interface in path")
+
+// ErrInvalidValueInPath 表示路径中的值无效
+var ErrInvalidValueInPath = errors.New("rfx: invalid value in path")
+
+// ErrValueCannotBeSet 表示值无法被设置
+var ErrValueCannotBeSet = errors.New("rfx: value cannot be set")
+
+// ErrTargetNilPointer 表示目标是 nil 指针或接口
+var ErrTargetNilPointer = errors.New("rfx: target is nil pointer/interface")
+
+// ErrInvalidValue 表示值无效的基础错误
+var ErrInvalidValue = errors.New("rfx: invalid value")
+
+// ErrCannotSet 表示无法设置的基础错误
+var ErrCannotSet = errors.New("rfx: cannot set value")
+
+// ErrFieldNotFound 表示字段不存在的基础错误
+var ErrFieldNotFound = errors.New("rfx: field not found")
+
+// ErrKeyNotFound 表示键不存在的基础错误
+var ErrKeyNotFound = errors.New("rfx: key not found")
+
+// ErrValueNotFound 表示值不存在的基础错误
+var ErrValueNotFound = errors.New("rfx: value not found")
+
+// ErrInvalidIndex 表示索引无效的基础错误
+var ErrInvalidIndex = errors.New("rfx: invalid index")
+
+// ErrElementInvalid 表示元素无效的基础错误
+var ErrElementInvalid = errors.New("rfx: element invalid")
+
+// ErrUnsupportedType 表示不支持的类型的基础错误
+var ErrUnsupportedType = errors.New("rfx: unsupported type")
+
+// ErrCannotAssign 表示无法赋值的基础错误
+var ErrCannotAssign = errors.New("rfx: cannot assign value")
+
+// ErrIndexOutOfRange 表示索引越界的基础错误
+var ErrIndexOutOfRange = errors.New("rfx: index out of range")
+
+// ErrNormalizeFailed 表示规范化失败的基础错误
+var ErrNormalizeFailed = errors.New("rfx: normalize failed")
+
+// ErrCannotConvert 表示无法转换的基础错误
+var ErrCannotConvert = errors.New("rfx: cannot convert")
+
+// ErrSetFailed 表示设置失败的基础错误
+var ErrSetFailed = errors.New("rfx: set failed")
+
+// ErrInvalidValue 相关
+
+// NewErrInvalidValueForPath 创建路径值无效错误
+func NewErrInvalidValueForPath(path string) error {
+	return fmt.Errorf("%w for path '%s'", ErrInvalidValue, path)
+}
+
+// ErrCannotSet 相关
+
+// NewErrCannotSetPath 创建无法设置路径错误
+func NewErrCannotSetPath(path string) error {
+	return fmt.Errorf("%w at path '%s'", ErrCannotSet, path)
+}
+
+// NewErrFieldCannotSet 创建字段无法设置错误
+func NewErrFieldCannotSet(fieldName string, fieldType reflect.Type) error {
+	return fmt.Errorf("%w, field '%s' (type: %s) (unexported or not addressable)", ErrCannotSet, fieldName, fieldType)
+}
+
+// NewErrSliceElementCannotSet 创建切片元素无法设置错误
+func NewErrSliceElementCannotSet(index int) error {
+	return fmt.Errorf("%w, slice element at index %d", ErrCannotSet, index)
+}
+
+// NewErrArrayElementCannotSet 创建数组元素无法设置错误
+func NewErrArrayElementCannotSet(index int) error {
+	return fmt.Errorf("%w, array element at index %d", ErrCannotSet, index)
+}
+
+// ErrSetFailed 相关
+
+// NewErrSetFailed 创建设置失败错误(包装底层错误)
+func NewErrSetFailed(path string, err error) error {
+	return fmt.Errorf("%w at path '%s': %w", ErrSetFailed, path, err)
+}
+
+// NewErrSetSliceElementFailed 创建设置切片元素失败错误
+func NewErrSetSliceElementFailed(index int, err error) error {
+	return fmt.Errorf("%w, slice element at index %d: %w", ErrSetFailed, index, err)
+}
+
+// NewErrSetStructFieldFailed 创建设置结构体字段失败错误
+func NewErrSetStructFieldFailed(fieldName string, err error) error {
+	return fmt.Errorf("%w, struct field '%s': %w", ErrSetFailed, fieldName, err)
+}
+
+// Append 相关
+
+// NewErrAppendItemFailed 创建追加元素失败错误
+func NewErrAppendItemFailed(index int, err error) error {
+	return fmt.Errorf("rfx: failed to append item at index %d to slice: %w", index, err)
+}
+
+// ErrFieldNotFound / ErrKeyNotFound / ErrValueNotFound 相关
+
+// NewErrFieldNotFound 创建字段不存在错误
+func NewErrFieldNotFound(fieldName string) error {
+	return fmt.Errorf("%w, '%s' in struct", ErrFieldNotFound, fieldName)
+}
+
+// NewErrFieldNotFoundInStruct 创建结构体中字段不存在错误(包含类型信息)
+func NewErrFieldNotFoundInStruct(fieldName string, structType reflect.Type) error {
+	return fmt.Errorf("%w, '%s' in struct %s", ErrFieldNotFound, fieldName, structType)
+}
+
+// NewErrKeyNotFound 创建键不存在错误
+func NewErrKeyNotFound(key string) error {
+	return fmt.Errorf("%w, '%s' in map", ErrKeyNotFound, key)
+}
+
+// NewErrValueNotFound 创建值不存在错误
+func NewErrValueNotFound(key string) error {
+	return fmt.Errorf("%w for key '%s' in map", ErrValueNotFound, key)
+}
+
+// ErrInvalidIndex / ErrIndexOutOfRange / ErrElementInvalid 相关
+
+// NewErrInvalidIndex 创建索引无效错误
+func NewErrInvalidIndex(index string, length int) error {
+	return fmt.Errorf("%w, '%s' for slice/array (len=%d)", ErrInvalidIndex, index, length)
+}
+
+// NewErrInvalidSliceIndex 创建切片索引无效错误
+func NewErrInvalidSliceIndex(index string, err error) error {
+	return fmt.Errorf("%w, slice index '%s': %w", ErrInvalidIndex, index, err)
+}
+
+// NewErrInvalidArrayIndex 创建数组索引无效错误
+func NewErrInvalidArrayIndex(index string, err error) error {
+	return fmt.Errorf("%w, array index '%s': %w", ErrInvalidIndex, index, err)
+}
+
+// NewErrSliceIndexOutOfRange 创建切片索引越界错误
+func NewErrSliceIndexOutOfRange(index, length int) error {
+	return fmt.Errorf("%w, slice index %d (len=%d)", ErrIndexOutOfRange, index, length)
+}
+
+// NewErrArrayIndexOutOfRange 创建数组索引越界错误
+func NewErrArrayIndexOutOfRange(index, length int) error {
+	return fmt.Errorf("%w, array index %d (len=%d)", ErrIndexOutOfRange, index, length)
+}
+
+// NewErrElementInvalid 创建元素无效错误
+func NewErrElementInvalid(index string) error {
+	return fmt.Errorf("%w at index '%s'", ErrElementInvalid, index)
+}
+
+// ErrUnsupportedType 相关
+
+// NewErrUnsupportedType 创建不支持的类型错误
+func NewErrUnsupportedType(kind reflect.Kind, key string) error {
+	return fmt.Errorf("%w, %s at key '%s'", ErrUnsupportedType, kind, key)
+}
+
+// NewErrUnsupportedTargetType 创建不支持的目标类型错误
+func NewErrUnsupportedTargetType(kind reflect.Kind) error {
+	return fmt.Errorf("%w, %s", ErrUnsupportedType, kind)
+}
+
+// NewErrUnsupportedTargetTypeForValue 创建不支持的目标类型错误(包含值类型)
+func NewErrUnsupportedTargetTypeForValue(targetType reflect.Type, inputType string) error {
+	return fmt.Errorf("%w, target %s for value type %s", ErrUnsupportedType, targetType, inputType)
+}
+
+// ErrCannotAssign 相关
+
+// NewErrCannotAssign 创建无法赋值错误
+func NewErrCannotAssign(valueType, targetType reflect.Type) error {
+	return fmt.Errorf("%w, type %s to map value type %s", ErrCannotAssign, valueType, targetType)
+}
+
+// ErrNormalizeFailed 相关
+
+// NewErrNormalizeInputFailed 创建输入规范化失败错误
+func NewErrNormalizeInputFailed(err error) error {
+	return fmt.Errorf("%w, input value: %w", ErrNormalizeFailed, err)
+}
+
+// ErrCannotConvert 相关
+
+// NewErrCannotConvertToSlice 创建无法转换为切片错误
+func NewErrCannotConvertToSlice(sourceType, targetType reflect.Type) error {
+	return fmt.Errorf("%w, %s to slice type %s", ErrCannotConvert, sourceType, targetType)
+}
+
+// NewErrCannotConvertToStruct 创建无法转换为结构体错误
+func NewErrCannotConvertToStruct(sourceType, targetType reflect.Type) error {
+	return fmt.Errorf("%w, %s to struct type %s", ErrCannotConvert, sourceType, targetType)
+}
+
+// NewErrCannotConvertValue 创建无法转换值错误
+func NewErrCannotConvertValue(inputType string, targetType reflect.Type, err error) error {
+	return fmt.Errorf("%w, value of type %s to target type %s: %w", ErrCannotConvert, inputType, targetType, err)
+}
+
+// 其他
+
+// NewErrUnmarshalFailed 创建反序列化失败错误
+func NewErrUnmarshalFailed(targetType reflect.Type, err error) error {
+	return fmt.Errorf("rfx: failed to unmarshal JSON into type %s: %w", targetType, err)
+}