《互联网产品的服务端架构·产品、流量与基础能力》6.2 错误码与用户可感知的失败

HTTP/1.1 500 Internal Server Error
{"code":"INTERNAL","message":"pq: duplicate key value violates unique constraint \"stock_pkey\" (SQL: update stock set locked = locked + 1 where sku_id = 8812)"}

// file: internal/api/errors.go
// tier: L1
// verify: go test ./internal/api/

package api

import (
	"fmt"
	"strings"
)

// ErrorCode 是一个对外可见的错误契约。
// 它不带内部错误，也不带堆栈；那些只进日志。
type ErrorCode struct {
	Code        string
	HTTPStatus  int
	UserMessage string
	Retryable   bool
}

// internalWords 是用户文案里不允许出现的实现细节。
// 检查不区分大小写，"SQL" 和 "sql" 都算泄漏。
var internalWords = []string{"sql", "nil", "panic", "stack", "goroutine"}

// Lookup 按 code 精确查找。找不到时返回错误，
// 不允许调用方把未知 code 猜成 500。
func Lookup(codes []ErrorCode, code string) (ErrorCode, error) {
	for _, c := range codes {
		if c.Code == code {
			return c, nil
		}
	}
	return ErrorCode{}, fmt.Errorf("error code %q not found", code)
}

// Validate 检查整张错误码表。
// 任何一条不合格都会让启动失败，而不是等到线上第一次报错。
func Validate(codes []ErrorCode) error {
	seen := make(map[string]bool, len(codes))
	for i, c := range codes {
		if !validCode(c.Code) {
			return fmt.Errorf("codes[%d]: invalid code %q", i, c.Code)
		}
		if seen[c.Code] {
			return fmt.Errorf("codes[%d]: duplicate code %q", i, c.Code)
		}
		seen[c.Code] = true
		if c.HTTPStatus < 400 || c.HTTPStatus > 599 {
			return fmt.Errorf("codes[%d] %s: status %d out of 400..599", i, c.Code, c.HTTPStatus)
		}
		if strings.TrimSpace(c.UserMessage) == "" {
			return fmt.Errorf("codes[%d] %s: empty user message", i, c.Code)
		}
		lower := strings.ToLower(c.UserMessage)
		for _, word := range internalWords {
			if strings.Contains(lower, word) {
				return fmt.Errorf("codes[%d] %s: user message contains %q", i, c.Code, word)
			}
		}
	}
	return nil
}

// validCode 要求首字符是大写字母，其余只允许大写字母、数字和下划线。
func validCode(code string) bool {
	if code == "" || code[0] < 'A' || code[0] > 'Z' {
		return false
	}
	for i := 0; i < len(code); i++ {
		c := code[i]
		if (c >= 'A' && c <= 'Z') || (c >= '0' && c <= '9') || c == '_' {
			continue
		}
		return false
	}
	return true
}

// file: internal/api/errors_test.go
// tier: L1
// verify: go test ./internal/api/

package api

import (
	"strings"
	"testing"
)

func validTable() []ErrorCode {
	return []ErrorCode{
		{Code: "ORDER_NOT_FOUND", HTTPStatus: 404, UserMessage: "订单不存在，请检查后重试", Retryable: false},
		{Code: "RATE_LIMITED", HTTPStatus: 429, UserMessage: "操作太频繁，请稍后再试", Retryable: true},
		{Code: "UPSTREAM_TIMEOUT", HTTPStatus: 503, UserMessage: "服务暂时不可用，请稍后再试", Retryable: true},
	}
}

func TestValidateAcceptsContractTable(t *testing.T) {
	if err := Validate(validTable()); err != nil {
		t.Fatalf("Validate() = %v, want nil", err)
	}
}

func TestValidateRejectsBadRows(t *testing.T) {
	cases := []struct {
		name string
		row  ErrorCode
		want string
	}{
		{
			name: "lowercase code",
			row:  ErrorCode{Code: "order_not_found", HTTPStatus: 404, UserMessage: "订单不存在"},
			want: "invalid code",
		},
		{
			name: "code with dash",
			row:  ErrorCode{Code: "ORDER-NOT-FOUND", HTTPStatus: 404, UserMessage: "订单不存在"},
			want: "invalid code",
		},
		{
			name: "empty code",
			row:  ErrorCode{Code: "", HTTPStatus: 404, UserMessage: "订单不存在"},
			want: "invalid code",
		},
		{
			name: "status below 400",
			row:  ErrorCode{Code: "ORDER_OK", HTTPStatus: 200, UserMessage: "订单正常"},
			want: "out of 400..599",
		},
		{
			name: "status above 599",
			row:  ErrorCode{Code: "ORDER_WEIRD", HTTPStatus: 600, UserMessage: "订单异常"},
			want: "out of 400..599",
		},
		{
			name: "empty message",
			row:  ErrorCode{Code: "ORDER_EMPTY", HTTPStatus: 400, UserMessage: "   "},
			want: "empty user message",
		},
		{
			name: "leaks sql",
			row:  ErrorCode{Code: "ORDER_SAVE_FAILED", HTTPStatus: 500, UserMessage: "insert into orders failed: sql error"},
			want: "contains",
		},
		{
			name: "leaks nil in caps",
			row:  ErrorCode{Code: "ORDER_NIL", HTTPStatus: 500, UserMessage: "order pointer is NIL"},
			want: "contains",
		},
		{
			name: "leaks goroutine",
			row:  ErrorCode{Code: "ORDER_CRASH", HTTPStatus: 500, UserMessage: "goroutine 42 panic"},
			want: "contains",
		},
	}

	for _, tc := range cases {
		t.Run(tc.name, func(t *testing.T) {
			err := Validate([]ErrorCode{tc.row})
			if err == nil {
				t.Fatalf("Validate(%+v) = nil, want error", tc.row)
			}
			if !strings.Contains(err.Error(), tc.want) {
				t.Fatalf("error %q does not contain %q", err, tc.want)
			}
		})
	}
}

func TestValidateRejectsDuplicateCode(t *testing.T) {
	codes := append(validTable(), ErrorCode{
		Code:        "RATE_LIMITED",
		HTTPStatus:  429,
		UserMessage: "请求过多",
	})
	err := Validate(codes)
	if err == nil || !strings.Contains(err.Error(), "duplicate") {
		t.Fatalf("Validate() = %v, want duplicate error", err)
	}
}

func TestLookupFoundAndMissing(t *testing.T) {
	codes := validTable()

	got, err := Lookup(codes, "RATE_LIMITED")
	if err != nil {
		t.Fatalf("Lookup() error: %v", err)
	}
	if got.HTTPStatus != 429 || !got.Retryable {
		t.Fatalf("Lookup() = %+v, want 429 retryable", got)
	}

	if _, err := Lookup(codes, "NOT_A_CODE"); err == nil {
		t.Fatal("unknown code should return an error")
	}
}

cd .local/checks/webapp-lab && go test ./internal/api/ -count=1 -run 'TestValidate|TestLookup' -v

=== RUN   TestValidateAcceptsContractTable
--- PASS: TestValidateAcceptsContractTable (0.00s)
=== RUN   TestValidateRejectsBadRows
=== RUN   TestValidateRejectsBadRows/lowercase_code
=== RUN   TestValidateRejectsBadRows/code_with_dash
=== RUN   TestValidateRejectsBadRows/empty_code
=== RUN   TestValidateRejectsBadRows/status_below_400
=== RUN   TestValidateRejectsBadRows/status_above_599
=== RUN   TestValidateRejectsBadRows/empty_message
=== RUN   TestValidateRejectsBadRows/leaks_sql
=== RUN   TestValidateRejectsBadRows/leaks_nil_in_caps
=== RUN   TestValidateRejectsBadRows/leaks_goroutine
--- PASS: TestValidateRejectsBadRows (0.00s)
    --- PASS: TestValidateRejectsBadRows/lowercase_code (0.00s)
    --- PASS: TestValidateRejectsBadRows/code_with_dash (0.00s)
    --- PASS: TestValidateRejectsBadRows/empty_code (0.00s)
    --- PASS: TestValidateRejectsBadRows/status_below_400 (0.00s)
    --- PASS: TestValidateRejectsBadRows/status_above_599 (0.00s)
    --- PASS: TestValidateRejectsBadRows/empty_message (0.00s)
    --- PASS: TestValidateRejectsBadRows/leaks_sql (0.00s)
    --- PASS: TestValidateRejectsBadRows/leaks_nil_in_caps (0.00s)
    --- PASS: TestValidateRejectsBadRows/leaks_goroutine (0.00s)
=== RUN   TestValidateRejectsDuplicateCode
--- PASS: TestValidateRejectsDuplicateCode (0.00s)
=== RUN   TestLookupFoundAndMissing
--- PASS: TestLookupFoundAndMissing (0.00s)
PASS
ok  	webapp/internal/api	0.293s