AGENT SKILL

shared-packages

The packages every service shares under pkg/ — logging, errors, httputil, openapi and middleware — what each gives, and when a new one belongs there.

License 许可
MIT
最近更新
2026-11-13
Stars
★ 0
Forks
0

01 前言 Front Matter

name
shared-packages
description
The packages every service shares under pkg/ — logging, errors, httputil, openapi and middleware — what each gives, and when a new one belongs there.

03 SKILL.md 正文

Skill: Shared packages

The root pkg/ holds what every service needs, written once. wf add backend wrote the ones below; they are the project's own, to change and extend.

When this skill applies

  • Using pkg/logging, pkg/errors, pkg/httputil, pkg/openapi or pkg/middleware
  • Writing code a second service needs, which goes here rather than into a copy

pkg/logging

Init() first line of every main(): JSON lines on stdout
Debug, Info, Warn, Error(ctx, msg, args...) log with the correlation ID ctx carries
WithCorrelationID, CorrelationID put the ID in a context, read it back

pkg/errors

APIError{Code, Message, Cause} the one error that crosses layers; Cause is never sent to a client
New(code, message, cause) make one
HTTPStatus(code), FromHTTPStatus(status) the HTTP status of a code, and the code of a status another service answered with
As, Is the standard ones, so a file needs only this errors package

Add a code when a client must tell a new kind of failure apart, and give it its status in both functions.

pkg/httputil

Success(c, data), Created(c, data) answer 200 or 201 with {"data": …}
RespondWithError(c, err) answer {"error": {"code", "message"}} with the code's status; logs the cause
BindError(err) the APIError for a request ShouldBind* rejected; its message names each field as the client sends it and the rule it broke, never a Go name
BindQuery(c, &q) binds the query into q by its form tags; a bad value is a 400 naming the parameter
ParamID(c, "id", "order") a positive ID from a path parameter; anything else is a 400 naming it
SplitList(raw) a comma-separated value as its trimmed, non-empty items
PageQuery, ParsePage(c, max), Page.HasMore(returned, total) a paged list's offset and limit; no limit is a full page, one past max is a 400

pkg/openapi

Operation, Build(operations) a route's description, and the document built from them: the api-design skill
openapitest.Engine(t), openapitest.Context(t, w) Gin for a handler test, checking each response against openapi.yaml: the testing skill

pkg/middleware

CorrelationID() gives each request its X-Request-ID, or a new one, in its context and its response

A gateway that calls another service passes the correlation ID on in the same header, so one request can be followed through every service's logs.

A new shared package

Code goes here when a second service needs it, moved rather than copied, with its tests. It depends only on other pkg/ packages and libraries, never on a service.

Definition of done

  • [ ] Nothing in a service repeats what a pkg/ package does
  • [ ] A new shared package has its own tests and imports no service

04 同仓库更多 Skills