ECC Go 模式实践指南：函数式选项、小接口与构造函数注入

本文以 .kiro/steering/golang-patterns.md 为核心骨架，阐述 ECC 这一 Agent 执行性能优化系统中如何把 Go 语言的惯用工程模式固化为一套可被 Claude Code / Codex / Opencode / Cursor 等 Agent 自动触发的"护栏"：从函数式选项（Functional Options）、小接口（Small Interfaces）到构造函数注入（Dependency Injection），并延伸到并发、错误处理、包组织与测试实践。读完本文，你将掌握 ECC 体系中 Go 代码编写、评审与重构所遵循的模式基线，以及它们在各层级文件中的落点与相互引用关系。

定位：一篇"模式护栏"文件如何驱动 Go 开发

在 ECC 仓库中，.kiro/steering/ 目录存放的是面向 Agent 的"steering（引导）上下文"文件。golang-patterns.md 通过文件头部的元信息声明了自己的作用边界：

inclusion: fileMatch
fileMatchPattern: "*.go"
description: Go-specific patterns including functional options, small interfaces, and dependency injection

其中 fileMatchPattern: "*.go" 表示：当任务涉及 Go 源文件时，这段 Go 专属模式指南会随上下文注入，指导 Agent 按仓库认可的惯用范式编写与审查代码。文件正文的第一句也明确其层次关系——"This file extends the common patterns with Go specific content."，即它是对通用模式（仓库内对应 rules/common/patterns.md，涵盖仓库模式 Repository Pattern、API 响应格式、骨架项目策略等）的 Go 语言细化。

这份模式内容在仓库中以多层级镜像存在，形成"引导 → 规则 → 技能"的完整链路，可以从如下路径查阅：

层级	路径	说明
Steering 引导层	.kiro/steering/golang-patterns.md	精简核心：三大模式的速记版，按 *.go 自动匹配注入
规则层	rules/golang/patterns.md、.cursor/rules/golang-patterns.md	与 steering 内容对应，面向 **/*.go、**/go.mod、**/go.sum
技能层（深度版）	.kiro/skills/golang-patterns/SKILL.md	三大模式 + 并发、错误处理、包组织、测试的完整扩展
测试技能	.kiro/skills/golang-testing/SKILL.md	表驱动测试、test helper、竞态检测、覆盖率、基准、mock、集成测试

steering 文件末尾有一行 "See skill: golang-patterns"，指向技能层的完整版——这正是 ECC 的典型组织方式：浅层文件负责快速注入，深层技能负责按需深读。

函数式选项（Functional Options）：可演进的构造函数配置

steering 文件中给出的核心示例以配置一个 Server 为场景：将"可选项"建模为 func(*Server) 类型，通过可变参数在构造函数中统一应用。

type Option func(*Server)

func WithPort(port int) Option {
    return func(s *Server) { s.port = port }
}

func NewServer(opts ...Option) *Server {
    s := &Server{port: 8080}
    for _, opt := range opts {
        opt(s)
    }
    return s
}

这是 Go 社区经典的"选项对象"替代方案。相比传统的"为每个配置新增参数"或"传入大型配置结构体"，函数式选项在 .kiro/skills/golang-patterns/SKILL.md 中被总结了三点核心收益：

• 向后兼容的 API 演进：新增配置项时只需增加一个 WithXxx 函数与结构体字段，已调用 NewServer() 的存量代码无需任何改动；
• 带默认值的可选参数：NewServer 在循环应用选项之前先初始化默认值（如上例 port: 8080），未显式配置时使用默认端口；
• 自文档化的配置：调用侧写作 NewServer(WithPort(9090), WithTimeout(5*time.Second))，每个选项语义即方法名，无需记忆结构体字段顺序。

从实现机制看，模式的关键在于两点：其一，Option 是对 *Server 的闭包封装，只有构造函数有权在 &Server{...} 初始化后通过 opt(s) 修改内部状态，天然保护了字段不被外部随意篡改；其二，可变参数 opts ...Option 允许零个或多个选项传入，配合"先默认、后覆盖"的顺序，保证了无论调用方传多少选项，最终状态都可预期。

小接口（Small Interfaces）：在使用处定义，而非实现处

steering 文件中关于接口的指引只有一句话，却是一条高度凝练的 Go 设计准则：

Define interfaces where they are used, not where they are implemented.

即在消费方定义接口，而不是在生产方定义。典型反例是：数据访问实现方定义一个包罗万象的 UserRepository 巨型接口，把所有 CRUD 方法写满；而正确做法是让每个使用方只声明它真正需要的最小方法集，接口的"大小"由使用场景决定。

技能层进一步补充了配套原则与示例：

• 原则：Accept interfaces, return structs（入参接接口、返回值给具体类型）；
• 接口应当小而聚焦，例如仅包含消费方需要的单个方法：

// Good: Small, focused interface defined at point of use
type UserStore interface {
    GetUser(id string) (*User, error)
}

func ProcessUser(store UserStore, id string) error {
    user, err := store.GetUser(id)
    // ...
}

技能文件同时列出了小接口带来的三项收益：更易测试与打桩（mock 只需实现一两个方法）、松耦合（消费方不依赖实现包的任何多余行为）、依赖关系清晰（一眼看出该函数究竟需要什么能力）。这一模式也是后续"基于接口的 Mocking"和"构造函数注入"能够顺畅落地的前提——没有小接口，依赖注入就无从谈起。

依赖注入（Dependency Injection）：构造函数显式收参

steering 文件给出的依赖注入范式非常直白——用构造函数注入，而不是全局变量、包级单例或反射容器：

func NewUserService(repo UserRepository, logger Logger) *UserService {
    return &UserService{repo: repo, logger: logger}
}

技能层 .kiro/skills/golang-patterns/SKILL.md 将这一写法展开为四条明确规矩：

• 构造函数以 New* 前缀命名，作为创建实例的唯一入口；
• 依赖以显式参数传入，repo、logger 等协作对象一目了然，不依赖隐式全局状态；
• 返回具体类型（*UserService），把构造结果作为可被持有的实体，而不是面向接口返回；
• 在构造函数内校验依赖，若传入的 repo == nil 等非法状态，应在 NewUserService 中尽早返回错误或 panic，避免半初始化对象流入业务代码。

该模式与上一节的"小接口"互为表里：构造函数参数的类型（如 UserRepository）往往正是定义在消费包内的小接口。这一点在测试环节收益尤为显著——golang-testing 技能 中的接口 Mock 示例正是 NewUserService(mock) 传入一个手写假实现来完成对 UserService 的隔离测试。

由三大模式延伸：并发与错误处理的惯例

steering 文件本身只覆盖三大模式，但它的参考目标 .kiro/skills/golang-patterns/SKILL.md 将"并发模式"和"错误处理"一并纳入 Go 惯用实践版图。对于 Agent 在编写并发服务时的代码生成与评审，这些是紧随三大模式之后的高频判定点。

Worker Pool 与 Context 传播

技能文件给出了 worker pool 的骨架——用 chan 分发任务、sync.WaitGroup 汇合、完成后 close(results) 收敛结果通道：

func workerPool(jobs <-chan Job, results chan<- Result, workers int) {
    var wg sync.WaitGroup
    for i := 0; i < workers; i++ {
        wg.Add(1)
        go func() {
            defer wg.Done()
            for job := range jobs {
                results <- processJob(job)
            }
        }()
    }
    wg.Wait()
    close(results)
}

并发函数的硬性约定是把 context.Context 作为第一个参数，并在耗时逻辑前检查取消信号：

func FetchUser(ctx context.Context, id string) (*User, error) {
    // Check context cancellation
    select {
    case <-ctx.Done():
        return nil, ctx.Err()
    default:
    }
    // ... fetch logic
}

错误处理三段式：包装、自定义类型与哨兵错误

• 错误包装：用 fmt.Errorf("failed to fetch user %s: %w", id, err) 携带 %w 动词保留原始错误的 Unwrap 链，调用方才能用 errors.Is/errors.As 逐层判定；
• 自定义错误类型：如 ValidationError{Field, Msg}，通过实现 Error() string 让错误携带结构化字段，供上层以 errors.As 提取；
• 哨兵错误（Sentinel Errors）：包级导出 var ErrNotFound = errors.New("not found") 等预定义错误值，配合 errors.Is 判定，替代在调用链深处依赖字符串匹配的脆弱写法。

包组织与命名约定

技能文件同时给出了推荐的目录骨架与命名规范，Agent 在脚手架生成、重构评审时会以此核对：

project/
├── cmd/              # Main applications
│   └── server/
│       └── main.go
├── internal/         # Private application code
│   ├── domain/       # Business logic
│   ├── handler/      # HTTP handlers
│   └── repository/   # Data access
└── pkg/              # Public libraries

配套规则：包名小写单词；避免命名重复（user.User 而非 user.UserModel）；私有代码放 internal/；main 包保持最小化。

测试实践：ECC 的 Go 质量门槛

ECC 仓库中的 Go 测试专属技能 .kiro/skills/golang-testing/SKILL.md 与 golang-patterns 技能互为补充，把"模式可验证"落到了可执行层面。以下是其推荐的几类高频做法。

表驱动测试（Table-Driven Tests）

以 []struct{...} 描述输入/期望，用 t.Run(tt.name, ...) 生成独立子测试，是 go test 生态中最具 Go 特色的测试形态：

func TestValidateEmail(t *testing.T) {
    tests := []struct {
        name    string
        email   string
        wantErr bool
    }{
        {"valid email", "[e-mail]", false},
        {"missing @", "userexample.com", true},
        {"empty string", "", true},
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            err := ValidateEmail(tt.email)
            if (err != nil) != tt.wantErr {
                t.Errorf("ValidateEmail(%q) error = %v, wantErr %v",
                    tt.email, err, tt.wantErr)
            }
        })
    }
}

其收益在于：新增用例即新增一行结构体条目，测试即文档；独立子测试间可用 t.Parallel() 并行；失败信息自带用例名，便于定位。

测试辅助函数与资源清理

辅助函数首行调用 t.Helper()，使报错时定位到真正的调用行而非辅助函数内部；资源型辅助函数用 t.Cleanup 注册清理，保证测试结束后释放：

func testDB(t *testing.T) *sql.DB {
    t.Helper()
    db, err := sql.Open("sqlite3", ":memory:")
    if err != nil {
        t.Fatalf("failed to open test db: %v", err)
    }
    t.Cleanup(func() { db.Close() })
    return db
}

竞态检测、覆盖率与基准测试

技能文件规定"始终以 -race 运行测试"以暴露数据竞争；在 CI 中建议 go test -race -timeout 5m ./...。覆盖率可用 go test -coverprofile=coverage.out ./... 生成报告并以 go tool cover -html=coverage.out 可视化。基准测试使用标准 b *testing.B 形态配合 go test -bench=. -benchmem，两次运行结果可交由 benchstat 对比回归。

基于小接口的 Mock 与集成测试

由于"小接口 + 构造函数注入"已经是模式基线，测试中手写一个满足消费方最小方法集的假实现成本极低——这正是上一节接口模式在测试侧的回报。集成测试则通过 //go:build integration 构建标签隔离，使用 go test -tags=integration ./... 显式运行，必要时借助 testcontainers 拉起真实中间件。

这些模式在 ECC 中的触发与应用场景

golang-patterns.md 属于 *.go 匹配的 steering 上下文，因此当 Agent 面临以下任务时，上述模式会被优先激活，作为代码生成与评审的默认判据：

• 设计 Go API 与包：构造函数注入 + 小接口决定了对外 API 的形态与包间依赖方向；
• 实现并发系统：worker pool、context 首参传播决定并发正确性；
• 组织 Go 项目结构：cmd/internal/pkg 骨架决定代码落位；
• 编写与重构 Go 代码库：以函数式选项替换配置结构体、拆分巨型接口、清理包级可变全局状态等，都是重构类评审的高频动作（仓库 .kiro/agents/go-reviewer.md 即承担此类 Go 评审角色）。

需要说明的是，.kiro/steering/ 中的 Go 模式文件定位为快速注入的精简引导，其完整内容扩展在 .kiro/skills/golang-patterns/SKILL.md 中，二者配合 rules/golang/ 下的同主题规则，共同构成 ECC 对 Go 工程实践的三层约束体系。理解这一文件组织，既有助于在使用 ECC 编写 Go 代码时获得一致的模式输出，也有助于在二次定制时知道该在哪个层级补丁——这正是本指南的最终用途。

小结

围绕 .kiro/steering/golang-patterns.md 这一引导文件，ECC 为 Go 工程实践锚定了三条主基线：函数式选项保证构造函数 API 的可演进性与默认值语义；小接口要求接口在使用处定义、保持最小；构造函数依赖注入让协作对象显式可见、可替换、可在构造期校验。再向外延伸，并发（worker pool、context 首参）、错误处理（%w 包装、哨兵错误）、包组织（cmd/internal/pkg）与测试（表驱动、-race、覆盖率）共同构成了一个自洽、可评审、可自动化的 Go 编码契约。对于希望让 AI Agent 稳定产出高质量 Go 代码的团队而言，这套"steering 精简引导 + 技能深度扩展 + 规则逐文件匹配"的层级化组织方式，本身就是值得借鉴的落地样板。