《后端架构设计·架构基础与边界》4.1 模块化单体：先拿到边界再谈拆分

// file: internal/modules/modules.go
// tier: L1
// verify: go test ./internal/modules/ -run TestValidate -v
package modules

import (
	"fmt"
	"go/parser"
	"go/token"
	"io/fs"
	"os"
	"path/filepath"
	"sort"
	"strconv"
	"strings"
)

// Module 是模块边界声明。PublicPackages 允许跨模块导入；
// InternalPackages 只允许本模块导入；Owner 标明值班与评审归属。
type Module struct {
	Name             string
	Owner            string
	PublicPackages   []string
	InternalPackages []string
	DependsOn        []string
}

type Registry struct {
	Modules []Module
}

type Checker struct {
	ModulePath string
	Exempt     []string // 不归属任何模块的包前缀，例如检查器自身
}

func (c Checker) Validate(root string, reg Registry) ([]string, error) {
	var out []string
	byName := make(map[string]Module)
	owner := make(map[string]string)
	private := make(map[string]string)

	for _, m := range reg.Modules {
		if _, exists := byName[m.Name]; exists {
			out = append(out, "duplicate module "+m.Name)
			continue
		}
		byName[m.Name] = m
		for _, pkg := range m.PublicPackages {
			c.claim(&out, owner, m.Name, pkg)
		}
		for _, pkg := range m.InternalPackages {
			c.claim(&out, owner, m.Name, pkg)
			private[pkg] = m.Name
		}
	}
	for _, m := range reg.Modules {
		for _, dep := range m.DependsOn {
			if _, ok := byName[dep]; !ok {
				out = append(out, fmt.Sprintf("module %q: unknown dependency %q", m.Name, dep))
			}
		}
	}
	out = append(out, cycles(reg)...)

	fset := token.NewFileSet()
	err := filepath.WalkDir(root, func(path string, entry fs.DirEntry, walkErr error) error {
		if walkErr != nil {
			return walkErr
		}
		if entry.IsDir() {
			name := entry.Name()
			if path != root && (name == "testdata" || name == "vendor" || strings.HasPrefix(name, ".")) {
				return fs.SkipDir
			}
			return nil
		}
		if !strings.HasSuffix(path, ".go") || strings.HasSuffix(path, "_test.go") {
			return nil
		}
		file, err := parser.ParseFile(fset, path, nil, parser.ImportsOnly)
		if err != nil {
			return err
		}
		src := lookup(owner, c.pkgPath(root, filepath.Dir(path)))
		if src == "" {
			return nil
		}
		for _, spec := range file.Imports {
			imported, err := strconv.Unquote(spec.Path.Value)
			if err != nil || !has(imported, c.ModulePath) {
				continue
			}
			dst := lookup(owner, imported)
			if dst == "" || dst == src {
				continue
			}
			for prefix, prefixOwner := range private {
				if prefixOwner != src && has(imported, prefix) {
					out = append(out, fmt.Sprintf("%s: module %q imports internal %q of %q",
						rel(root, path), src, imported, prefixOwner))
					dst = ""
					break
				}
			}
			if dst != "" && !hasDep(byName[src], dst) {
				out = append(out, fmt.Sprintf("%s: module %q imports %q without declaring %q",
					rel(root, path), src, imported, dst))
			}
		}
		return nil
	})
	if err != nil {
		return nil, err
	}
	out = append(out, c.coverage(root, owner)...)
	sort.Strings(out)
	return out, nil
}

func (c Checker) claim(out *[]string, owner map[string]string, module, pkg string) {
	if !has(pkg, c.ModulePath) {
		*out = append(*out, fmt.Sprintf("module %q claims package %q outside %q", module, pkg, c.ModulePath))
		return
	}
	if previous, ok := owner[pkg]; ok && previous != module {
		*out = append(*out, fmt.Sprintf("package %q claimed by %q and %q", pkg, previous, module))
		return
	}
	owner[pkg] = module
}

// coverage 要求 internal/ 下每个含非测试 Go 文件的包恰好被声明一次。
func (c Checker) coverage(root string, owner map[string]string) []string {
	var out []string
	_ = filepath.WalkDir(filepath.Join(root, "internal"), func(path string, entry fs.DirEntry, err error) error {
		if err != nil || !entry.IsDir() {
			return nil
		}
		pkg := c.pkgPath(root, path)
		for _, exempt := range c.Exempt {
			if has(pkg, exempt) {
				return nil
			}
		}
		entries, err := os.ReadDir(path)
		if err != nil {
			return nil
		}
		for _, item := range entries {
			name := item.Name()
			if !item.IsDir() && strings.HasSuffix(name, ".go") && !strings.HasSuffix(name, "_test.go") {
				if _, ok := owner[pkg]; !ok {
					out = append(out, fmt.Sprintf("internal package %q is unowned", pkg))
				}
				return nil
			}
		}
		return nil
	})
	return out
}

func (c Checker) pkgPath(root, dir string) string {
	value, err := filepath.Rel(root, dir)
	if err != nil || value == "." {
		return c.ModulePath
	}
	return c.ModulePath + "/" + filepath.ToSlash(value)
}

func lookup(owner map[string]string, pkg string) string {
	if module, ok := owner[pkg]; ok {
		return module
	}
	best, bestLen := "", -1
	for prefix, module := range owner {
		if has(pkg, prefix) && len(prefix) > bestLen {
			best, bestLen = module, len(prefix)
		}
	}
	return best
}

// cycles 用 Kahn 拓扑排序检测模块级依赖环，剩余节点即环或其下游。
func cycles(reg Registry) []string {
	indegree := make(map[string]int)
	edges := make(map[string][]string)
	for _, m := range reg.Modules {
		indegree[m.Name] = 0
	}
	for _, m := range reg.Modules {
		for _, dep := range m.DependsOn {
			if _, ok := indegree[dep]; !ok {
				continue
			}
			edges[m.Name] = append(edges[m.Name], dep)
			indegree[dep]++
		}
	}
	var queue []string
	for name, degree := range indegree {
		if degree == 0 {
			queue = append(queue, name)
		}
	}
	seen := 0
	for len(queue) > 0 {
		name := queue[0]
		queue = queue[1:]
		seen++
		for _, next := range edges[name] {
			indegree[next]--
			if indegree[next] == 0 {
				queue = append(queue, next)
			}
		}
	}
	if seen == len(indegree) {
		return nil
	}
	var stuck []string
	for name, degree := range indegree {
		if degree > 0 {
			stuck = append(stuck, name)
		}
	}
	sort.Strings(stuck)
	return []string{"dependency cycle among: " + strings.Join(stuck, ", ")}
}

func hasDep(m Module, target string) bool {
	for _, dep := range m.DependsOn {
		if dep == target {
			return true
		}
	}
	return false
}

func has(pkg, prefix string) bool {
	return pkg == prefix || strings.HasPrefix(pkg, prefix+"/")
}

func rel(root, path string) string {
	value, err := filepath.Rel(root, path)
	if err != nil {
		return path
	}
	return filepath.ToSlash(value)
}

// file: internal/modules/modules_test.go
// tier: L1
// verify: go test ./internal/modules/ -run TestValidate -v
package modules

import (
	"strings"
	"testing"
)

func TestValidateRejectsDependencyCycle(t *testing.T) {
	reg := Registry{Modules: []Module{
		{Name: "a", InternalPackages: []string{"archlab/internal/a"}, DependsOn: []string{"b"}},
		{Name: "b", InternalPackages: []string{"archlab/internal/b"}, DependsOn: []string{"a"}},
	}}
	problems, err := Checker{ModulePath: "archlab"}.Validate(t.TempDir(), reg)
	if err != nil {
		t.Fatal(err)
	}
	if !strings.Contains(strings.Join(problems, "\n"), "dependency cycle among: a, b") {
		t.Fatalf("problems = %v", problems)
	}
}

$ go test ./internal/modules/ -run TestValidate -v -count=1
=== RUN   TestValidateRejectsDependencyCycle
--- PASS: TestValidateRejectsDependencyCycle (0.00s)
PASS
ok  	archlab/internal/modules	0.551s