chore: initial import

pkg/errors/errors.go

@@ -0,0 +1,52 @@
+package errors
+
+import "fmt"
+
+// AppError 是应用错误结构
+type AppError struct {
+	Code       string // OPS_{CATEGORY}_{CODE}
+	HTTPStatus int
+	Message    string
+	Detail     map[string]any
+}
+
+func (e *AppError) Error() string {
+	return fmt.Sprintf("[%s] %s", e.Code, e.Message)
+}
+
+// 预定义错误
+var (
+	ErrBadRequest      = &AppError{Code: "OPS_GEN_4001", HTTPStatus: 400, Message: "请求参数错误"}
+	ErrUnauthorized    = &AppError{Code: "OPS_GEN_4002", HTTPStatus: 401, Message: "未授权"}
+	ErrForbidden       = &AppError{Code: "OPS_GEN_4003", HTTPStatus: 403, Message: "权限不足"}
+	ErrNotFound        = &AppError{Code: "OPS_GEN_4004", HTTPStatus: 404, Message: "资源不存在"}
+	ErrConflict        = &AppError{Code: "OPS_GEN_4005", HTTPStatus: 409, Message: "资源冲突"}
+	ErrPayloadTooLarge = &AppError{Code: "OPS_GEN_4006", HTTPStatus: 413, Message: "请求体过大"}
+	ErrInternal        = &AppError{Code: "OPS_GEN_5001", HTTPStatus: 500, Message: "内部服务错误"}
+
+	ErrInvalidMetricName = &AppError{Code: "OPS_MET_4001", HTTPStatus: 400, Message: "指标名称无效"}
+	ErrInvalidTimeRange  = &AppError{Code: "OPS_MET_4002", HTTPStatus: 400, Message: "时间范围不合法"}
+)
+
+// WithDetail 为错误添加详细信息
+func (e *AppError) WithDetail(detail map[string]any) *AppError {
+	return &AppError{
+		Code:       e.Code,
+		HTTPStatus: e.HTTPStatus,
+		Message:    e.Message,
+		Detail:     detail,
+	}
+}
+
+// Wrap 包裹原始错误
+func Wrap(err error, appErr *AppError) *AppError {
+	if err == nil {
+		return nil
+	}
+	return &AppError{
+		Code:       appErr.Code,
+		HTTPStatus: appErr.HTTPStatus,
+		Message:    fmt.Sprintf("%s: %v", appErr.Message, err),
+		Detail:     appErr.Detail,
+	}
+}

pkg/errors/errors_test.go

@@ -0,0 +1,45 @@
+package errors
+
+import (
+	"errors"
+	"testing"
+)
+
+func TestAppErrorErrorIncludesCodeAndMessage(t *testing.T) {
+	err := &AppError{Code: "OPS_TEST", Message: "failed"}
+	if got := err.Error(); got != "[OPS_TEST] failed" {
+		t.Fatalf("unexpected error string: %s", got)
+	}
+}
+
+func TestWithDetailReturnsCopyWithoutMutatingBase(t *testing.T) {
+	detail := map[string]any{"field": "name"}
+	err := ErrBadRequest.WithDetail(detail)
+
+	if err == ErrBadRequest {
+		t.Fatal("expected a copy, got original pointer")
+	}
+	if err.Code != ErrBadRequest.Code || err.HTTPStatus != ErrBadRequest.HTTPStatus || err.Message != ErrBadRequest.Message {
+		t.Fatalf("metadata not preserved: %+v", err)
+	}
+	if err.Detail["field"] != "name" {
+		t.Fatalf("detail not attached: %+v", err.Detail)
+	}
+	if ErrBadRequest.Detail != nil {
+		t.Fatalf("base error was mutated: %+v", ErrBadRequest.Detail)
+	}
+}
+
+func TestWrap(t *testing.T) {
+	if Wrap(nil, ErrInternal) != nil {
+		t.Fatal("nil input should return nil")
+	}
+
+	wrapped := Wrap(errors.New("boom"), ErrInternal)
+	if wrapped.Code != ErrInternal.Code || wrapped.HTTPStatus != ErrInternal.HTTPStatus {
+		t.Fatalf("metadata not preserved: %+v", wrapped)
+	}
+	if wrapped.Message != "内部服务错误: boom" {
+		t.Fatalf("unexpected message: %s", wrapped.Message)
+	}
+}