Community编程与开发github.com

sk-go-service

在 Go 后端服务中实现、扩展或调试 handler、service 或 repository,涵盖上下文传播、错误包装、事务边界、多租户范围控制和表格驱动测试。适用于编写或修改 Go 服务器代码、添加端点或 gRPC 方法、接触仓库查询,或诊断 Go 服务中的 panic、泄漏或不稳定测试。

sk-go-service 是什么?

该技能为在 Go 后端服务中编写正确、可维护的代码提供了一套约定和最佳实践,特别关注并发和多租户场景下的正确性。它涵盖了从上下文传播、错误处理、事务管理、多租户隔离到 goroutine 生命周期控制和表格驱动测试的全流程指导。该技能适用于任何基于 Go 的服务器端开发,尤其是在使用标准库和常见模式(如 handler-service-repository 分层架构)的项目中。通过遵循这些约定,开发者可以避免常见的并发问题、资源泄漏和安全漏洞,同时确保代码的一致性和可测试性。技能还强调了在编写代码前检查工具链版本、理解包内已有模式的重要性,以及如何通过运行测试和 linter 来验证代码质量。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/vanhuydotcom/sk-skills/tree/HEAD/skills/sk-go-service

Installed? Explore more 编程与开发 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

Go 服务工作

保持分层 Go 服务在并发和多租户下正确的约定。先阅读周围的包——一个一致应用的本地模式比这里的任何东西都重要。

编写代码之前

检查工具链。go.mod 决定了哪些标准库和语言特性可用,同一工作区中的服务通常位于不同的版本上。循环变量捕获在 Go 1.22 以下是一个真正的 bug,在以上则不是问题;errors.Join、slices 和 maps 需要 Go 1.21。读取版本而不是假设最新。

然后找到拥有你要更改的决策的层。Handler 仅将传输层转换为领域层,不做其他事情。Service 持有决策。Repository 持有查询。在 handler 中添加的验证对 service 的所有其他调用者是不可见的。

上下文

上下文属于请求,并随其消亡。

  • 将 ctx 作为第一个参数传递,一直传递到数据库调用。不接受上下文的函数无法被取消,也无法携带截止时间。
  • 切勿将 context.Context 存储在结构体字段中。
  • 切勿将请求上下文传递给生命周期超出 handler 的 goroutine。分离的后台工作需要自己的上下文,带有自己的超时时间,并且在 handler 返回之前显式地复制出它需要的值。
  • 同样适用于从请求派生的任何句柄——事务、连接、请求作用域的数据库访问器。在 handler 返回后使用它们是一种使用后释放,只是错误消息更友好。

错误

  • 使用 %w 包装,并添加调用者无法已知的信息:标识符、操作。fmt.Errorf("load order %d: %w", id, err)。不要用函数名作为前缀;一堆这样的信息读起来像噪音。
  • 使用 errors.Is 和 errors.As 进行比较。一旦有人包装,直接的 == 就会失效。
  • 在 handler 边界的一个地方,将错误转换为传输状态。返回 HTTP 状态码的 repository 已经泄露了两层。
  • sql.ErrNoRows 是一种领域结果,而不是失败。在 repository 边缘将其映射为领域的“未找到”,这样 service 就无需导入 database/sql。
  • 切勿为了满足编译器而丢弃错误。如果确实可以忽略,请赋值给 _ 并添加注释说明原因。

事务

在拥有不变量的层打开事务——通常是 service,绝不是 repository,因为打开自己事务的 repository 无法组合成更大的事务。传递事务句柄向下。

在每个路径上提交和回滚,包括 panic。成功提交后的回滚必须无害;这就是使 defer tx.Rollback() 安全的原因。

不要在不与事务原子化的大前提下执行 I/O。在打开的事务内对支付提供商进行 HTTP 调用,会在别人中断期间持有数据库锁。

多租户

如果服务是多租户的,租户标识符在代码中强制执行,而不是由数据库负责。每个 repository 查询——读和写——都携带租户谓词。仅按主键过滤的查询会愉快地返回另一个租户的行。从代码库已经使用的请求上下文访问器中派生标识符,并检查哪个访问器是正确的:代表子租户操作的 service 通常有两个访问器,明显的那个往往是错误的。

Goroutine

每个 goroutine 都需要已知的生命周期和已知的所有者。在编写 go 之前,回答:谁等待它,它如何停止,它的错误去哪里?错误被丢弃的 goroutine 是静默失败。

当调用者等待时使用 errgroup。当它不合适时,使用显式的 sync.WaitGroup 加上收集错误通道。请求处理中的裸 go f() 几乎总是一个缺陷。

测试

表格驱动,每个 case 一个 t.Run,根据行为而不是输入命名。每个 case 陈述其输入、其期望,不包含其他内容;所有 case 共享的设置属于表格上方。

运行时始终传递超时:

go test -count=1 -timeout 60s ./...

-count=1 阻止结果缓存,否则它会报告你刚刚修改的代码通过。超时比看起来更重要:没有超时的死锁测试会消耗内存直到机器停滞。

测试包的导出行为。测试未导出的内部实现会锁定实现,并在每次诚实的重构时失败。

当测试不稳定时,大多数情况下它报告的是真实的竞争。在得出其他结论之前,使用 -race 运行它,并且永远不要通过添加 sleep 来修复它。

在完成之前

运行覆盖更改的最窄测试,如果共享契约发生变化则扩大范围。在服务中运行 golangci-lint run,而不是通过可能吞没退出代码的 make 目标。报告失败的输出,而不是削弱测试。

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

sk-api

Design and change API contracts (REST, gRPC, protobuf, events) so existing callers keep working, covering resource and method shape, error models, pagination, versioning and the deploy order a breaking change requires. Use when adding or altering an endpoint, message or event, or when judging whether a proposed change breaks a consumer.

sk-code-review

Shows an agent how to design, debug, or review "sk code review" so the concrete output is a code change with a check. The procedure moves through Code review, Establish the diff first, What to look for, in priority order. Use it when a new assignment calls for this craft.

sk-python

Write and debug Python with attention to the traps that produce silent wrong behaviour — mutable defaults, late-binding closures, shallow copies, swallowed exceptions — plus typing, environment and packaging with uv or venv, and pytest structure. Use when writing a Python script, service or library, setting up a Python project, or debugging behaviour that looks impossible.

sk-react

Build and fix React and TypeScript components, covering state placement, effect dependencies, data fetching, list rendering and the re-render traps that cause stale or looping UI. Use when writing or changing a React component or hook, debugging stale data, an infinite render loop or a lost input, or reviewing frontend code.

sk-system-design

Design or evaluate a distributed system from its constraints — service boundaries, synchronous versus event-driven communication, consistency, failure behaviour and capacity — and state the trade-off each choice buys. Use when splitting or merging services, choosing between a call and an event, deciding where data lives, reviewing an architecture proposal, or answering a system design question.

相关技能