戈兰
- 作者仓库星标 0
- 作者仓库 skills-registry
- 领域
- 工程开发
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @tomevault-io · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 即装即用
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- 未声明(默认跨平台)
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
# 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 -->
章节与文件索引
按说明文件中的顺序排列。
错误处理
项目结构
并发性
接口
测试
文件/命令 -> if err != nil · . Wrap errors with context using · var ErrNotFound = errors.New("not found") · errors.Is() · cmd/ · internal/ · pkg/ · main.go
内容校验值 -> 33fa850324ca
当前原文的自动摘译,尚未人工审校。
错误处理
检查每个错误。
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(),以便失败消息指向调用测试,而不是辅助函数。