go-packages
Use when creating or splitting Go packages, organizing imports or dependencies, or structuring a new Go project. Individual identifier naming belongs to go-naming.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-14
- Stars
- ★ 7
- Forks
- 2
01 前言 Front Matter
- name
- go-packages
- description
- Use when creating or splitting Go packages, organizing imports or dependencies, or structuring a new Go project. Individual identifier naming belongs to go-naming.
02 资源文件 3
- 参考文档references/DEPENDENCIES.md2.7 KB
- 参考文档references/IMPORTS.md2.2 KB
- 参考文档references/PACKAGE-SIZE.md3.5 KB
03 SKILL.md 正文
Go Packages and Imports
Compatibility: Baseline Go 1.27 (see COMPATIBILITY.md). The
tooldirective requires Go 1.24+; stdlibuuidandencoding/json/v2Go 1.27+.
Resource Routing
references/IMPORTS.md- Read when grouping imports, using blank imports, dot imports, or import aliases.references/PACKAGE-SIZE.md- Read when splitting packages, avoidinginit, structuringmain, or designing CLI flags/subcommands.references/DEPENDENCIES.md- Read when runninggo mod initor setting thegodirective, adding a module, usingreplaceorexclude, pinning a tool, tidying, or scanning before a release.
Dependency Ladder
Normative: Before adding a module to
go.mod, check the stdlib. Go 1.27 absorbed several of the most-added dependencies.
Stop at the first rung that works:
- Standard library — check
go doc <pkg>before assuming it is missing - A module already in
go.mod— reuse a suitable supported API - A new module, including
golang.org/x/...— when the above do not meet the contract or would require materially more implementation and maintenance
Judge suitability by required semantics, supported versions, and maintenance, not line count alone. Existing project conventions take precedence; this ladder does not require replacing a working dependency in neighboring code. A dependency is a convention; a standard-library idiom is not (Write Current Go).
Commonly added modules the standard library now covers:
| Was | Use instead | Since |
|---|---|---|
github.com/google/uuid |
uuid — New/NewV4/NewV7, Parse/MustParse, Nil/Max, Compare, text marshaling |
1.27 |
| A third-party JSON library kept for speed | encoding/json, which runs on the v2 implementation (unmarshal faster, marshal slower than on 1.26); encoding/json/v2 + encoding/json/jsontext for v2 semantics or streaming |
1.27 |
github.com/sirupsen/logrus, go.uber.org/zap |
log/slog (see go-logging) |
1.21 |
github.com/pkg/errors |
fmt.Errorf with %w, errors.Is, errors.AsType |
1.13 / 1.26 |
golang.org/x/exp/slices, .../maps |
slices, maps |
1.21 |
| A CSPRNG string helper | crypto/rand.Text |
1.24 |
encoding/json/v2 is not a drop-in replacement for encoding/json: it changes
omitempty, case-matching, and error semantics. Keep v1 for existing wire
formats; reach for v2 for new code or when you need jsontext streaming. Both
ship in the toolchain — no build tag or GOEXPERIMENT needed on Go 1.27.
For I/O forms and compatibility options, read
JSON v2 at API boundaries.
github.com/google/uuid stays justified for the algorithms stdlib uuid does
not have (v1, v3, v5, custom sources).
Adding and Auditing Dependencies
- Upgrade one module per change —
go get <module>@<version>, notgo get -u ./...— so a failure names its cause and the revert is one line; modules that release together count as one. A minor bump needs its release notes read, a major one its migration notes, and av0minor may break. Minimal version selection raises the indirect requirements the new version declares: the// indirectandgo.sumlines are part of the diff, andgo mod graph | grep <module>@names who pulled a surprise version. Tests run before and after;govulncheckcovers the new versions. - A checksum mismatch is a finding.
SECURITY ERRORfrom thegocommand means the bytes differ fromgo.sumor the checksum database: report the module, version, and both hashes. Never editgo.sumor setGOSUMDB,GONOSUMDB, orGOPRIVATEto get past it;go clean -modcachefixes only whatgo mod verifyreports asdir has been modified.
go mod init and the go directive, the pre-add check, replace and
exclude, tool pinning, tidy, and the release scan:
DEPENDENCIES.md.
Package Organization
Layout
cmd/<binary>holds eachmainpackage; everything it imports lives elsewhere.internal/holds packages that are not API. Use it for anything you do not want to support; do not wrap the whole module ininternal/pkg. A layer tree (internal/handlers,internal/services,internal/repositories,internal/models) fits one cohesive service; once several domains change independently, the same layer names move underinternal/<module>/.- Restructuring an existing module — a god package, a global layer tree several domains share, a monolith heading for modules — is go-code-refactor's ARCHITECTURE.md: the import-graph audit, the target shapes, the staged move, and the boundary test. This skill decides where a new package goes.
- A package with a generic name (
util,helper,common,shared,lib) is a finding: go-naming owns the rule and the list.
Package Size
Don't split just because a file is long, to create single-type packages, or if it would create circular dependencies.
Imports
| Rule | Guidance |
|---|---|
Blank imports (import _) |
Only in main packages or tests |
import _ "embed" |
Any package, in the file whose //go:embed fills a string or []byte — the compiler requires it |
Avoid init()
Avoid init() where possible. When unavoidable, it must be:
- Completely deterministic
- Independent of other
init()ordering - Free of environment state and I/O
Exit in Main
Call os.Exit or log.Fatal* only in main(). All other functions should
return errors.
Why: Non-obvious control flow, untestable, defer statements skipped.
Best practice: Use the run() pattern — extract logic into a run that
returns an error, called from main() with a single exit point:
func main() {
if err := run(os.Args[1:], os.Stdout, os.Stderr); err != nil {
fmt.Fprintln(os.Stderr, err)
os.Exit(1)
}
}
A CLI's run takes args []string, stdout, stderr io.Writer and builds its
flag set or command tree inside: a package-level FlagSet or cobra root keeps
flags and state from one test to the next.
Command-Line Flags
Advisory: Define flags only in
package main.
- Follow the project's flag naming convention; this pack defaults to
snake_case(--output_dir) when none exists. - Libraries should accept configuration as parameters, not read flags directly — this keeps them testable and reusable
- Prefer the standard
flagpackage, which already accepts-vand--vas the same flag; usepflagonly when POSIX/GNU conventions are required — grouped single-letter flags (-xvf) or short/long pairs (-v/--verbose)
Build Constraints and Embedded Files
- Platform-specific code lives in
_linux.go/_windows.gosuffix files or behind//go:build linux; a runtimeif runtime.GOOS == ...switch is the last resort. Every constrained file needs a fallback so the package still compiles undergo vet ./...on any GOOS. - Static assets (templates, SQL, schemas) ship via
//go:embedin the package that uses them — never by reading a relative path at runtime, which breaks as soon as the binary runs from another directory.
//go:embed schema/*.sql
var schemaFS embed.FS
Related Skills
- go-naming: package names, stuttering, exported symbols.
- go-error-handling:
%wversus%vat package boundaries. - go-linting: goimports local prefixes, import grouping.
- go-defensive: replacing
init(), mutable globals.
04 同仓库更多 Skills
go-troubleshooting
Use when investigating a bug or ticket in a Go service whose cause is unknown — wrong or missing results, tenant-specific behavior, a regression, stage/prod/CI differences, a panic, hang, deadlock, leak, unexplained CPU/RSS growth, or a flaky test. Also use for pasted stack traces, profiles, logs, or requests to find a Go issue's root cause, even without the word debug. Does not cover rewriting ticket text, implementing an already-diagnosed fix alone (use its topic skill), or optimizing a known bottleneck (see go-performance).
go-testing
Use when writing, reviewing, or improving Go test code — including table-driven tests, subtests, parallel tests, test helpers, test doubles, and assertions with cmp.Diff. Also use when a user asks to write a test for a Go function, even if they don't mention specific patterns like table-driven tests or subtests. Does not cover benchmark performance testing (see go-performance).
go-style-core
Use when resolving Go style or language mechanics such as formatting, nesting, declarations, initialization, scope, shadowing, loops, switches, or enum zero values. API design, naming, errors, and tests have specialized skills.
go-security
Use when writing or reviewing Go code that touches untrusted input, secrets, or credentials — SQL, shell, or template injection, path traversal, SSRF, cookies and security headers, password hashing, TLS settings, token comparison, or what may appear in a log line. Also use when a handler accepts a file name, URL, or command argument from a client, or when asked to find "vulnerabilities", even if the user never says "security". Does not cover the os.Root and crypto/rand mechanics (see go-defensive) or the dependency CVE scan in the gate (see go-linting).
go-resilience
Use when handling Go dependency failures or overload with retries, backoff/jitter, budgets, idempotency, duplicate delivery, circuit breakers, bulkheads, rate limits, backpressure, or degradation. Unknown root causes belong to go-troubleshooting.
go-performance
Use when optimizing slow or performance-critical Go code, allocations, string concatenation in loops, or benchmarks. Also use when writing or reviewing a cache, including implementing one from a stub — its key, its expiry, and how a miss loads. Concurrent code patterns belong to go-concurrency.