Функции пакета net/http языка Go

Функции пакета http для реализации HTTP-клиента и сервера.
Tags:
Categories:

func CanonicalHeaderKey

func CanonicalHeaderKey(s string) string

CanonicalHeaderKey возвращает канонический формат заголовка. Преобразует первую букву и буквы после дефиса в верхний регистр, остальные - в нижний. Например, “accept-encoding” → “Accept-Encoding”. Если s содержит пробелы или недопустимые символы, возвращается без изменений.

func DetectContentType

func DetectContentType(data []byte) string

DetectContentType определяет Content-Type данных по алгоритму https://mimesniff.spec.whatwg.org/. Анализирует первые 512 байт. Всегда возвращает валидный MIME-тип, по умолчанию “application/octet-stream”.

func Error

func Error(w ResponseWriter, error string, code int)

Error отправляет ответ с указанным HTTP-кодом и текстом ошибки. Устанавливает заголовки:

  • Удаляет Content-Length
  • Content-Type: “text/plain; charset=utf-8”
  • X-Content-Type-Options: “nosniff”

func Handle

func Handle(pattern string, handler Handler)

Регистрирует обработчик для шаблона в DefaultServeMux.

Пример 
package main

import (
	"fmt"
	"log"
	"net/http"
	"sync"
)

type countHandler struct {
	mu sync.Mutex // guards n
	n  int
}

func (h *countHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
	h.mu.Lock()
	defer h.mu.Unlock()
	h.n++
	fmt.Fprintf(w, "count is %d\n", h.n)
}

func main() {
	http.Handle("/count", new(countHandler))
	log.Fatal(http.ListenAndServe(":8080", nil))
}

func HandleFunc

func HandleFunc(pattern string, handler func(ResponseWriter, *Request))

Регистрирует функцию-обработчик для шаблона в DefaultServeMux.

Пример 
package main

import (
	"io"
	"log"
	"net/http"
)

func main() {
	h1 := func(w http.ResponseWriter, _ *http.Request) {
		io.WriteString(w, "Hello from a HandleFunc #1!\n")
	}
	h2 := func(w http.ResponseWriter, _ *http.Request) {
		io.WriteString(w, "Hello from a HandleFunc #2!\n")
	}

	http.HandleFunc("/", h1)
	http.HandleFunc("/endpoint", h2)

	log.Fatal(http.ListenAndServe(":8080", nil))
}

func ListenAndServe

func ListenAndServe(addr string, handler Handler) error

Запускает HTTP-сервер на указанном адресе. Если handler=nil, используется DefaultServeMux.

Пример 
package main

import (
	"io"
	"log"
	"net/http"
)

func main() {
	// Hello world, the web server

	helloHandler := func(w http.ResponseWriter, req *http.Request) {
		io.WriteString(w, "Hello, world!\n")
	}

	http.HandleFunc("/hello", helloHandler)
	log.Fatal(http.ListenAndServe(":8080", nil))
}

func ListenAndServeTLS

func ListenAndServeTLS(addr, certFile, keyFile string, handler Handler) error

Аналогично ListenAndServe, но для HTTPS-соединений. Требует сертификат и приватный ключ.

Пример 
package main

import (
	"io"
	"log"
	"net/http"
)

func main() {
	http.HandleFunc("/", func(w http.ResponseWriter, req *http.Request) {
		io.WriteString(w, "Hello, TLS!\n")
	})

	// One can use generate_cert.go in crypto/tls to generate cert.pem and key.pem.
	log.Printf("About to listen on 8443. Go to https://127.0.0.1:8443/")
	err := http.ListenAndServeTLS(":8443", "cert.pem", "key.pem", nil)
	log.Fatal(err)
}

func MaxBytesReader

func MaxBytesReader(w ResponseWriter, r io.ReadCloser, n int64) io.ReadCloser

Ограничивает размер тела запроса. В отличие от io.LimitReader:

  • Возвращает ReadCloser
  • При превышении лимита возвращает ошибку *MaxBytesError
  • Закрывает исходный reader при вызове Close

func NotFound

func NotFound(w ResponseWriter, r *Request)

Отправляет ответ с HTTP 404.

func ParseHTTPVersion

func ParseHTTPVersion(vers string) (major, minor int, ok bool)

Разбирает строку версии HTTP (например, “HTTP/1.1” → (1, 1, true)).

func ParseTime

func ParseTime(text string) (t time.Time, err error)

Разбирает временную метку из заголовка, поддерживая три формата: TimeFormat, RFC850 и ANSIC.

func ProxyFromEnvironment

func ProxyFromEnvironment(req *Request) (*url.URL, error)

ProxyFromEnvironment возвращает URL прокси-сервера для указанного запроса на основе переменных окружения:

  • HTTP_PROXY/https_proxy - для HTTP-запросов
  • HTTPS_PROXY/https_proxy - для HTTPS-запросов
  • NO_PROXY/no_proxy - исключения из проксирования

Форматы значений:

  • Полный URL (http://proxy.example.com:8080)
  • host:port (подразумевается схема http)

Возвращаемые значения:

  • Если прокси не задан или запрос исключен через NO_PROXY → nil, nil
  • При некорректном формате → ошибка
  • Для localhost (с портом или без) → nil, nil (специальный случай)

Примеры использования:

proxyUrl, err := http.ProxyFromEnvironment(req)
if err != nil {
    // обработка ошибки конфигурации прокси
}
if proxyUrl != nil {
    // настроить транспорт с этим прокси
}

Особенности:

  1. Автоматически выбирает переменную окружения по схеме запроса
  2. Учитывает исключения в NO_PROXY
  3. Всегда пропускает запросы к localhost
  4. Поддерживает оба регистра переменных (UPPER и lower case)

func ProxyURL

func ProxyURL(fixedURL *url.URL) func(*Request) (*url.URL, error)

Возвращает функцию прокси, всегда возвращающую указанный URL.

func Redirect

func Redirect(w ResponseWriter, r *Request, url string, code int)

Перенаправляет запрос на указанный URL (может быть относительным путем). Код ответа должен быть в диапазоне 3xx (обычно 301, 302 или 303). Если Content-Type не установлен, автоматически добавляет “text/html; charset=utf-8” и простой HTML-ответ. Установка любого значения Content-Type отключает это поведение.

func Serve

func Serve(l net.Listener, handler Handler) error

Принимает входящие HTTP-соединения через listener, создавая новую горутину для каждого соединения. Если handler=nil, используется DefaultServeMux. Поддержка HTTP/2 требует TLS-соединений с “h2” в Config.NextProtos. Всегда возвращает non-nil ошибку.

func ServeContent

func ServeContent(w ResponseWriter, req *Request, name string, modtime time.Time, content io.ReadSeeker)

Отвечает на запрос содержимым из ReadSeeker с поддержкой:

  • Range-запросов
  • Заголовков If-Match/If-None-Match
  • If-Modified-Since/If-Unmodified-Since

Автоматически определяет Content-Type (по расширению файла или через DetectContentType). Использует modtime для Last-Modified и проверки If-Modified-Since. Требует работающий Seek() для определения размера.

func ServeFile

func ServeFile(w ResponseWriter, r *Request, name string)

Отправляет содержимое файла или директории. Особенности:

  • Отклоняет пути с “..” (защита от traversal-атак)
  • Перенаправляет запросы к “/index.html” на родительский каталог
  • Использует только параметр name (игнорирует r.URL.Path)
  • Относительные пути разрешаются от текущего каталога

func ServeFileFS

func ServeFileFS(w ResponseWriter, r *Request, fsys fs.FS, name string)

Отправляет содержимое указанного файла или директории из файловой системы fsys в ответ на запрос. Файлы в fsys должны реализовывать интерфейс io.Seeker.

Меры предосторожности:

  1. Если имя (name) формируется из пользовательского ввода, его необходимо санировать перед вызовом
  2. Автоматически отклоняет запросы с “..” в r.URL.Path (защита от path traversal)
  3. Специальный случай: перенаправляет запросы, оканчивающиеся на “/index.html”, на путь без этого суффикса

Важно: выбор файла/директории осуществляется только по параметру name, r.URL.Path игнорируется (кроме двух указанных случаев).

func ServeTLS

func ServeTLS(l net.Listener, handler Handler, certFile, keyFile string) error

Принимает входящие HTTPS-соединения через listener l, создавая новую горутину для обработки каждого соединения. Требования:

  • Если handler не указан (nil), используется DefaultServeMux
  • Необходимо указать файлы сертификата (certFile) и приватного ключа (keyFile)
  • Для цепочки сертификатов certFile должен содержать: серверный сертификат, промежуточные и корневой CA

Особенности:

  • Всегда возвращает non-nil ошибку
  • Для корректной работы требуется правильная настройка TLS

Технические детали:

  1. Для ServeFileFS:

    • Работает с абстрактной файловой системой (fs.FS)
    • Требуется поддержка Seek() для обработки Range-запросов
    • Поведение с “index.html” аналогично классическим веб-серверам

  2. Для ServeTLS:

    • Автоматически активирует HTTP/2 при поддержке
    • Рекомендуется использовать современные параметры шифрования
    • Для production-среды следует использовать полную цепочку сертификатов

func SetCookie

func SetCookie(w ResponseWriter, cookie *Cookie)

Добавляет Set-Cookie заголовок в ответ. Некорректные cookie могут игнорироваться.

func StatusText

func StatusText(code int) string

Возвращает текстовое описание HTTP-статуса. Для неизвестных кодов возвращает пустую строку.