戈兰

工程开发 社区

技能解读

当前原文的自动摘译,尚未人工审校。

错误处理

检查每个错误。 if err != nil 模式是有意为之的——Go 使错误处理变得明确。切勿使用_丢弃错误。使用fmt.Errorf("doing X: %w", err)用上下文包装错误,以便调用链产生可读的消息。使用标记错误 (var ErrNotFound = errors.New("not found")) 来处理调用者使用errors.Is() 检查的预期条件。对携带结构化数据的错误使用自定义错误类型。

项目结构

遵循标准布局:cmd/用于应用程序入口点,internal/用于私有包,pkg/用于公共库(如果有)。保持main.go最小化——它连接依赖项并启动服务器。每个目录一个包。包名称应该简短、小写且具有描述性。避免使用util或common包裹——它们会成为垃圾场。

并发性

不要通过共享内存来通信——通过通信来共享内存。使用通道在 goroutine 之间进行同步。仅使用 sync.Mutex 来保护通道会被过度杀伤的简单共享状态。始终确保 goroutine 可以停止。通过context.Context并检查ctx.Done()。泄漏 goroutine 是一种随着时间的推移而增长的内存泄漏。当您需要等待已知数量的 goroutine 完成时,请使用sync.WaitGroup。当任何 goroutine 失败应该取消其余的时,请使用errgroup.Group。

接口

在使用接口的地方定义接口,而不是在实现接口的地方定义接口。保持接口较小——一两种方法是理想的。 io.Reader 和io.Writer 接口是黄金标准。接受接口,返回结构。这使得代码可测试——调用者可以注入满足接口的模拟。

测试

对具有多个输入/输出组合的函数使用表驱动测试。清楚地命名测试用例。使用t.Run()进行子测试,以便失败可以确定哪个案例损坏了。在测试辅助函数中使用testing.T.Helper(),以便失败消息指向调用测试,而不是辅助函数。

流狐档案 运行与权限由流狐静态检查推断,不代表作者声明或实际测试结果。
领域
工程开发
作者声明的智能体
未找到明确声明;不据此推断已兼容或已测试
静态检查
88 / 100 · 启发式扫描,不代表运行安全
运行环境证据
未执行;当前没有隔离运行测试证据
作者 / 版本 / 许可证
@tomevault-io · 未声明许可证
上下文用量评级
低消耗
接入复杂程度
即装即用
是否需要外部接口密钥
不需要
兼容的系统
未声明(默认跨平台)
运行环境要求
未检出明确要求
检测到的文件与系统行为
  • 只读
网络行为
仅限本地
安装命令数
无(仅作为资料)

需要注意: 未声明工具权限范围;实际权限由运行环境决定。

作者说明文件(原文) SKILL.md

# Go Best Practices

## Error Handling

Check every error. The `if err != nil` pattern is intentional -- Go makes error handling explicit. Never discard errors with `_`. Wrap errors with context using `fmt.Errorf("doing X: %w", err)` so call chains produce readable messages.

Use sentinel errors (`var ErrNotFound = errors.New("not found")`) for expected conditions that callers check with `errors.Is()`. Use custom error types for errors that carry structured data.

## Project Structure

Follow the standard layout: `cmd/` for application entry points, `internal/` for private packages, `pkg/` for public libraries (if any). Keep `main.go` minimal -- it wires up dependencies and starts the server.

One package per directory. Package names should be short, lowercase, and descriptive. Avoid `util` or `common` packages -- they become dumping grounds.

## Concurrency

Do not communicate by sharing memory -- share memory by communicating. Use channels for synchronization between goroutines. Use `sync.Mutex` only for protecting simple shared state where channels would be overkill.

Always ensure goroutines can be stopped. Pass `context.Context` and check `ctx.Done()`. Leaking goroutines is a memory leak that grows over time.

Use `sync.WaitGroup` when you need to wait for a known number of goroutines to complete. Use `errgroup.Group` when any goroutine failure should cancel the rest.

## Interfaces

Define interfaces where they are used, not where they are implemented. Keep interfaces small -- one or two methods is ideal. The `io.Reader` and `io.Writer` interfaces are the gold standard.

Accept interfaces, return structs. This makes code testable -- callers can inject mocks that satisfy the interface.

## Testing

Use table-driven tests for functions with multiple input/output combinations. Name test cases clearly. Use `t.Run()` for subtests so failures identify which case broke.

Use `testing.T.Helper()` in test helper functions so failure messages point to the calling test, not the helper.

## Dependencies

Use `go mod tidy` to keep `go.mod` clean. Vendor dependencies with `go mod vendor` for reproducible builds in CI. Avoid unnecessary dependencies -- the standard library is comprehensive. Check if `net/http`, `encoding/json`, or `os` already do what you need.

## Performance

Profile before optimizing with `pprof`. Pre-allocate slices with `make([]T, 0, expectedCap)` when the size is known. Avoid string concatenation in loops -- use `strings.Builder`. Reduce allocations by reusing buffers with `sync.Pool` for hot paths.

---
> Source: [calcosmic/Aether](https://github.com/calcosmic/Aether) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-23 -->

讨论

基于 GitHub Discussions。登录 GitHub 即可参与讨论、点赞、订阅更新。