go-http
/go-http
Pomaga pisać i recenzować kod HTTP w Go: handlery, routing net/http ServeMux, middleware, dekodowanie żądań i kodowanie odpowiedzi, timeouty serwera, łagodne zamykanie i klienty HTTP.
- Autor
- h0rn3t ↗
- Repozytorium
- golang-skills ↗
- Licencja
- Apache-2.0
- Ostatnia zmiana repozytorium
- 27.10.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 4
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 27.10.2026, bez odwołań do wycofanych modeli i API.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
Co robi i kiedy
Pomaga pisać i recenzować kod HTTP w Go: handlery, routing net/http ServeMux, middleware, dekodowanie żądań i kodowanie odpowiedzi, timeouty serwera, łagodne zamykanie i klienty HTTP.
Oryginalny opis (EN)
Use when writing or reviewing Go HTTP code — handlers, routing with net/http ServeMux, middleware, request decoding and response encoding, server timeouts and graceful shutdown, or HTTP clients. Also use when building a REST or JSON API endpoint or calling an external HTTP service, even if the user names a framework instead of net/http. Does not cover the test server helpers (see go-testing) or request-scoped logging (see go-logging).
Jak działa
- Resource Routing
- Routing (Go 1.22+)
- Handler Shape
- Middleware
- Server Construction
- Clients
- Related Skills
Podgląd SKILL.md
---
name: go-http
description: Use when writing or reviewing Go HTTP code — handlers, routing with net/http ServeMux, middleware, request decoding and response encoding, server timeouts and graceful shutdown, or HTTP clients. Also use when building a REST or JSON API endpoint or calling an external HTTP service, even if the user names a framework instead of net/http. Does not cover the test server helpers (see go-testing) or request-scoped logging (see go-logging).
---
# Go HTTP Servers and Clients
> Compatibility: Baseline Go 1.27 (see the plugin repository's COMPATIBILITY.md). `ServeMux` method and
> wildcard patterns require Go 1.22+; `http.NewCrossOriginProtection` Go 1.25+;
> `http.Server.MaxHeaderValueCount` and `encoding/json/v2` Go 1.27+.
## Resource Routing
- `references/WEB-SERVER.md` - Read when assembling a complete server: routing, handler, graceful shutdown, and where the other go-* skills meet in one `main`.
- `references/JSON-V2.md` - Read when choosing JSON v2 I/O APIs, decoding a bounded document, migrating wire formats, or testing exact JSON bytes (Go 1.27+).
- `references/GRPC.md` - Read when writing a gRPC server or client: status codes, generated-server embedding, `grpc.NewClient`, bounded `GracefulStop`, and bufconn tests.
## Routing (Go 1.22+)
A package already on a framework keeps it, and the rules below still apply;
[go-packages](../go-packages/SKILL.md) owns adding a router module.
```go
mux := http.NewServeMux()
mux.HandleFunc("GET /users/{id}", s.handleGetUser) // serves GET and HEAD
mux.HandleFunc("GET /users", s.handleListUsers)
mux.HandleFunc("POST /users", s.handleCreateUser)
mux.HandleFunc("GET /{$}", s.handleIndex) // exact "/", not a subtree
id := r.PathValue("id")
```
- **A `GET` pattern also serves `HEAD`.** A method pattern answers every other
method on its path with 405 and an `Allow` header that lists `HEAD`; `HEAD`
is the one it lets through, with the `GET` handler's status. Under a
contract that makes every method but `GET` a 405, every `GET` path gets a
`HEAD` pattern and a pattern without a method, both answered with the
methods that path serves — the health check and the index as much as the
resource routes, so the file registers as many `HEAD` patterns as `GET`
patterns — or a `GET`-only path registers its handler without a method and
opens it with an `r.Method != http.MethodGet` check that answers 405 with
`Allow: GET`; the test file sends
`HEAD` and `POST` to each `GET` path and reads `Allow`. A pattern without a
method matches every method.
- Conflicting patterns panic at registration; overlapping patterns are valid
when one is more specific, which is why `HEAD /users/{id}` registers beside
`GET /users/{id}`.
- Trailing `/` is a subtree; `{$}` pins the exact path.
Only when the contract makes `HEAD` a 405, one package function builds the
answer, registered twice per `GET` path — as `HEAD` and without a method, so
`POST` and `DELETE` get the same `Allow` — the index included:
```go
// methodNotAllowed answers every method its path does not serve, HEAD among
// them; allow lists the methods the path does serve.
func methodNotAllowed(allow string) http.HandlerFunc {
return func(w http.ResponseWriter, _ *http.Request) {
w.Header().Set("Allow", allow)
http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
}
}
mux.HandleFunc("HEAD /users/{id}", methodNotAllowed("GET"))
mux.HandleFunc("/users/{id}", methodNotAllowed("GET"))
mux.HandleFunc("HEAD /users", methodNotAllowed("GET, POST"))
mux.HandleFunc("/users", methodNotAllowed("GET, POST"))
mux.HandleFunc("HEAD /{$}", methodNotAllowed("GET"))
mux.HandleFunc("/{$}", methodNotAllowed("GET"))
```
## Handler Shape
Preserve the existing handler structure. No package-level state.
Bound and decode → validate → call the domain with `r.Context()` → map the
error → write once. `Server` below stands for the type the repository already
has; in new code without one, the handler is a function literal in the
constructor that builds the mux, capturing the store
([go-code](../go-code/SKILL.md#declaration-budget)). With
`import json "encoding/json/v2"` (Go 1.27):
```go
func (s *Server) handleCreateUser(w http.ResponseWriter, r *http.Request) {
r.Body = http.MaxBytesReader(w, r.Body, 1<<20)
var req struct {
Name string `json:"name"`
}
// One decode: an unknown member, a second value, junk, or an oversized body fails.
if err := json.UnmarshalRead(r.Body, &req, json.RejectUnknownMembers(true)); err != nil {
http.Error(w, "invalid JSON body", http.StatusBadRequest)
return
}
if req.Name == "" {
http.Error(w, "name is required", http.StatusBadRequest)
return
}
user, err := s.store.Create(r.Context(), req.Name)
switch {
case errors.Is(err, ErrConflict):
http.Error(w, "name already taken", http.StatusConflict)
return
case err != nil && errors.Is(r.Context().Err(), context.Canceled):
slog.DebugContext(r.Context(), "create user: client gone", "err", err)
return // nobody is left to read a status
case err != nil:
slog.ErrorContext(r.Context(), "create user", "err", err)
http.Error(w, "internal error", http.StatusInternalServerError)
return
}
body, err := json.Marshal(struct { // the response names its fields; a stored one added later stays out
ID string `json:"id"`
Name string `json:"name"`
}{user.ID, user.Name})
if err != nil { // before any header, so an encode error is still a 500
slog.ErrorContext(r.Context(), "encode user", "err", err)
http.Error(w, "internal error", http.StatusInternalServerError)
return
}
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(http.StatusCreated)
_, _ = w.Write(body) // headers are sent; a failed write is the client's disconnect
}
```
- Bound every decoded body with `http.MaxBytesReader`. `{}` and `null` still
decode, leaving `req` zero, so required fields are validated before the
store call. The request type is declared in the handler that reads it; a second
handler decoding the same document is what moves it to package level
([go-code](../go-code/SKILL.md#declaration-budget)).
- A package already decoding with `encoding/json` v1 keeps v1 and its two
decodes: `dec.DisallowUnknownFields()`, `dec.Decode(&req)`, then
`dec.Decode(new(any))` must return `io.EOF` — `DisallowUnknownFields`
alone accepts trailing data, and the second decode allows trailing
whitespace while the cap still holds.
- v2 encodes a nil slice as `[]` and a nil map as `{}`, so a filtered list
with no matches is written as it is, with no `make([]T, 0, n)`; that line
belongs to a package on v1, or under `FormatNilSliceAsNull(true)`
([JSON-V2.md](references/JSON-V2.md#defaults-that-can-change-the-contract)).
- A response body is marshalled with `json.Marshal` before the first header,
as above. v2 fails at encode time on a `time.Duration` field (no default
representation), invalid UTF-8 in stored text, or a `MarshalJSON` error;
`json.MarshalWrite(w, v)` after `WriteHeader` sends the status with a
truncated body and nowhere to report the error.
- A write whose error has nowhere to go is discarded in the open with its
reason on the line, as the example's last line is, never bare. `errcheck`
reads a bare `w.Write`, `io.WriteString(w, …)`, `json.MarshalWrite(w, v)`,
or `json.NewEncoder(w).Encode(v)` as a finding, and `//nolint:errcheck` is
not a way out: `gosec` G104 reports the same line.
### Partial Updates
A PATCH body names only the members it changes, and a Go struct cannot tell a
missing member from a zero one: decoding into a fresh struct and saving it
zeroes every field the client left out. Load the record, copy its
client-writable fields into the request value, and unmarshal the body onto
that value. v2 leaves an absent member as loaded and sets one sent as `null`
to its zero value (v1 leaves it unchanged). `RejectUnknownMembers(true)`
refuses `password_hash` and any member the request type does not hold, and a
top-level `null` leaves the pointer nil. v2 decodes into what the request
value already holds — it writes a non-nil slice's array, merges into a
non-nil map, decodes through a non-nil pointer — so a slice, map, or pointer
field is copied with `slices.Clone`, `maps.Clone`, or a new value; copied as
is, the record changes before the body is rejected:
```go
r.Body = http.MaxBytesReader(w, r.Body, 1<<20)
req := &struct {
Email string `json:"email"`
Phone string `json:"phone"` // "phone": null clears it
Tags []string `json:"tags"`
}{acct.Email, acct.Phone, slices.Clone(acct.Tags)} // never acct.Tags: v2 writes into its array
if err := json.UnmarshalRead(r.Body, &req, json.RejectUnknownMembers(true)); err != nil || req == nil {
http.Error(w, "invalid JSON body", http.StatusBadRequest)
return
}
if req.Email == "" { // "email": null arrives as ""
http.Error(w, "email is required", http.StatusBadRequest)
return
}
acct.Email, acct.Phone, acct.Tags = req.Email, req.Phone, req.Tags // a rejected body never touched acct
```
### Mapping errors to status codes
Centralize shared error-to-status rules in `writeError`, using
`errors.Is`/`errors.AsType`; keep a single-handler mapping local. Apply each
row where that failure can occur:
| Error | Status | Body |
|---|---|---|
| Validation, malformed input | 400 | The validation message |
| `ErrNotFound` sentinel | 404 | Generic |
| `ErrConflict`, version mismatch | 409 | Generic |
| Incoming `r.Context().Err()` is `context.Canceled` | 499-style: log at Debug, write nothing | — |
| Downstream `context.Canceled` while the incoming request is alive | 500 unless the endpoint specifies otherwise | Generic |
| `context.DeadlineExceeded` from downstream | 504 | Generic |
| Anything else | 500 | Generic — **never** `err.Error()` |
The request ID reaches the 500 record only through the request-scoped
logger [go-logging](../go-logging/SKILL.md#request-scoped-logging) sets up;
where the repository has one, the example's `slog` calls go through it. This is
the handle-once exception owned by
[go-error-handling](../go-error-handling/SKILL.md).
## Middleware
`func(next http.Handler) http.Handler`. Outside in: recover → request ID +
logging → auth → mux. Wrap `http.ResponseWriter` only to capture status and
keep it transparent; use `http.NewResponseController(w)` for deadlines and
flushing instead of asserting optional interfaces.
## Server Construction
Construct an `http.Server`; bare `http.ListenAndServe` sets no timeouts.
| Field | Why |
|---|---|
| `ReadHeaderTimeout` | Slowloris defense; must never be zero |
| `ReadTimeout`, `WriteTimeout` | Bound slow clients; `WriteTimeout` exceeds the slowest handler |
| `IdleTimeout` | Reclaim keep-alive connections |
| `MaxHeaderBytes`, `MaxHeaderValueCount` (Go 1.27+) | Only to change the defaults, 1 MiB and 500 values: `MaxHeaderBytes: 1 << 20` restates zero |
| `Handler: http.NewCrossOriginProtection().Handler(mux)` | CSRF for state-changing requests (Go 1.25+). One per server: with CORS it is the instance go-security's `withCORS` builds with the trusted origins; a second, empty one around it answers every cross-origin POST with 403 |
| `BaseContext` | Never the `signal.NotifyContext` context when in-flight requests should drain: it cancels every request at the signal, before `Shutdown` waits for them. Handlers that must see shutdown get a separate context, cancelled once `Shutdown`'s timeout expires |
One slow route does not raise `WriteTimeout` for all: wrap it in
`http.TimeoutHandler(h, d, msg)`, which cancels `r.Context()` at `d` and
answers 503. It buffers the response and has no `Flusher`, so a streaming
route sets its own deadline with `http.NewResponseController(w)` instead.
For graceful shutdown, `signal.NotifyContext` owns the lifetime;
`ListenAndServe` runs in one goroutine feeding a buffered error channel;
`srv.Shutdown(ctx)` gets its own timeout.
## Clients
- Never `http.Get`, `http.Post`, or `http.DefaultClient` — no timeout. One
tuned `*http.Transport` and one `*http.Client{Timeout: d, Transport: t}` per
dependency, built once and reused. The Transport owns the connection pool: a
`Client` with a nil `Transport` shares `http.DefaultTransport`, which keeps
two idle connections per host (`http.DefaultMaxIdleConnsPerHost`). Tune a
clone of it; a `&http.Transport{...}` literal drops `ProxyFromEnvironment`
and the dial, TLS-handshake, and idle-connection timeouts (the SSRF dialer in
[go-security](../go-security/SKILL.md) drops the proxy on purpose):
```go
t := http.DefaultTransport.(*http.Transport).Clone()
t.MaxIdleConnsPerHost = 32
client := &http.Client{Timeout: 10 * time.Second, Transport: t}
```
- `http.NewRequestWithContext(ctx, ...)` — the ctx-less form is unbounded;
`noctx` in the lint gate flags it.
- The Transport reads the request body on its own goroutine, and that read
can outlive `Do`: a 4xx/5xx answered from the headers, a timeout, or a
cancel returns mid-upload, and on HTTP/2 the Transport's own `Close` of the
body can overlap a `Read`. Each request, retry included, gets its own
`bytes.NewReader` over bytes nobody writes again — never the previous
attempt's reader rewound, never a shared or pooled buffer refilled; `-race`
reports that write against the Transport's body writer.
- `defer resp.Body.Close()` right after the `err != nil` return, on every
status (`bodyclose` flags a miss); on error `Do` returns no body to close.
Bound untrusted bodies and close them on every path. Go 1.27
drains an unread HTTP/1 body on `Close` — up to 256 KiB and 50 ms — to keep
the connection reusable, so closing is the whole obligation; a manual read to
EOF only buys reuse for responses past those bounds.
- Check `resp.StatusCode` before decoding; a 5xx body is not your struct.
- For retry eligibility, `Retry-After`, replay safety, and coordinated budgets,
use [go-resilience](../go-resilience/SKILL.md). HTTP status alone does not
establish whether repeating an operation is safe.
### Bounded Response Bodies
For a strict response-size limit, read at most the limit plus one byte,
reject an oversized result, then decode the complete buffer into `dst`.
A decoder can finish its first object before `io.LimitReader` reaches its
limit; that alone does not enforce the size of the whole response.
```go
const maxBody = 64 << 10
body, err := io.ReadAll(io.LimitReader(resp.Body, maxBody+1))
if err != nil {
return fmt.Errorf("read response: %w", err)
}
if len(body) > maxBody {
return fmt.Errorf("response exceeds %d bytes", maxBody)
}
return json.Unmarshal(body, dst)
```
## Related Skills
- [go-context](../go-context/SKILL.md): derived deadlines and request lifetime.
- [go-database](../go-database/SKILL.md): handler queries and transactions.
- [go-testing](../go-testing/SKILL.md): `httptest` and `synctest`.
- [go-concurrency](../go-concurrency/SKILL.md): server goroutine and shared state.
- [go-security](../go-security/SKILL.md): input naming files, URLs or commands;
cookies, SSRF, and error disclosure.
- [go-data-structures](../go-data-structures/SKILL.md): nil versus empty slices
and maps before they reach the encoder.
Pliki w paczce (4)
- SKILL.md 15 KB
- references/GRPC.md 4 KB
- references/JSON-V2.md 5 KB
- references/WEB-SERVER.md 3 KB
Wersje
W bazie nie ma innych skilli o nazwie go-http.
Migawka bazy z 13.11.2026 · wersja paczki fafd48b8e973 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100go-api-design
Projektuje API HTTP i REST w Go: handlery, routing ServeMux, middleware, walidacja żądań, paginacja, idempotentność, health checki, odpowiedzi błędów i łagodne zamykanie. - 100go-architect
Projektuje architekturę aplikacji w Go: routing net/http 1.22+, strukturę projektu, łagodne zamykanie i wstrzykiwanie zależności. - 100gin
Buduje API HTTP w Go z frameworkiem Gin: routing i grupy tras, middleware, bindowanie i walidacja żądań, odpowiedzi JSON oraz bezpieczne zamykanie serwera. - 100chi
Wspiera budowę REST API i usług webowych w Go z routerem chi na net/http: middleware, grupy tras, parametry URL, sub-routery i migracja z gorilla/mux lub ServeMux. - 100rust-web
Projektuje i wdraża produkcyjne serwisy HTTP w Rust, np. w axum lub Actix Web: routing, ekstraktory, middleware, timeouty i graceful shutdown. - 100golang-api-server
Buduje usługi HTTP, REST API i middleware w Go.