القائمة
指导 Go 后端功能的分层设计、领域实体建模、Service 编排、错误边界、日志与依赖方向。新增或修改 application、model/entity、infrastructure、transport、controller、repository 或 Service 代码时使用。
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
| name | golang-backend-guidelines |
| description | 指导 Go 后端功能的分层设计、领域实体建模、Service 编排、错误边界、日志与依赖方向。新增或修改 application、model/entity、infrastructure、transport、controller、repository 或 Service 代码时使用。 |
实现或审查 Go 后端功能时，遵循本技能的分层、领域模型和错误边界规则。与本技能配套的命名、代码风格、context、安全和 lint 规则见仓库中的相关技能链接。
涉及业务状态和业务规则的实体应优先采用充血模型：把数据、状态变化和与自身相关的约束放进实体本身，不把有明确业务行为的实体退化成只有字段的数据库记录。对于纯 DTO、简单 CRUD 或没有业务不变量的持久化映射，不强行增加领域行为。
示例：
type Order struct {
status OrderStatus
}
func (o *Order) Pay(payment Payment) error {
if o.status == OrderStatusCanceled {
return ErrOrderCanceled
}
if payment.Amount <= 0 {
return ErrInvalidPayment
}
o.status = OrderStatusPaid
return nil
}
func (o Order) Status() OrderStatus {
return o.status
}
调用方应使用 order.Pay(payment)、order.Cancel(reason)、order.Ship(trackingNo)，而不是直接执行 order.status = ...。实体必须保证“已取消不能支付”“未付款不能发货”等不变量。
Service 返回给 Controller 的错误必须是 constant/errors.go 定义的 constant.ServiceError，不能把 Repository、数据库、网络或加密库的底层错误直接返回给前端。
ServiceError，例如 constant.ErrBadRequest、constant.ErrUserNotFound。constant.ErrSystemMalfunction。ServiceError.Message。return err，除非 err 已明确是允许暴露的 constant.ServiceError。errors.Is 或 errors.As，不要依赖字符串比较。推荐写法：
user, err := s.userRepository().GetByUsername(ctx, request.Username)
if err != nil {
s.res.Logger().Error(ctx, "failed to get user by username", err)
return nil, constant.ErrSystemMalfunction
}
校验错误和领域错误应在 Service 边界映射；底层错误应在日志中保留诊断信息，但不越过 Service 边界。
transport → application → infrastructure，Controller 不得直接访问 Repository。AGENTS.md 的标准流程注册 DTO、Repository、Service、Controller、路由和依赖注入。ctx context.Context 放在第一个参数。context.Background()。context.WithValue 传递请求级元数据时，key 常量统一定义在 constant/contextkey.go；禁止在各业务层重复定义 context key。context.Context、Logger、Repository 或 HTTP 对象。完成代码后至少执行：
gofmt -w <modified-go-files>
golangci-lint run ./...
go vet ./...
go test ./...
同时检查：实体状态是否只能通过行为修改、Service 是否泄露底层错误、日志是否包含足够诊断上下文，以及错误映射是否覆盖所有失败路径。
需要更详细的充血模型和错误边界示例时，读取领域模型与错误边界参考。
在新增项目通用工具函数前，从 github.com/samber/lo 和 github.com/duke-git/lancet/v2 中查找并选择可复用的 Go 工具函数。实现或审查跨模块工具、集合映射字符串时间文件处理、指针默认值转换、重试或并发辅助逻辑时使用，尤其适用于在 utils/ 下新增代码之前。
Comprehensive documentation guide for Golang projects, covering godoc comments, README, CONTRIBUTING, CHANGELOG, Go Playground, Example tests, API docs, and llms.txt. Use when writing or reviewing doc comments, documentation, adding code examples, setting up doc sites, or discussing documentation best practices. Triggers for both libraries and applications/CLIs.
Golang benchmarking, profiling, and performance measurement. Use when writing, running, or comparing Go benchmarks, profiling hot paths with pprof, interpreting CPU/memory/trace profiles, analyzing results with benchstat, setting up CI benchmark regression detection, or investigating production performance with Prometheus runtime metrics. Also use when the developer needs deep analysis on a specific performance indicator - this skill provides the measurement methodology, while golang-performance provides the optimization patterns.
Golang code style, formatting and conventions. Use when writing Go code, reviewing style, configuring linters, writing comments, or establishing project standards.
Golang concurrency patterns. Use when writing or reviewing concurrent Go code involving goroutines, channels, select, locks, sync primitives, errgroup, singleflight, worker pools, or fan-out/fan-in pipelines. Also triggers when you detect goroutine leaks, race conditions, channel ownership issues, or need to choose between channels and mutexes.
Provides CI/CD pipeline configuration using GitHub Actions for Golang projects. Covers testing, linting, SAST, security scanning, code coverage, Dependabot, Renovate, GoReleaser, code review automation, and release pipelines. Use this whenever setting up CI for a Go project, configuring workflows, adding linters or security scanners, setting up Dependabot or Renovate, automating releases, or improving an existing CI pipeline. Also use when the user wants to add quality gates to their Go project.