《互联网产品的服务端架构·产品、流量与基础能力》7.1 静态与动态的分界

// file: internal/edge/static.go
// tier: L1
// verify: go test ./internal/edge/

package edge

import (
	"errors"
	"fmt"
	"path"
	"strings"
)

// PathKind 表示一个请求路径属于哪类内容，分类结果决定缓存与回源策略。
type PathKind string

const (
	// KindStatic 是同一份内容对所有人都相同的资源。
	KindStatic PathKind = "static"
	// KindDynamic 是需要按用户或请求上下文生成的内容。
	KindDynamic PathKind = "dynamic"
	// KindAPI 是程序接口，不应被共享缓存保存。
	KindAPI PathKind = "api"
)

var (
	// ErrEmptyPath 表示调用方没有提供路径。
	ErrEmptyPath = errors.New("edge: empty path")
	// ErrRelativePath 表示路径不是以 / 开头。
	ErrRelativePath = errors.New("edge: path must start with /")
	// ErrDotDot 表示路径包含 .. 片段，可能是目录穿越。
	ErrDotDot = errors.New("edge: path contains ..")
)

// staticDirs 是产品约定为静态资源的目录。即使目录里的文件没有扩展名，
// 也按静态处理。
var staticDirs = []string{"/css/", "/images/", "/fonts/"}

// staticExts 是允许边缘长期缓存的扩展名集合。
var staticExts = map[string]bool{
	".css": true, ".js": true, ".mjs": true, ".map": true,
	".png": true, ".jpg": true, ".jpeg": true, ".gif": true,
	".svg": true, ".webp": true, ".avif": true, ".ico": true,
	".woff": true, ".woff2": true, ".ttf": true, ".pdf": true,
}

// ClassifyPath 判断路径的内容类别。查询串会被忽略，但路径本身必须是
// 以 / 开头的绝对路径，且不能包含 .. 片段。
func ClassifyPath(p string) (PathKind, error) {
	if p == "" {
		return "", ErrEmptyPath
	}
	if !strings.HasPrefix(p, "/") {
		return "", fmt.Errorf("%w: %q", ErrRelativePath, p)
	}
	if strings.Contains(p, "..") {
		return "", fmt.Errorf("%w: %q", ErrDotDot, p)
	}

	pathOnly, _, _ := strings.Cut(p, "?")
	switch {
	case pathOnly == "/api" || strings.HasPrefix(pathOnly, "/api/"):
		return KindAPI, nil
	case isStaticPath(pathOnly):
		return KindStatic, nil
	default:
		return KindDynamic, nil
	}
}

// isStaticPath 只看目录约定和扩展名。API 前缀在调用方已经先行判断，
// 所以 /api/export.csv 不会被这里误判成静态文件。
func isStaticPath(p string) bool {
	for _, dir := range staticDirs {
		if strings.HasPrefix(p, dir) {
			return true
		}
	}
	return staticExts[strings.ToLower(path.Ext(p))]
}

// Policy 是一次边缘响应的缓存策略。MaxAgeSeconds 为 0 表示不缓存，
// Revalidate 表示每次使用前必须回源确认。
type Policy struct {
	Kind          PathKind
	MaxAgeSeconds int
	Revalidate    bool
}

// PolicyFor 返回某类内容的默认策略。未知类别按 dynamic 处理，
// 宁可回源也不要误缓存。
func PolicyFor(kind PathKind) Policy {
	switch kind {
	case KindStatic:
		return Policy{Kind: KindStatic, MaxAgeSeconds: 86400, Revalidate: false}
	case KindAPI:
		return Policy{Kind: KindAPI, MaxAgeSeconds: 0, Revalidate: true}
	default:
		return Policy{Kind: KindDynamic, MaxAgeSeconds: 0, Revalidate: true}
	}
}

// file: internal/edge/static_test.go
// tier: L1
// verify: go test ./internal/edge/

package edge

import (
	"errors"
	"testing"
)

func TestClassifyPath(t *testing.T) {
	cases := []struct {
		path string
		want PathKind
	}{
		{"/css/app.css", KindStatic},
		{"/images/home/hero.avif", KindStatic},
		{"/fonts/inter.woff2", KindStatic},
		{"/downloads/report.pdf", KindStatic},
		{"/images/logo.png?v=3", KindStatic},
		{"/api", KindAPI},
		{"/api/user/42", KindAPI},
		{"/api/export.csv", KindAPI},
		{"/", KindDynamic},
		{"/posts/edge-cache", KindDynamic},
		{"/search?q=cache", KindDynamic},
	}
	for _, tc := range cases {
		got, err := ClassifyPath(tc.path)
		if err != nil {
			t.Fatalf("ClassifyPath(%q) error: %v", tc.path, err)
		}
		if got != tc.want {
			t.Errorf("ClassifyPath(%q) = %q, want %q", tc.path, got, tc.want)
		}
	}
}

func TestClassifyPathRejectsBadInput(t *testing.T) {
	cases := []struct {
		path string
		want error
	}{
		{"", ErrEmptyPath},
		{"css/app.css", ErrRelativePath},
		{"/images/../etc/passwd", ErrDotDot},
		{"/../secret", ErrDotDot},
	}
	for _, tc := range cases {
		if _, err := ClassifyPath(tc.path); !errors.Is(err, tc.want) {
			t.Errorf("ClassifyPath(%q) error = %v, want %v", tc.path, err, tc.want)
		}
	}
}

func TestPolicyFor(t *testing.T) {
	static := PolicyFor(KindStatic)
	if static.Kind != KindStatic || static.MaxAgeSeconds == 0 || static.Revalidate {
		t.Fatalf("static policy = %+v", static)
	}
	for _, kind := range []PathKind{KindDynamic, KindAPI} {
		p := PolicyFor(kind)
		if p.Kind != kind {
			t.Errorf("PolicyFor(%q).Kind = %q", kind, p.Kind)
		}
		if p.MaxAgeSeconds != 0 {
			t.Errorf("PolicyFor(%q).MaxAgeSeconds = %d, want 0", kind, p.MaxAgeSeconds)
		}
		if !p.Revalidate {
			t.Errorf("PolicyFor(%q).Revalidate = false, want true", kind)
		}
	}
}

func TestPolicyForUnknownKindIsConservative(t *testing.T) {
	p := PolicyFor(PathKind("unknown"))
	if p.Kind != KindDynamic || p.MaxAgeSeconds != 0 || !p.Revalidate {
		t.Fatalf("unknown policy = %+v", p)
	}
}

cd .local/checks/webapp-lab && go test ./internal/edge/ -count=1 -v -run 'TestClassifyPath|TestPolicyFor'

=== RUN   TestClassifyPath
--- PASS: TestClassifyPath (0.00s)
=== RUN   TestClassifyPathRejectsBadInput
--- PASS: TestClassifyPathRejectsBadInput (0.00s)
=== RUN   TestPolicyFor
--- PASS: TestPolicyFor (0.00s)
=== RUN   TestPolicyForUnknownKindIsConservative
--- PASS: TestPolicyForUnknownKindIsConservative (0.00s)
PASS
ok  	webapp/internal/edge	0.224s