《游戏服务端架构·平台化与架构治理》8.3 架构规则的自动化检查

Rule{ID, Source, Level, Kind, Severity, Status, Pattern}
Fact{Kind, Target, Attributes}

package archrules

import (
	"fmt"
	"sort"
	"strings"
	"time"
)

// Source records why a rule exists. A rule without a source is an opinion,
// and opinions do not survive the next reorganisation.
type Source string

const (
	Review     Source = "review"
	Postmortem Source = "postmortem"
	Contract   Source = "contract"
)

// Level is where the check runs. Earlier levels are cheaper and catch fewer
// problems; runtime checks catch configuration drift that no build can see.
type Level string

const (
	CompileTime Level = "compile"
	TestTime    Level = "test"
	Runtime     Level = "runtime"
)

type Status string

const (
	Active  Status = "active"
	Retired Status = "retired"
)

type Severity string

const (
	Warning  Severity = "warning"
	Blocking Severity = "blocking"
)

type Kind string

const (
	ForbiddenDependency Kind = "forbidden-dependency"
	RequiredAttribute   Kind = "required-attribute"
	ConfigDrift         Kind = "config-drift"
)

// Rule is one executable check. Pattern means different things per kind: an
// import prefix, an attribute name, or an expected configuration value.
type Rule struct {
	ID       string
	Source   Source
	Level    Level
	Kind     Kind
	Severity Severity
	Status   Status
	Pattern  string
}

// Fact is the observation a rule runs against. Keeping facts as data rather
// than callbacks lets the same rule engine run in CI and in production.
type Fact struct {
	Kind       Kind
	Target     string
	Attributes map[string]string
}

// Exemption is time-boxed. Expiry is data, not a calendar reminder: an
// expired exemption stops suppressing on the next evaluation.
type Exemption struct {
	RuleID    string
	Target    string
	Owner     string
	Reason    string
	ExpiresAt time.Time
}

type Violation struct {
	RuleID   string
	Target   string
	Level    Level
	Severity Severity
	Message  string
	Exempted bool
	Owner    string
}

// Evaluate runs every active rule against every matching fact and returns
// violations sorted by target and rule. Retired rules are skipped; they stay
// in the source as history, not as checks.
func Evaluate(rules []Rule, facts []Fact, exemptions []Exemption, at time.Time) []Violation {
	byKey := make(map[string]Exemption, len(exemptions))
	for _, e := range exemptions {
		byKey[e.RuleID+"|"+e.Target] = e
	}
	var out []Violation
	for _, rule := range rules {
		if rule.Status == Retired {
			continue
		}
		for _, fact := range facts {
			if fact.Kind != rule.Kind {
				continue
			}
			bad, msg := check(rule, fact)
			if !bad {
				continue
			}
			v := Violation{
				RuleID:   rule.ID,
				Target:   fact.Target,
				Level:    rule.Level,
				Severity: rule.Severity,
				Message:  msg,
			}
			if e, ok := byKey[rule.ID+"|"+fact.Target]; ok {
				switch {
				case e.Owner == "" || e.Reason == "":
					v.Message += " (exemption invalid: owner and reason are required)"
				case !at.Before(e.ExpiresAt):
					v.Message += " (exemption expired at " + e.ExpiresAt.Format(time.RFC3339) + ")"
				default:
					v.Exempted = true
					v.Owner = e.Owner
					v.Message += " (exempted by " + e.Owner + " until " + e.ExpiresAt.Format(time.RFC3339) + ")"
				}
			}
			out = append(out, v)
		}
	}
	sort.Slice(out, func(i, j int) bool {
		if out[i].Target != out[j].Target {
			return out[i].Target < out[j].Target
		}
		return out[i].RuleID < out[j].RuleID
	})
	return out
}

func check(rule Rule, fact Fact) (bool, string) {
	switch rule.Kind {
	case ForbiddenDependency:
		if rule.Pattern == "" {
			return false, ""
		}
		if strings.HasPrefix(fact.Target, rule.Pattern) {
			return true, fmt.Sprintf("dependency on forbidden prefix %q", rule.Pattern)
		}
	case RequiredAttribute:
		if rule.Pattern == "" {
			return false, ""
		}
		if strings.TrimSpace(fact.Attributes[rule.Pattern]) == "" {
			return true, fmt.Sprintf("missing required attribute %q", rule.Pattern)
		}
	case ConfigDrift:
		if actual := fact.Attributes["actual"]; actual != rule.Pattern {
			return true, fmt.Sprintf("config drift: want %q, got %q", rule.Pattern, actual)
		}
	}
	return false, ""
}

type Report struct {
	Violations []Violation
	Blocking   int
	Warnings   int
	Exempted   int
}

// BuildReport separates blocking failures from warnings and exemptions. A
// report that only counts violations hides how much of the debt is already
// known and time-boxed.
func BuildReport(vs []Violation) Report {
	r := Report{Violations: vs}
	for _, v := range vs {
		if v.Exempted {
			r.Exempted++
			continue
		}
		if v.Severity == Blocking {
			r.Blocking++
		} else {
			r.Warnings++
		}
	}
	return r
}

func (r Report) Passed() bool { return r.Blocking == 0 }