refactor: 自定义业务错误

backend/internal/infrastructure/errors/errors.go

@@ -0,0 +1,157 @@
+package errors
+
+import (
+	"errors"
+	"fmt"
+	"net/http"
+)
+
+const (
+	UnknownCode   = http.StatusInternalServerError
+	UnknownReason = ""
+)
+
+type Status struct {
+	Code     int32             `json:"code"`
+	Reason   string            `json:"reason,omitempty"`
+	Message  string            `json:"message"`
+	Metadata map[string]string `json:"metadata,omitempty"`
+}
+
+// ApplicationError is the standard error type used to control HTTP responses.
+//
+// Code is expected to be an HTTP status code (e.g. 400/401/403/404/409/500).
+type ApplicationError struct {
+	Status
+	cause error
+}
+
+// Error is kept for backwards compatibility within this package.
+type Error = ApplicationError
+
+func (e *ApplicationError) Error() string {
+	if e == nil {
+		return "<nil>"
+	}
+	if e.cause == nil {
+		return fmt.Sprintf("error: code=%d reason=%q message=%q metadata=%v", e.Code, e.Reason, e.Message, e.Metadata)
+	}
+	return fmt.Sprintf("error: code=%d reason=%q message=%q metadata=%v cause=%v", e.Code, e.Reason, e.Message, e.Metadata, e.cause)
+}
+
+// Unwrap provides compatibility for Go 1.13 error chains.
+func (e *ApplicationError) Unwrap() error { return e.cause }
+
+// Is matches each error in the chain with the target value.
+func (e *ApplicationError) Is(err error) bool {
+	if se := new(ApplicationError); errors.As(err, &se) {
+		return se.Code == e.Code && se.Reason == e.Reason
+	}
+	return false
+}
+
+// WithCause attaches the underlying cause of the error.
+func (e *ApplicationError) WithCause(cause error) *ApplicationError {
+	err := Clone(e)
+	err.cause = cause
+	return err
+}
+
+// WithMetadata deep-copies the given metadata map.
+func (e *ApplicationError) WithMetadata(md map[string]string) *ApplicationError {
+	err := Clone(e)
+	if md == nil {
+		err.Metadata = nil
+		return err
+	}
+	err.Metadata = make(map[string]string, len(md))
+	for k, v := range md {
+		err.Metadata[k] = v
+	}
+	return err
+}
+
+// New returns an error object for the code, message.
+func New(code int, reason, message string) *ApplicationError {
+	return &ApplicationError{
+		Status: Status{
+			Code:    int32(code),
+			Message: message,
+			Reason:  reason,
+		},
+	}
+}
+
+// Newf New(code fmt.Sprintf(format, a...))
+func Newf(code int, reason, format string, a ...any) *ApplicationError {
+	return New(code, reason, fmt.Sprintf(format, a...))
+}
+
+// Errorf returns an error object for the code, message and error info.
+func Errorf(code int, reason, format string, a ...any) error {
+	return New(code, reason, fmt.Sprintf(format, a...))
+}
+
+// Code returns the http code for an error.
+// It supports wrapped errors.
+func Code(err error) int {
+	if err == nil {
+		return http.StatusOK
+	}
+	return int(FromError(err).Code)
+}
+
+// Reason returns the reason for a particular error.
+// It supports wrapped errors.
+func Reason(err error) string {
+	if err == nil {
+		return UnknownReason
+	}
+	return FromError(err).Reason
+}
+
+// Message returns the message for a particular error.
+// It supports wrapped errors.
+func Message(err error) string {
+	if err == nil {
+		return ""
+	}
+	return FromError(err).Message
+}
+
+// Clone deep clone error to a new error.
+func Clone(err *ApplicationError) *ApplicationError {
+	if err == nil {
+		return nil
+	}
+	var metadata map[string]string
+	if err.Metadata != nil {
+		metadata = make(map[string]string, len(err.Metadata))
+		for k, v := range err.Metadata {
+			metadata[k] = v
+		}
+	}
+	return &ApplicationError{
+		cause: err.cause,
+		Status: Status{
+			Code:     err.Code,
+			Reason:   err.Reason,
+			Message:  err.Message,
+			Metadata: metadata,
+		},
+	}
+}
+
+// FromError tries to convert an error to *ApplicationError.
+// It supports wrapped errors.
+func FromError(err error) *ApplicationError {
+	if err == nil {
+		return nil
+	}
+	if se := new(ApplicationError); errors.As(err, &se) {
+		return se
+	}
+
+	// Fall back to a generic internal error.
+	return New(UnknownCode, UnknownReason, err.Error()).WithCause(err)
+}

backend/internal/infrastructure/errors/errors_test.go

@@ -0,0 +1,168 @@
+//go:build unit
+
+package errors
+
+import (
+	stderrors "errors"
+	"fmt"
+	"io"
+	"net/http"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestApplicationError_Basics(t *testing.T) {
+	tests := []struct {
+		name    string
+		err     *ApplicationError
+		want    Status
+		wantIs  bool
+		target  error
+		wrapped error
+	}{
+		{
+			name: "new",
+			err:  New(400, "BAD_REQUEST", "invalid input"),
+			want: Status{
+				Code:    400,
+				Reason:  "BAD_REQUEST",
+				Message: "invalid input",
+			},
+		},
+		{
+			name:   "is_matches_code_and_reason",
+			err:    New(401, "UNAUTHORIZED", "nope"),
+			want:   Status{Code: 401, Reason: "UNAUTHORIZED", Message: "nope"},
+			target: New(401, "UNAUTHORIZED", "ignored message"),
+			wantIs: true,
+		},
+		{
+			name:   "is_does_not_match_reason",
+			err:    New(401, "UNAUTHORIZED", "nope"),
+			want:   Status{Code: 401, Reason: "UNAUTHORIZED", Message: "nope"},
+			target: New(401, "DIFFERENT", "ignored message"),
+			wantIs: false,
+		},
+		{
+			name:    "from_error_unwraps_wrapped_application_error",
+			err:     New(404, "NOT_FOUND", "missing"),
+			wrapped: fmt.Errorf("wrap: %w", New(404, "NOT_FOUND", "missing")),
+			want: Status{
+				Code:    404,
+				Reason:  "NOT_FOUND",
+				Message: "missing",
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if tt.err != nil {
+				require.Equal(t, tt.want, tt.err.Status)
+			}
+
+			if tt.target != nil {
+				require.Equal(t, tt.wantIs, stderrors.Is(tt.err, tt.target))
+			}
+
+			if tt.wrapped != nil {
+				got := FromError(tt.wrapped)
+				require.Equal(t, tt.want, got.Status)
+			}
+		})
+	}
+}
+
+func TestApplicationError_WithMetadataDeepCopy(t *testing.T) {
+	tests := []struct {
+		name string
+		md   map[string]string
+	}{
+		{name: "non_nil", md: map[string]string{"a": "1"}},
+		{name: "nil", md: nil},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			appErr := BadRequest("BAD_REQUEST", "invalid input").WithMetadata(tt.md)
+
+			if tt.md == nil {
+				require.Nil(t, appErr.Metadata)
+				return
+			}
+
+			tt.md["a"] = "changed"
+			require.Equal(t, "1", appErr.Metadata["a"])
+		})
+	}
+}
+
+func TestFromError_Generic(t *testing.T) {
+	tests := []struct {
+		name       string
+		err        error
+		wantCode   int32
+		wantReason string
+		wantMsg    string
+	}{
+		{
+			name:       "plain_error",
+			err:        stderrors.New("boom"),
+			wantCode:   UnknownCode,
+			wantReason: UnknownReason,
+			wantMsg:    "boom",
+		},
+		{
+			name:       "wrapped_plain_error",
+			err:        fmt.Errorf("wrap: %w", io.EOF),
+			wantCode:   UnknownCode,
+			wantReason: UnknownReason,
+			wantMsg:    "wrap: EOF",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := FromError(tt.err)
+			require.Equal(t, tt.wantCode, got.Code)
+			require.Equal(t, tt.wantReason, got.Reason)
+			require.Equal(t, tt.wantMsg, got.Message)
+			require.Equal(t, tt.err, got.Unwrap())
+		})
+	}
+}
+
+func TestToHTTP(t *testing.T) {
+	tests := []struct {
+		name           string
+		err            error
+		wantStatusCode int
+		wantBody       Status
+	}{
+		{
+			name:           "nil_error",
+			err:            nil,
+			wantStatusCode: http.StatusOK,
+			wantBody:       Status{Code: int32(http.StatusOK)},
+		},
+		{
+			name:           "application_error",
+			err:            Forbidden("FORBIDDEN", "no access"),
+			wantStatusCode: http.StatusForbidden,
+			wantBody: Status{
+				Code:    int32(http.StatusForbidden),
+				Reason:  "FORBIDDEN",
+				Message: "no access",
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			code, body := ToHTTP(tt.err)
+			require.Equal(t, tt.wantStatusCode, code)
+			require.Equal(t, tt.wantBody, body)
+		})
+	}
+}

backend/internal/infrastructure/errors/http.go

@@ -0,0 +1,21 @@
+package errors
+
+import "net/http"
+
+// ToHTTP converts an error into an HTTP status code and a JSON-serializable body.
+//
+// The returned body matches the project's Status shape:
+// { code, reason, message, metadata }.
+func ToHTTP(err error) (statusCode int, body Status) {
+	if err == nil {
+		return http.StatusOK, Status{Code: int32(http.StatusOK)}
+	}
+
+	appErr := FromError(err)
+	if appErr == nil {
+		return http.StatusOK, Status{Code: int32(http.StatusOK)}
+	}
+
+	cloned := Clone(appErr)
+	return int(cloned.Code), cloned.Status
+}

backend/internal/infrastructure/errors/types.go

@@ -0,0 +1,114 @@
+// nolint:mnd
+package errors
+
+import "net/http"
+
+// BadRequest new BadRequest error that is mapped to a 400 response.
+func BadRequest(reason, message string) *ApplicationError {
+	return New(http.StatusBadRequest, reason, message)
+}
+
+// IsBadRequest determines if err is an error which indicates a BadRequest error.
+// It supports wrapped errors.
+func IsBadRequest(err error) bool {
+	return Code(err) == http.StatusBadRequest
+}
+
+// TooManyRequests new TooManyRequests error that is mapped to a 429 response.
+func TooManyRequests(reason, message string) *ApplicationError {
+	return New(http.StatusTooManyRequests, reason, message)
+}
+
+// IsTooManyRequests determines if err is an error which indicates a TooManyRequests error.
+// It supports wrapped errors.
+func IsTooManyRequests(err error) bool {
+	return Code(err) == http.StatusTooManyRequests
+}
+
+// Unauthorized new Unauthorized error that is mapped to a 401 response.
+func Unauthorized(reason, message string) *ApplicationError {
+	return New(http.StatusUnauthorized, reason, message)
+}
+
+// IsUnauthorized determines if err is an error which indicates an Unauthorized error.
+// It supports wrapped errors.
+func IsUnauthorized(err error) bool {
+	return Code(err) == http.StatusUnauthorized
+}
+
+// Forbidden new Forbidden error that is mapped to a 403 response.
+func Forbidden(reason, message string) *ApplicationError {
+	return New(http.StatusForbidden, reason, message)
+}
+
+// IsForbidden determines if err is an error which indicates a Forbidden error.
+// It supports wrapped errors.
+func IsForbidden(err error) bool {
+	return Code(err) == http.StatusForbidden
+}
+
+// NotFound new NotFound error that is mapped to a 404 response.
+func NotFound(reason, message string) *ApplicationError {
+	return New(http.StatusNotFound, reason, message)
+}
+
+// IsNotFound determines if err is an error which indicates an NotFound error.
+// It supports wrapped errors.
+func IsNotFound(err error) bool {
+	return Code(err) == http.StatusNotFound
+}
+
+// Conflict new Conflict error that is mapped to a 409 response.
+func Conflict(reason, message string) *ApplicationError {
+	return New(http.StatusConflict, reason, message)
+}
+
+// IsConflict determines if err is an error which indicates a Conflict error.
+// It supports wrapped errors.
+func IsConflict(err error) bool {
+	return Code(err) == http.StatusConflict
+}
+
+// InternalServer new InternalServer error that is mapped to a 500 response.
+func InternalServer(reason, message string) *ApplicationError {
+	return New(http.StatusInternalServerError, reason, message)
+}
+
+// IsInternalServer determines if err is an error which indicates an Internal error.
+// It supports wrapped errors.
+func IsInternalServer(err error) bool {
+	return Code(err) == http.StatusInternalServerError
+}
+
+// ServiceUnavailable new ServiceUnavailable error that is mapped to an HTTP 503 response.
+func ServiceUnavailable(reason, message string) *ApplicationError {
+	return New(http.StatusServiceUnavailable, reason, message)
+}
+
+// IsServiceUnavailable determines if err is an error which indicates an Unavailable error.
+// It supports wrapped errors.
+func IsServiceUnavailable(err error) bool {
+	return Code(err) == http.StatusServiceUnavailable
+}
+
+// GatewayTimeout new GatewayTimeout error that is mapped to an HTTP 504 response.
+func GatewayTimeout(reason, message string) *ApplicationError {
+	return New(http.StatusGatewayTimeout, reason, message)
+}
+
+// IsGatewayTimeout determines if err is an error which indicates a GatewayTimeout error.
+// It supports wrapped errors.
+func IsGatewayTimeout(err error) bool {
+	return Code(err) == http.StatusGatewayTimeout
+}
+
+// ClientClosed new ClientClosed error that is mapped to an HTTP 499 response.
+func ClientClosed(reason, message string) *ApplicationError {
+	return New(499, reason, message)
+}
+
+// IsClientClosed determines if err is an error which indicates a IsClientClosed error.
+// It supports wrapped errors.
+func IsClientClosed(err error) bool {
+	return Code(err) == 499
+}