《后端架构设计·架构基础与边界》1.3 架构风格谱系与 arch-lab 选型矩阵

ADR-001：arch-lab 卷一采用模块化单体
状态：已接受
背景：两人团队，日订单量不到万级；订单、库存、支付共享同一套状态机
      与事务边界；没有独立运维多个服务的预算。
决策：单进程部署，按 internal/order、catalog、payment、inventory、
      ports、adapters、platform 划分模块；模块间只经接口与领域类型通信；
      依赖方向由 deplint 强制检查。
备选 A：微服务——按订单、库存、支付拆三个服务。
      否决理由：跨服务下单需要分布式事务或补偿；当前团队无法承担服务发现、
      链路追踪、独立发布与值班成本；一致性缺陷会直接变成超卖。
备选 B：事件驱动优先——下单只写事件，库存与支付各自消费。
      否决理由：卷一需要同步返回订单状态；事件溯源、幂等消费与对账尚未建立，
      调试成本高于收益。
后果：正面——单库事务保证状态与库存同成败，重构可先改模块边界；
      负面——无法按模块独立扩缩容，单进程故障影响全部模块；
      重新评估触发条件——单模块团队超过 5 人、某模块需要独立扩缩容，
      或发布频率冲突开始排队。

cmd/orderd/main.go
internal/order/           聚合、状态机、领域事件
internal/catalog/         SKU 与价格
internal/payment/         支付端口与假实现
internal/inventory/       库存预留与释放
internal/ports/           仓储/支付/消息接口
internal/adapters/memory/
internal/adapters/postgres/
internal/platform/config/
internal/platform/httpserver/
internal/platform/idempotency/

// file: tools/deplint/lint.go
// tier: L1
// verify: go test ./tools/deplint/
package main

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

type Rule struct {
	From  string
	Allow []string
}

type Violation struct {
	File   string
	Import string
	Rule   string
}

// Check 扫描非测试 .go 文件，只检查模块内导入。
func Check(root, module string, rules []Rule) ([]Violation, error) {
	modulePrefix := module + "/"
	fset := token.NewFileSet()
	var violations []Violation

	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
		}
		pkgDir, err := filepath.Rel(root, filepath.Dir(path))
		if err != nil {
			return err
		}
		pkg := module
		if pkgDir != "." {
			pkg = module + "/" + filepath.ToSlash(pkgDir)
		}
		rule, matched := matchRule(pkg, rules)
		if !matched {
			return nil
		}
		fileName, err := filepath.Rel(root, path)
		if err != nil {
			return err
		}
		for _, spec := range file.Imports {
			importPath, err := strconv.Unquote(spec.Path.Value)
			if err != nil {
				return err
			}
			if importPath != module && !strings.HasPrefix(importPath, modulePrefix) {
				continue
			}
			if !allowedImport(importPath, rule.Allow) {
				violations = append(violations, Violation{
					File: filepath.ToSlash(fileName), Import: importPath, Rule: rule.From,
				})
			}
		}
		return nil
	})
	return violations, err
}

// matchRule 取最长前缀，让 internal/adapters 覆盖更宽的 internal 规则。
func matchRule(pkg string, rules []Rule) (Rule, bool) {
	var best Rule
	found := false
	for _, rule := range rules {
		if pkg != rule.From && !strings.HasPrefix(pkg, rule.From+"/") {
			continue
		}
		if !found || len(rule.From) > len(best.From) {
			best, found = rule, true
		}
	}
	return best, found
}

func allowedImport(importPath string, allow []string) bool {
	for _, prefix := range allow {
		if importPath == prefix || strings.HasPrefix(importPath, prefix+"/") {
			return true
		}
	}
	return false
}

// file: tools/deplint/main.go
// tier: L1
// verify: go run ./tools/deplint -root . -module archlab
package main

import (
	"flag"
	"fmt"
	"os"
)

// rules 是 arch-lab 的依赖方向契约：内层不知道外层，平台不知道领域。
var rules = []Rule{
	{From: "archlab/internal/order", Allow: nil},
	{From: "archlab/internal/catalog", Allow: nil},
	{From: "archlab/internal/ports", Allow: []string{"archlab/internal/order", "archlab/internal/catalog"}},
	{From: "archlab/internal/adapters", Allow: []string{
		"archlab/internal/order", "archlab/internal/catalog",
		"archlab/internal/ports", "archlab/internal/platform",
	}},
	{From: "archlab/internal/platform", Allow: nil},
	{From: "archlab/cmd", Allow: []string{"archlab/internal"}},
}

func main() {
	root := flag.String("root", ".", "module root")
	module := flag.String("module", "archlab", "module path from go.mod")
	flag.Parse()

	violations, err := Check(*root, *module, rules)
	if err != nil {
		fmt.Fprintln(os.Stderr, "deplint:", err)
		os.Exit(2)
	}
	for _, violation := range violations {
		fmt.Printf("%s: imports %s (rule %s)\n", violation.File, violation.Import, violation.Rule)
	}
	if len(violations) > 0 {
		fmt.Fprintf(os.Stderr, "deplint: %d violation(s)\n", len(violations))
		os.Exit(1)
	}
	fmt.Println("deplint: ok")
}

// file: tools/deplint/lint_test.go
// tier: L1
// verify: go test ./tools/deplint/ -run TestCheckFlagsLayerViolations -v
package main

import (
	"os"
	"path/filepath"
	"testing"
)

func writeFile(t *testing.T, root, name, body string) {
	t.Helper()
	path := filepath.Join(root, filepath.FromSlash(name))
	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
		t.Fatal(err)
	}
	if err := os.WriteFile(path, []byte(body), 0o644); err != nil {
		t.Fatal(err)
	}
}

func TestCheckFlagsLayerViolations(t *testing.T) {
	root := t.TempDir()
	writeFile(t, root, "internal/order/order.go", `package order

import _ "archlab/internal/adapters/memory"
`)
	writeFile(t, root, "internal/platform/config/config.go", `package config

import _ "archlab/internal/order"
`)
	writeFile(t, root, "internal/adapters/memory/memory.go", `package memory

import (
	_ "archlab/internal/order"
	_ "archlab/internal/ports"
)
`)
	writeFile(t, root, "cmd/orderd/main.go", `package main

import _ "archlab/internal/adapters/memory"

func main() {}
`)
	// 测试文件不在契约范围内：允许用假实现替换端口。
	writeFile(t, root, "internal/order/order_test.go", `package order

import _ "archlab/internal/adapters/memory"
`)

	violations, err := Check(root, "archlab", rules)
	if err != nil {
		t.Fatal(err)
	}
	if len(violations) != 2 {
		t.Fatalf("violations = %d, want 2: %+v", len(violations), violations)
	}

	got := map[string]string{}
	for _, violation := range violations {
		got[violation.File] = violation.Import
	}
	if got["internal/order/order.go"] != "archlab/internal/adapters/memory" {
		t.Errorf("missing domain -> adapter violation: %+v", got)
	}
	if got["internal/platform/config/config.go"] != "archlab/internal/order" {
		t.Errorf("missing platform -> domain violation: %+v", got)
	}
}

$ go test ./tools/deplint/ -count=1 -v
=== RUN   TestCheckFlagsLayerViolations
--- PASS: TestCheckFlagsLayerViolations (0.05s)
PASS
ok  	archlab/tools/deplint	0.343s

$ go run ./tools/deplint -root . -module archlab
deplint: ok

$ go run ./tools/deplint -root ./badfixture -module archlab
internal/order/order.go: imports archlab/internal/adapters (rule archlab/internal/order)
internal/platform/config.go: imports archlab/internal/order (rule archlab/internal/platform)
deplint: 2 violation(s)