go-microservice-dev

name

go-microservice-dev

description

Use when implementing, modifying, scaffolding, generating, or testing a new product's Go microservice, backend feature, or standalone Go CLI/tooling binary using protobuf IDL, Kitex or similar RPC, Hertz or similar HTTP, Wire/DI, MySQL/GORM-style DAL, Redis, MQ, dynamic config, code generation, and focused tests. For reproduction, isolation, or root-cause debugging, use defect-diagnosis first; this skill owns the Go implementation/fix. Triggers also include "用 Go 写一个服务", "Go 后端怎么搞", "Kitex 接口怎么写", "GORM 加索引", "用 Go 写个命令行工具", "重构 Go 服务里的某文件/某类(局部)", "拆分 Go 服务中的大文件或大类", "refactor a file/class within a Go service".

Go Microservice Dev

Use this for implementation of new backend products and services. It should adapt to the repo in front of you, but the workflow is independent of any prior codebase.

Skill Routing

• Use this skill for implementation, scaffolding, code generation, handlers, RPC methods, DAL, Redis, MQ, jobs, external clients, DI, and tests.

• Use product-rd-workflow first when the request is an end-to-end product delivery workflow, product idea to implementation plan, release workflow, cross-skill coordination, bug postmortem, or durable process improvement.

• Use defect-diagnosis first when the task is to reproduce, isolate, instrument, fix, verify, or root-cause a backend defect, regression, repeated failure, review finding, or failing test.

• Use go-microservice-architecture when the user asks for system design, service boundaries, contract strategy, storage ownership, reliability design, or architecture review without code changes.

• Use testing-strategy when the main question is which unit, integration, contract, or E2E layer should prove behavior; then return here for Go-specific implementation.

• Use test-artifact-management when the ask is about generating structured test cases from a Feishu requirements doc or codebase and tracking them in Feishu Bitable before implementation begins.

• Use codebase-specific skills only when the task is explicitly about an existing legacy/workspace repository.

• Development references should turn already-chosen architecture into code, tests, and generated artifacts. If a change requires choosing ownership, security model, source of truth, or release governance, first apply go-microservice-architecture.

• For money, billing, quota, permission, tenant/user data isolation, high-impact AI, repeated writes, async finality, or incident-explanation risk, apply product-rd-workflow high-risk resilience gates and route test-layer design through testing-strategy.

• When a change can alter what a client renders or which state, action, or decision path it offers—including strings/templates/config/flags and API/event/schema fields, enums, status/progress, permission/capability signals, defaults, or result shapes—load ../product-ui-ux-design/references/delivery-contract.md, create the applicable full or lightweight record in that contract, and follow its canonical consumer-universe classification, design/test/client handoffs, and terminal-status rules.

• This Go owner returns only its producer_record delta: immutable binding, build/schema/config artifact identity, exact command/environment, and API/event/log/output observation.

• For a standalone Go CLI, this skill owns Go parser/library implementation mechanics. Any change to a user-facing command tree, subcommand, flag/default/action path, help/output/exit behavior, confirmation, progress, or recovery path also loads terminal-cli-dev, which owns the terminal contract and its UI/UX/testing handoff. Only internal parser refactors proven to preserve all user-visible semantics may skip that owner.

Generalization Discipline

• Implement the repo in front of you, but do not import product nouns, service names, package paths, provider names, IDs, dashboards, or organization-specific habits from prior codebases.
• Convert domain-specific source patterns into reusable mechanics: handler shape, contract evolution, repository pattern, transaction boundary, cache key strategy, idempotency, job lease, config, observability, or test style.
• If an observed pattern only works for one product domain, discard it instead of turning it into a rule.
• Resolve conflicts by choosing the safer generic default: explicit contracts over hidden conventions, DB constraints over cache-only correctness, typed config over ad hoc strings, idempotent consumers over retry-only consumers, focused unit tests over live-infra tests by default, and fail-closed for auth/permission/data-integrity paths.
• Fuse patterns only when both are product-agnostic and reduce implementation ambiguity; otherwise keep the simpler rule.
• When adding or revising durable Go implementation guidance, check whether the lesson is generic backend service practice that should also update python-service-dev, or belongs in a shared workflow skill instead. If the rule depends on Go tooling, protobuf/Kitex/Hertz, Go concurrency, or Go package layout, keep it here and do not force a Python mirror.
• Example: if an existing project uses inline Redis keys but another wraps keys in typed builders, implement typed builders and discard inline string formatting as a reusable pattern.

Development Workflow

Before editing code, generated files, migrations, configs, or tests, complete enough analysis and planning for the change to be reviewable. Scale the plan to risk: a simple low-risk single-package change can use a short inline plan; multi-file, contract-visible, data/schema, async, release, bug-fix, branch/MR, unclear-risk, or high-risk work needs explicit task split, acceptance checks, verification commands, rollback or stop conditions, and named handoffs to architecture, testing, or diagnosis skills before edits.

Repo-local agent contracts (AGENTS.md at the repo root and in source directories) are part of the delivery contract: when a change moves a stable boundary, generated surface, workflow, or directory-local rule, update the nearest contract in the same MR and keep coverage in sync per product-rd-workflow's spec / repo-contract sync gate (tooling: references/developer-tooling-patterns.md).

1. Establish the target service shape.

   • Is this an HTTP API, internal RPC, worker/consumer, scheduled task, command-line tool, or shared library?
   • For internal service-to-service calls, use RPC/gRPC by default and HTTP when the service contract chooses it. Do not treat HTTP as a local shortcut: use the repository/platform HTTP client wrappers for discovery, auth, deadlines, retries, logging, metrics, tracing, and contract tests.
   • Also classify SDK/tooling, generated-contract packages, and demo/test modules; do not treat every go.mod, cmd/*, or unfamiliar directory-naming/build-target convention as a deployable RPC service.
   • Identify the nearest go.mod, service entrypoint, config files, IDL, generated code, DI setup, and test commands.
   • When mining a local/internal reference tree for Go implementation patterns, first detect nested git repositories, submodules, and implementation-bearing non-default branches or tags before judging the tree empty. Prefer read-only tree inspection over switching branches, and record the reusable mechanism rather than the source branch, module, or path.
   • Check whether tests are split into fast unit tests and infrastructure-dependent integration tests.

2. Start from contracts and data.

   • Update protobuf IDL before changing request/response shape.
   • For new or contract-visible services, confirm the globally unique service name, IDL source location, generation command, and generated artifact version before implementing handlers or service logic. Prefer consuming generated contract packages from the contract/generation boundary. When shared IDL and IDLGen repositories exist, Go implementation must use the generated Go artifacts from that shared boundary and keep compatibility with Python and client-side consumers; do not create service-local private IDL copies that drift from the shared contract.
   • For protobuf-backed HTTP, confirm whether protobuf is only the contract source or also the binary wire format. For a new protobuf-backed HTTP surface, record the source/config/test location for the generator, route annotations, JSON/binary content-type policy, protobuf-generated clients, middleware order, error/envelope mapping, and compatibility tests before writing handlers. For modifications, confirm only the touched items; an additive non-wire claim must cite the out-of-scope evidence required by ../platform-service-connectivity/references/protobuf-http-contract-signals.md. Without that cited evidence, the touched item is a blocker, not an additive pass.
   • Implement JSON-wire business API responses through the contract-recorded envelope per ../platform-service-connectivity/references/http-response-envelope-contract.md; when the canonical envelope applies, map domain errors to the canonical / model at the transport boundary and do not return ad hoc top-level business fields from handlers.

Implementation Rules

• Pass context.Context through all external calls. The carve-out is narrow and behavioral: only a function that is and stays side-effect-free — no external calls, goroutines, filesystem/env, clock/random, or logging/trace/tenant/feature lookup across its body and callees — may omit ctx. A mapper or helper that does, or later gains, any such call takes ctx. "ctx on external calls" is not "ctx on every function", but the test is behavior, not the name.
• Set timeouts for RPC/HTTP/DB/Redis/MQ operations.
• Honor an existing context deadline when it is shorter than the local default timeout.
• Separate short serving-path request timeouts from longer admin, migration, bootstrap, and repair-operation timeouts. Do not reuse a sub-second request timeout for synchronous dependency setup, index builds, resource activation, schema creation, or other startup administration.
• Use one canonical error model and convert errors at transport boundaries.
• Add or preserve trace/log id in inbound, outbound, and async execution paths.
• MQ producers and consumers should preserve request context where possible, define retry/drop/dead-letter/alert behavior explicitly, and not return success after business failure unless the drop policy is deliberate and observable.
• MQ producer/consumer wrappers should centralize metadata propagation, topic/tag/filter config, worker sizing, retry/drop behavior, panic recovery, close/drain lifecycle, latency/error metrics, and replay or DLQ visibility. Business handlers should implement domain work and idempotency, not recreate consumer scaffolding.
• Use read/write DB separation if the service stack provides it.
• Use transactions for multi-step writes inside one database.
• Keep GORM/sqlx/raw SQL behind DAL or repository modules; handlers and application services should call intent-focused repository methods, not construct queries directly.
• When referencing an existing codebase or platform pattern, match the core abstraction shape, not just the concept. For example, if the reference stack exposes Tx(ctx, fn) plus transaction-scoped repository accessors or factories, add or reuse the same kind of platform/DAL helper instead of hand-writing Begin/Commit/Rollback or raw tx.ExecContext blocks in business code.
• Keep database read/write routing and transaction ownership in the shared DB/platform layer when the repository already has one. Business repositories should call the unified transaction interface and should not duplicate commit/rollback templates unless no shared primitive exists yet.
• For DB-heavy services, prefer shared transaction helpers that recover/rollback on panic or error, and add non-production query-safety checks where the repo has ORM hooks, query builders, migration metadata, or test infrastructure to support them. If the repo cannot mechanically check missing indexes or full scans yet, record the platform gap and cover changed high-risk queries with DDL/DAL review evidence, bounded pagination assertions, or focused tests. These checks should become framework or DAL behavior, not reviewer folklore.

Reference Loading

• For source provenance, current extraction boundary, and keep/merge/discard decisions, read references/source-evidence-map.md when auditing or re-extracting this skill.
• For feature implementation steps, read references/feature-playbook.md.
• For generated code, DB, Redis, MQ, and testing patterns, read references/engineering-patterns.md.
• For reliability, context, error handling, async jobs, and external calls, read references/reliability-patterns.md.
• For service setup, codegen commands, DI wiring, and test-target hygiene, read references/scaffold-and-codegen.md.
• For protobuf/IDL implementation, field numbering, enum/message patterns, generation commands, and compatibility tests, read references/protobuf-contract-patterns.md.
• For secret clients, service discovery clients, object storage, external HTTP clients, bounded concurrency, and dependency adapters, read references/dependency-client-patterns.md.
• For handler/service/DAL feature work, validation, transactions, pagination, and side effects, read references/domain-feature-patterns.md.
• For data access, local/Redis cache, locks, idempotency, and query design, read references/data-access-patterns.md.
• For public API auth, external app credentials, authorization-scope checks, callback verification, and audit behavior, read references/public-api-integration-patterns.md.
• For HTTP gateway handlers, generated route files, middleware hooks, request binding, response mapping, and generated HTTP clients, read references/http-gateway-client-patterns.md.
• For release-facing code, deployment config, health endpoints, canary checks, traffic config, approval tasks, and operations notifications, read references/release-ops-patterns.md.
• For test strategy, fakes/mocks, traffic replay, generated-output tests, and CI quality gates, read references/quality-and-testing-patterns.md.
• For cross-stack unit/integration/E2E test layer selection, fixtures, flake control, and CI gate design, use testing-strategy.
• For runtime middleware, context propagation, service discovery clients, logs, metrics, tracing, and request/response logging controls, read references/observability-implementation-patterns.md.
• For DDL-first DB implementation, generated models/DAL, sharding-safe queries, migrations, and transaction tests, read references/db-schema-and-dal-patterns.md.