Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

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.

Repozytorium
golang-skills ↗
Licencja
Apache-2.0
Ostatnia zmiana repozytorium
27.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
4
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 27.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

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

  1. Resource Routing
  2. Routing (Go 1.22+)
  3. Handler Shape
  4. Middleware
  5. Server Construction
  6. Clients
  7. Related Skills
Sekcje z nagłówków SKILL.md, w oryginale · 297 linii, 2 023 słów
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.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.