golang-expert
Complete Go development ecosystem: concurrent microservices with Gin, gRPC/Protobuf communication, data access with GORM/pgx/example.org, OpenTelemetry instrumentation, structured logging with Zap, table-driven testing and static analysis with golangci-lint. Use when writing Go microservices, creating gRPC/Protobuf APIs, implementing data access with GORM/pgx, or setting up OpenTelemetry instrumentation. Trigger: Go microservice, gRPC Protobuf, GORM, pgx, OpenTelemetry Go, Zap logger, table-driven test, golangci-lint. Do NOT trigger for: general HTTP API design, database schema design, Dockerfile creation.
- License 许可
- MIT
- 最近更新
- 2026-08-27
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- golang-expert
- license
- MIT
- metadata
- { "author": "Community", "status": "stable", "version": "1.0", "category": "backend" }
- description
- Complete Go development ecosystem: concurrent microservices with Gin, gRPC/Protobuf communication, data access with GORM/pgx/example.org, OpenTelemetry instrumentation, structured logging with Zap, table-driven testing and static analysis with golangci-lint. Use when writing Go microservices, creating gRPC/Protobuf APIs, implementing data access with GORM/pgx, or setting up OpenTelemetry instrumentation. Trigger: Go microservice, gRPC Protobuf, GORM, pgx, OpenTelemetry Go, Zap logger, table-driven test, golangci-lint. Do NOT trigger for: general HTTP API design, database schema design, Dockerfile creation.
02 资源文件 4
- 参考文档evals/evals.json2.4 KB
- 参考文档references/concurrency.md1.6 KB
- 参考文档references/performance.md1.2 KB
- 参考文档references/testing.md1.8 KB
03 SKILL.md 正文
Go Expert
Go ecosystem: microservices, gRPC, observability, testing and linting.
Core Stack
- HTTP: Gin (routing, middleware, validation)
- RPC: gRPC + Protobuf (Buf, proto3, streaming)
- Data: GORM + pgx +
example.orglibs (dynamodb, sqs, sns, auth, workflow, state-machine) - Internal:
go-kitteam (service interface, HTTP/AMQP transports, middleware) - Logging: Zap (structured JSON)
- Tracing: OpenTelemetry (traces, metrics, context propagation)
- Testing:
go testtable-driven + Testify + benchmarks + race detector - Linting:
golangci-lint(vet, staticcheck, gosec, errcheck)
Project Structure
cmd/server/main.go # entry point, DI, graceful shutdown
internal/
handler/ # HTTP handlers (thin: parse -> call service -> return)
service/ # business logic + OTel spans
repository/ # data access (GORM/pgx)
model/ # domain types
middleware/ # RequestID, logging, recovery, auth
api/proto/ # .proto files (Buf managed)
migrations/ # SQL migration files
Architecture
Handler -> Service -> Repository (NEVER skip layers)
- Handlers: thin, parse only, return status codes
- Service: business logic + OTel spans (
tracer.Start(ctx, "Op")) - Repository: data access with
context.Context - ALWAYS propagate
context.Contextthrough all layers - NEVER business logic in handlers | NEVER repo from handler directly
- ALWAYS
WithContext(ctx)on GORM | ALWAYS wrap errors withfmt.Errorf("op: %w", err)
gRPC / Protobuf
syntax = "proto3";
package resources.v1;
option go_package = "github.com/example/resources/gen/go/resources/v1;resourcesv1";
message ProcessRequest {
string resource_id = 1;
int64 quantity = 2; // discrete = int64 units, NEVER float
string kind = 3;
}
buf lint+buf breaking --against .git#branch=mainbefore merge- Enums: ALWAYS
_UNSPECIFIED = 0first value; never remove, mark reserved - Field numbers 1-15 for frequent fields (1-byte encoding)
- Version packages as
service.v1; bump tov2for breaking changes - Pagination: cursor-based with
page_token, NEVER offset-based
OpenTelemetry
- Span naming:
POST /resource(never include IDs) - ALWAYS
span.RecordError(err)on every error path - ALWAYS propagate
context.Context; never create root spans mid-chain - Sampling: <=10% in production (never 100%)
- NEVER high-cardinality values as metric label keys
Linting (Golden Chain)
go fmt -> golangci-lint run -> go vet -> go test -> gosec
Stop on first failure. Never || true in CI.
Libraries
example.org: 20+ sub-modules (core, http, dynamodb, aws, bindetector, auth, workflow, security, state-machine, validator, publisher, sns, sqs, notification-sender)go-kit: toolkit HTTP/AMQP, logging, tracing — 16+ dependent servicesgoauth: JWT integration helper- Changes to these libs have org-wide blast radius
Testing
func TestProcessItem(t *testing.T) {
tests := []struct {
name string
input ItemRequest
want ItemResponse
wantErr bool
}{{
name: "valid item",
input: ItemRequest{Value: 1000, Kind: "standard"},
want: ItemResponse{Status: "ok"},
wantErr: false,
}}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
got, err := svc.Process(t.Context(), tt.input)
if (err != nil) != tt.wantErr {
t.Errorf("error = %v, wantErr = %v", err, tt.wantErr)
}
})
}
}
- Table-driven tests always. Race detector:
go test -race ./... - Benchmarks for hot paths:
go test -bench=. -benchmem
Constraints
- NEVER business logic in handlers | NEVER repo from handler directly
- NEVER expose internal errors to clients
- NEVER reuse field numbers in proto | NEVER remove enum values
- NEVER
float/doublefor discrete quantities —int64units - ALWAYS
context.Context| ALWAYSWithContext(ctx)on GORM - ALWAYS wrap errors | ALWAYS structured logging with
trace_id - ALWAYS graceful shutdown with
signal.NotifyContext - NEVER
go fmt || true— stop on lint failure - NEVER hardcode secrets — use env/config with secrets manager
Security
- ALWAYS run
gosecin CI andgovulncheckfor dependency CVEs (supply chain, OWASP A03) - NEVER allow SSRF (CWE-918): validate and allowlist all URLs passed to HTTP clients
- NEVER deserialize untrusted bytes into structs (CWE-502) — decode with strict schemas only
- ALWAYS pin direct and transitive dependencies; review
go mod graphfor drift
Overview
Go microservices in this project use Gin for HTTP, gRPC+Protobuf for internal RPC, GORM/pgx for data access, and OpenTelemetry for observability. The example.org library suite provides shared infrastructure across 20+ services.
Quick Reference
| Layer | Library | Responsibility |
|---|---|---|
| HTTP | Gin | Routing, middleware, validation |
| RPC | gRPC + Protobuf (Buf) | Internal service-to-service communication |
| Data | GORM + pgx + example.org | ORM, raw SQL, DynamoDB/SQS/SNS helpers |
| Observability | OpenTelemetry + Zap | Traces, metrics, structured JSON logging |
| Linting | golangci-lint (vet, staticcheck, gosec, errcheck) | Static analysis |
Workflow
- Define
.protoservice schema withbuf lint+buf breakingcheck - Generate Go code from protos and implement gRPC server/handler
- Implement handler layer: parse request → call service → return response
- Implement service layer with business logic + OpenTelemetry spans
- Implement repository layer with
context.Contextand GORMWithContext - Write table-driven tests with
go test -race ./... - Run golden chain:
go fmt→golangci-lint run→go vet→go test→gosec
Anti-patterns
FAIL: Business logic in HTTP handlers PASS: Handlers only parse input; business logic in service layer
// FAIL:
func (h *Handler) CreateItem(c *gin.Context) {
var req ItemRequest
if err := c.BindJSON(&req); err != nil { ... }
if req.Value <= 0 { ... } // business logic
result := h.db.Create(&Item{Value: req.Value}) // data access
c.JSON(201, result)
}
// PASS:
func (h *Handler) CreateItem(c *gin.Context) {
var req ItemRequest
if err := c.BindJSON(&req); err != nil { ... }
result, err := h.svc.Process(c.Request.Context(), req)
if err != nil { ... }
c.JSON(201, result)
}
FAIL: Using float/double for discrete quantities
PASS: Always use int64 units
// FAIL:
type Item struct {
Value float64 // floating point rounding errors
}
// PASS:
type Item struct {
Value int64 // use integer units
}
FAIL: Silently swallowing errors with || true in CI linting
PASS: All linting steps must fail if any rule is violated
# FAIL:
lint:
go fmt || true
golangci-lint run || true
# PASS:
lint:
go fmt && golangci-lint run && go vet
References
-
Effective Go (last_verified: 2026-05-25)
-
gRPC Go Documentation (last_verified: 2026-05-25)
-
OpenTelemetry Go (last_verified: 2026-05-25)
Verification Checklist
- [ ] Handler layer is thin (parse request → call service → return response, no business logic)
- [ ]
context.Contextpropagated through all layers (handler → service → repository) - [ ] Discrete quantities use
int64units (never float/double) - [ ] gRPC protos pass
buf lintandbuf breakingchecks - [ ] OpenTelemetry spans created with
RecordErroron all error paths - [ ] Table-driven tests written with
go test -race ./...passing - [ ]
gosecandgovulncheckrun clean in CI (no HIGH/Critical findings)
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
sql: database is closed |
Missing WithContext(ctx) on GORM call |
Ensure every GORM query uses db.WithContext(ctx) |
gRPC Unavailable error |
Server not registered or port mismatch | Verify grpcServer.Serve(lis) called with correct listener address |
| Traces not appearing in backend | Missing OTel exporter or incorrect endpoint | Check OTEL_EXPORTER_OTLP_ENDPOINT env var and service name in SDK init |
Edge case: go test -race false positive on atomic operations |
Race detector flags intentional concurrent access patterns | Use sync/atomic for counters; mark deliberate races with //nolint:race comment |
| [WARN] go-kit endpoint panics on nil request | Endpoint DecodeRequestFunc returns nil if decoding fails; transport sends nil to endpoint | Check req != nil in endpoint before passing to next; always wrap decode with error return |
| go.mod indirect dependency pinned to broken version by a team internal module | team internal example.org module pins a vulnerable transitive dep that cannot be upgraded | Add replace directive in go.mod; request the owning team to update their dependency version |
| Known bug: go-kit logging middleware drops context fields when logger is passed by value | go-kit logger interface used with value receiver; context fields lost between middleware layers | Always pass *log.Logger pointer; verify context fields survive middleware chain |
04 同仓库更多 Skills
web-browsing-agent-expert
Web browsing for AI agents: driving a headless browser (Playwright, Puppeteer) from agent tooling, navigation and page-state grounding, DOM extraction and structured data capture, form interaction, session and cookie management, anti-bot mitigation awareness, and safe browsing rules (no PII exfiltration, respect robots and terms). Use when building a browsing tool or MCP server for an agent, teaching an agent to navigate and read web pages, extracting structured content from dynamic sites, or handling login walls and pagination in agent workflows. Trigger: web browsing agent, headless browser, Playwright MCP, Puppeteer, browser automation for agents, DOM extraction, page navigation, session management. Do NOT trigger for: end-to-end UI testing of an application (use playwright-expert); writing standalone scraping scripts for data pipelines (use python-expert); fetching a single public URL (use the fetch tool).
vector-databases
Design and operate vector databases for cloud-native AI features. Use when selecting between pgvector, Pinecone, or Weaviate for AI context layer or integration-hub; designing embedding schemas and index parameters; implementing ANN search with metadata filtering; managing embedding model versions; optimizing query latency; or debugging low retrieval quality. Pairs with rag-architecture for pipeline design and postgres-database-expert for pgvector specifics. Trigger: vector database, pgvector, Pinecone, Weaviate, embedding, ANN search, HNSW, cosine similarity. Do NOT trigger for: relational SQL optimization, standard PostgreSQL schema design, Redis caching.
typescript-expert
Full-stack TypeScript stack for modern projects: frontend SSR/CSR with Next.js 14 App Router and React, backend APIs with Node.js (Express/Fastify), state management with Zustand/Redux Toolkit, unit and integration testing with Vitest/Jest + React Testing Library + MSW, and static analysis with ESLint/Prettier/tsc. Use when building React components or hooks, implementing Next.js App Router or Server Components, writing Node.js REST API handlers, implementing middleware (auth, rate-limit, logging), managing client state (Zustand/RTK), writing frontend/backend tests, or running TypeScript linting/type checks. Trigger: TypeScript, Next.js, React, Zustand, Node.js, Express, Fastify, MSW, Vitest. Do NOT trigger for: Python backend development, Go microservices, iOS/mobile development.
tool-usage
Guide correct tool selection, design, and orchestration for AI agents. Use when choosing between dedicated vs Bash tools, designing MCP tool interfaces, naming tool parameters, handling tool response limits, orchestrating parallel vs sequential calls, evaluating tool accuracy, applying ACI design principles, selecting workflow patterns, or reading/filtering/transforming/generating structured data (JSON, YAML, CSV, TOML, XML). Trigger: tool selection, MCP tool design, orchestration, ACI, parallel execution, composite tool, structured data, jq, yq, dasel, mlr, csvkit. Do NOT trigger for: writing application business logic, domain-specific development (route to domain skill), database migrations.
token-efficiency
Enforce token-efficient output, compression, caching, and model routing. Use when calibrating response verbosity, applying compression strategies to logs or RAG chunks, routing tasks to the right model tier, setting thinking budgets, enforcing word limits, compressing context before reinitiation, applying KV-cache ordering, masking tool output observations, or applying clarification-first protocol before irreversible actions. Trigger: token efficiency, compression, model routing, thinking budget, KV-cache, clarification protocol. Do NOT trigger for: non-agent tooling, CI/CD pipeline scripting, infrastructure provisioning.
time-series-db
Time-series database patterns for cloud-native metrics and analytics: TimescaleDB, InfluxDB, and Amazon Timestream selection; continuous aggregates, retention policies, downsampling, and integration with Prometheus/Grafana. Use when storing business metrics over time, building custom business dashboards, designing high-frequency event storage, or querying time-bucketed aggregations. Trigger: time-series, TimescaleDB, InfluxDB, Prometheus, Grafana, hypertable, continuous aggregate, retention policy. Do NOT trigger for: relational PostgreSQL schema design, NoSQL document stores, Kafka event streaming.