《互联网产品的服务端架构·产品、流量与基础能力》6.3 版本演进与兼容窗口

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

package api

import (
	"fmt"
	"strconv"
	"strings"
	"time"
)

// Version 是产品对外承诺的主次版本。
// 只保留两段：补丁号不应该影响客户端兼容性判断。
type Version struct {
	Major int
	Minor int
}

// String 输出规范形式，用于日志和升级提示。
func (v Version) String() string {
	return fmt.Sprintf("%d.%d", v.Major, v.Minor)
}

// ParseVersion 只接受 "major.minor" 两段十进制整数。
// 前导零、多余段、负数都视为非法，避免 "1.02" 与 "1.2"
// 被当成两个不同版本，导致兼容判断出现分叉。
func ParseVersion(s string) (Version, error) {
	parts := strings.Split(s, ".")
	if len(parts) != 2 {
		return Version{}, fmt.Errorf("parse version %q: want major.minor", s)
	}
	major, err := parsePart(parts[0])
	if err != nil {
		return Version{}, fmt.Errorf("parse version %q: %w", s, err)
	}
	minor, err := parsePart(parts[1])
	if err != nil {
		return Version{}, fmt.Errorf("parse version %q: %w", s, err)
	}
	return Version{Major: major, Minor: minor}, nil
}

func parsePart(s string) (int, error) {
	n, err := strconv.Atoi(s)
	if err != nil || n < 0 || strconv.Itoa(n) != s {
		return 0, fmt.Errorf("invalid segment %q", s)
	}
	return n, nil
}

// Compatible 判断服务端能否继续服务该客户端。
// 同主版本内，服务端次版本不低于客户端即可；
// 主版本变化意味着破坏性变更，必须走新的接入点或迁移。
func Compatible(client, server Version) bool {
	if client.Major != server.Major {
		return false
	}
	return client.Minor <= server.Minor
}

// Sunset 声明某个版本的计划下线时间。
type Sunset struct {
	Version  Version
	RetireAt time.Time
}

// Available 判断版本在 now 是否仍可服务。
// 不可用时返回原因，调用方可以直接放进升级提示。
func Available(v Version, sunsets []Sunset, now time.Time) (bool, string) {
	for _, s := range sunsets {
		if s.Version != v {
			continue
		}
		if !now.Before(s.RetireAt) {
			return false, fmt.Sprintf("version %s retired at %s", v, s.RetireAt.Format(time.RFC3339))
		}
		return true, ""
	}
	return true, ""
}

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

package api

import (
	"strings"
	"testing"
	"time"
)

func mustVersion(t *testing.T, s string) Version {
	t.Helper()
	v, err := ParseVersion(s)
	if err != nil {
		t.Fatalf("ParseVersion(%q): %v", s, err)
	}
	return v
}

func TestParseVersion(t *testing.T) {
	cases := []struct {
		in   string
		want Version
	}{
		{in: "1.0", want: Version{Major: 1, Minor: 0}},
		{in: "1.12", want: Version{Major: 1, Minor: 12}},
		{in: "12.34", want: Version{Major: 12, Minor: 34}},
		{in: "0.0", want: Version{Major: 0, Minor: 0}},
	}
	for _, tc := range cases {
		got, err := ParseVersion(tc.in)
		if err != nil {
			t.Fatalf("ParseVersion(%q): %v", tc.in, err)
		}
		if got != tc.want {
			t.Fatalf("ParseVersion(%q) = %+v, want %+v", tc.in, got, tc.want)
		}
	}
}

func TestParseVersionRejectsMalformed(t *testing.T) {
	for _, in := range []string{"1", "1.2.3", "1.-1", "01.2", "1.02", "a.b", "", "1.2 "} {
		if _, err := ParseVersion(in); err == nil {
			t.Fatalf("ParseVersion(%q) = nil error, want error", in)
		}
	}
}

func TestCompatibleWithinSameMajor(t *testing.T) {
	cases := []struct {
		client string
		server string
		want   bool
	}{
		{client: "1.2", server: "1.5", want: true},
		{client: "1.5", server: "1.5", want: true},
		{client: "1.5", server: "1.2", want: false},
		{client: "2.0", server: "1.9", want: false},
		{client: "1.9", server: "2.0", want: false},
	}
	for _, tc := range cases {
		client := mustVersion(t, tc.client)
		server := mustVersion(t, tc.server)
		if got := Compatible(client, server); got != tc.want {
			t.Fatalf("Compatible(%s, %s) = %v, want %v", tc.client, tc.server, got, tc.want)
		}
	}
}

func TestAvailableBeforeAndAfterSunset(t *testing.T) {
	retire := time.Date(2026, 12, 31, 0, 0, 0, 0, time.UTC)
	sunsets := []Sunset{{Version: Version{Major: 1, Minor: 2}, RetireAt: retire}}

	ok, reason := Available(Version{Major: 1, Minor: 2}, sunsets, retire.Add(-time.Hour))
	if !ok || reason != "" {
		t.Fatalf("before sunset = %v, %q; want true, empty", ok, reason)
	}

	ok, reason = Available(Version{Major: 1, Minor: 2}, sunsets, retire)
	if ok {
		t.Fatal("version must be unavailable exactly at RetireAt")
	}
	if !strings.Contains(reason, "retired") || !strings.Contains(reason, "1.2") {
		t.Fatalf("reason = %q, want retired version 1.2", reason)
	}
}

func TestAvailableUnlistedAndOtherVersions(t *testing.T) {
	retire := time.Date(2026, 12, 31, 0, 0, 0, 0, time.UTC)
	sunsets := []Sunset{{Version: Version{Major: 1, Minor: 2}, RetireAt: retire}}
	now := retire.Add(24 * time.Hour)

	if ok, _ := Available(Version{Major: 1, Minor: 3}, sunsets, now); !ok {
		t.Fatal("version 1.3 has no sunset entry and must stay available")
	}
	if ok, _ := Available(Version{Major: 1, Minor: 2}, nil, now); !ok {
		t.Fatal("empty sunset list must keep the version available")
	}
}

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

=== RUN   TestParseVersion
--- PASS: TestParseVersion (0.00s)
=== RUN   TestParseVersionRejectsMalformed
--- PASS: TestParseVersionRejectsMalformed (0.00s)
=== RUN   TestCompatibleWithinSameMajor
--- PASS: TestCompatibleWithinSameMajor (0.00s)
=== RUN   TestAvailableBeforeAndAfterSunset
--- PASS: TestAvailableBeforeAndAfterSunset (0.00s)
=== RUN   TestAvailableUnlistedAndOtherVersions
--- PASS: TestAvailableUnlistedAndOtherVersions (0.00s)
PASS
ok  	webapp/internal/api	0.230s