《游戏服务端架构·平台化与架构治理》8.2 技术债与架构适应度函数

月利息（示例值） = 每次改动的额外成本 × 每月改动次数

package fitnessfunction

import (
	"errors"
	"fmt"
	"sort"
	"time"
)

var ErrDirection = errors.New("fitnessfunction: unknown direction")

type Direction string

const (
	AtMost  Direction = "max" // value must not exceed the threshold
	AtLeast Direction = "min" // value must not fall below the threshold
)

type Severity string

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

// Metric is one fitness function observation. The threshold lives beside the
// metric so a change to the budget is reviewable in the same diff.
type Metric struct {
	Name      string
	Value     float64
	Threshold float64
	Direction Direction
	Severity  Severity
}

// Exception is a time-boxed permission to miss a threshold. An exception
// without an owner or a reason is invalid, and an expired one stops working
// without anyone having to remember to remove it.
type Exception struct {
	Metric    string
	Owner     string
	Reason    string
	ExpiresAt time.Time
}

type Finding struct {
	Metric    string
	Value     float64
	Threshold float64
	Severity  Severity
	Violated  bool
	Exempted  bool
	Note      string
}

// Evaluate checks every metric against its threshold. Metrics that pass and
// metrics that fail both return a Finding so a report can show the margin,
// not only the failures.
func Evaluate(metrics []Metric, exceptions []Exception, at time.Time) ([]Finding, error) {
	ex := make(map[string]Exception, len(exceptions))
	for _, e := range exceptions {
		ex[e.Metric] = e
	}
	out := make([]Finding, 0, len(metrics))
	for _, m := range metrics {
		if m.Direction != AtMost && m.Direction != AtLeast {
			return nil, fmt.Errorf("%w: %q", ErrDirection, m.Direction)
		}
		f := Finding{
			Metric:    m.Name,
			Value:     m.Value,
			Threshold: m.Threshold,
			Severity:  m.Severity,
		}
		violated := (m.Direction == AtMost && m.Value > m.Threshold) ||
			(m.Direction == AtLeast && m.Value < m.Threshold)
		f.Violated = violated
		if !violated {
			out = append(out, f)
			continue
		}
		if e, ok := ex[m.Name]; ok {
			switch {
			case e.Owner == "" || e.Reason == "":
				f.Note = "exemption invalid: owner and reason are required"
			case !at.Before(e.ExpiresAt):
				f.Note = "exemption expired at " + e.ExpiresAt.Format(time.RFC3339)
			default:
				f.Exempted = true
				f.Note = "exempted by " + e.Owner + " until " + e.ExpiresAt.Format(time.RFC3339)
			}
		}
		out = append(out, f)
	}
	sort.Slice(out, func(i, j int) bool { return out[i].Metric < out[j].Metric })
	return out, nil
}

// Debt is one entry in the technology-debt ledger. Interest is the extra cost
// a change pays because the debt exists; frequency turns it into a monthly
// rate that can be compared with other debts.
type Debt struct {
	ID                string
	Description       string
	Impact            int // 1..5, player or revenue exposure
	InterestPerChange float64
	ChangesPerMonth   float64
	Owner             string
	RepayBy           time.Time
}

func (d Debt) MonthlyInterest() float64 {
	return d.InterestPerChange * d.ChangesPerMonth
}

func (d Debt) Overdue(at time.Time) bool {
	return !d.RepayBy.IsZero() && at.After(d.RepayBy)
}

// RankDebts puts overdue debts first, then orders by monthly interest. A debt
// with a high one-off cost but a low change frequency is not urgent; a small
// tax paid on every change is.
func RankDebts(debts []Debt, at time.Time) []Debt {
	out := append([]Debt(nil), debts...)
	sort.SliceStable(out, func(i, j int) bool {
		oi, oj := out[i].Overdue(at), out[j].Overdue(at)
		if oi != oj {
			return oi
		}
		ii, ij := out[i].MonthlyInterest(), out[j].MonthlyInterest()
		if ii != ij {
			return ii > ij
		}
		return out[i].ID < out[j].ID
	})
	return out
}

// Edge is one package-level dependency. Direction matters: From depends on To.
type Edge struct {
	From string
	To   string
}

type Coupling struct {
	FanIn  int
	FanOut int
}

func MeasureCoupling(edges []Edge, module string) Coupling {
	var c Coupling
	for _, e := range edges {
		if e.From == e.To {
			continue
		}
		if e.To == module {
			c.FanIn++
		}
		if e.From == module {
			c.FanOut++
		}
	}
	return c
}

// Instability is efferent / (afferent + efferent). A module with many
// dependents and few dependencies is stable and should change slowly.
func (c Coupling) Instability() float64 {
	total := c.FanIn + c.FanOut
	if total == 0 {
		return 0
	}
	return float64(c.FanOut) / float64(total)
}

// Layer orders packages from the inside out. Imports may point inward or stay
// on the same layer; imports pointing outward are violations.
type Layer int

const (
	Domain Layer = iota
	Application
	Adapter
)

func (l Layer) String() string {
	switch l {
	case Domain:
		return "domain"
	case Application:
		return "application"
	case Adapter:
		return "adapter"
	default:
		return "unknown"
	}
}

type Import struct {
	FromPackage string
	ToPackage   string
	FromLayer   Layer
	ToLayer     Layer
}

type Violation struct {
	FromPackage string
	ToPackage   string
	FromLayer   Layer
	ToLayer     Layer
}

func CheckDirection(imports []Import) []Violation {
	var out []Violation
	for _, im := range imports {
		if im.ToLayer > im.FromLayer {
			out = append(out, Violation{
				FromPackage: im.FromPackage,
				ToPackage:   im.ToPackage,
				FromLayer:   im.FromLayer,
				ToLayer:     im.ToLayer,
			})
		}
	}
	sort.Slice(out, func(i, j int) bool {
		if out[i].FromPackage != out[j].FromPackage {
			return out[i].FromPackage < out[j].FromPackage
		}
		return out[i].ToPackage < out[j].ToPackage
	})
	return out
}