...

パッケージ http

概要 ▾

http パッケージは,HTTP クライアントとサーバを実装します。

Get,Head,Post,PostForm は HTTP (または HTTPS) リクエストを行います。

resp, err := http.Get("http://example.com/")
...
resp, err := http.Post("http://example.com/upload", "image/jpeg", &buf)
...
resp, err := http.PostForm("http://example.com/form",
	url.Values{"key": {"Value"}, "id": {"123"}})

終わったら,クライアントはレスポンスボディを閉じる必要があります。

resp, err := http.Get("http://example.com/")
if err != nil {
	// handle error
}
defer resp.Body.Close()
body, err := ioutil.ReadAll(resp.Body)
// ...

HTTP クライアントヘッダー,リダイレクトポリシー,およびその他の設定を制御するには,Client を作成します。

client := &http.Client{
	CheckRedirect: redirectPolicyFunc,
}

resp, err := client.Get("http://example.com")
// ...

req, err := http.NewRequest("GET", "http://example.com", nil)
// ...
req.Header.Add("If-None-Match", `W/"wyzzy"`)
resp, err := client.Do(req)
// ...

プロキシ,TLS設定,キープアライブ,圧縮,およびその他の設定を制御するために,Transport を作成します。

tr := &http.Transport{
	MaxIdleConns:       10,
	IdleConnTimeout:    30 * time.Second,
	DisableCompression: true,
}
client := &http.Client{Transport: tr}
resp, err := client.Get("https://example.com")

Client と Transport は複数のゴルーチンによる平行使用に対して安全であり,効率化のために一度だけ作成して再利用すべきです。

ListenAndServe は与えられたアドレスとハンドラで HTTP サーバを起動します。 ハンドラは通常 nil です。これはDefaultServeMuxを使用することを意味します。 Handle と HandleFunc で DefaultServeMux にハンドラを追加します。

http.Handle("/foo", fooHandler)

http.HandleFunc("/bar", func(w http.ResponseWriter, r *http.Request) {
	fmt.Fprintf(w, "Hello, %q", html.EscapeString(r.URL.Path))
})

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

カスタム Server を作成することで,サーバーの動作をさらに制御できます。

s := &http.Server{
	Addr:           ":8080",
	Handler:        myHandler,
	ReadTimeout:    10 * time.Second,
	WriteTimeout:   10 * time.Second,
	MaxHeaderBytes: 1 << 20,
}
log.Fatal(s.ListenAndServe())

Go 1.6 以降, HTTPS を使用する場合, http パッケージは HTTP/2 プロトコルを透過的にサポートします。 HTTP/2 を無効にする必要があるプログラムは, Transport.TLSNextProto (クライアント用) または Server.TLSNextProto (サーバー用) を nil でない空のマップに設定することで無効にできます。 あるいは,以下の GODEBUG 環境変数が現在サポートされています。

GODEBUG=http2client=0  # disable HTTP/2 client support
GODEBUG=http2server=0  # disable HTTP/2 server support
GODEBUG=http2debug=1   # enable verbose HTTP/2 debug logs
GODEBUG=http2debug=2   # ... even more verbose, with frame dumps

GODEBUG 変数は Go の API 互換性の保証に入っていません。 HTTP/2 サポートを無効にする前に問題があれば報告してください。 https://golang.org/s/http2bug

http パッケージの Transport と Server は両方とも,簡単な設定で HTTP/2 サポートが自動的に有効になります。 より複雑な設定で HTTP/2 を有効にする,下位レベルの HTTP/2 機能を使う,あるいは Go の新しいバージョンの http2 パッケージを使うには, "golang.org/x/net/http2" を直接インポートし,ConfigureTransport と ConfigureServer の関数を使います。 golang.org/x/net/http2 パッケージを使用しての HTTP/2 手動設定は, net/http パッケージに組み込まれている HTTP/2 よりも優先されます。

目次 ▾

定数
変数
func CanonicalHeaderKey(s string) string
func DetectContentType(data []byte) string
func Error(w ResponseWriter, error string, code int)
func Handle(pattern string, handler Handler)
func HandleFunc(pattern string, handler func(ResponseWriter, *Request))
func ListenAndServe(addr string, handler Handler) error
func ListenAndServeTLS(addr, certFile, keyFile string, handler Handler) error
func MaxBytesReader(w ResponseWriter, r io.ReadCloser, n int64) io.ReadCloser
func NotFound(w ResponseWriter, r *Request)
func ParseHTTPVersion(vers string) (major, minor int, ok bool)
func ParseTime(text string) (t time.Time, err error)
func ProxyFromEnvironment(req *Request) (*url.URL, error)
func ProxyURL(fixedURL *url.URL) func(*Request) (*url.URL, error)
func Redirect(w ResponseWriter, r *Request, url string, code int)
func Serve(l net.Listener, handler Handler) error
func ServeContent(w ResponseWriter, req *Request, name string, modtime time.Time, content io.ReadSeeker)
func ServeFile(w ResponseWriter, r *Request, name string)
func ServeTLS(l net.Listener, handler Handler, certFile, keyFile string) error
func SetCookie(w ResponseWriter, cookie *Cookie)
func StatusText(code int) string
type Client
    func (c *Client) CloseIdleConnections()
    func (c *Client) Do(req *Request) (*Response, error)
    func (c *Client) Get(url string) (resp *Response, err error)
    func (c *Client) Head(url string) (resp *Response, err error)
    func (c *Client) Post(url, contentType string, body io.Reader) (resp *Response, err error)
    func (c *Client) PostForm(url string, data url.Values) (resp *Response, err error)
type CloseNotifier
type ConnState
    func (c ConnState) String() string
type Cookie
    func (c *Cookie) String() string
type CookieJar
type Dir
    func (d Dir) Open(name string) (File, error)
type File
type FileSystem
type Flusher
type Handler
    func FileServer(root FileSystem) Handler
    func NotFoundHandler() Handler
    func RedirectHandler(url string, code int) Handler
    func StripPrefix(prefix string, h Handler) Handler
    func TimeoutHandler(h Handler, dt time.Duration, msg string) Handler
type HandlerFunc
    func (f HandlerFunc) ServeHTTP(w ResponseWriter, r *Request)
type Header
    func (h Header) Add(key, value string)
    func (h Header) Clone() Header
    func (h Header) Del(key string)
    func (h Header) Get(key string) string
    func (h Header) Set(key, value string)
    func (h Header) Write(w io.Writer) error
    func (h Header) WriteSubset(w io.Writer, exclude map[string]bool) error
type Hijacker
type ProtocolError
    func (pe *ProtocolError) Error() string
type PushOptions
type Pusher
type Request
    func NewRequest(method, url string, body io.Reader) (*Request, error)
    func NewRequestWithContext(ctx context.Context, method, url string, body io.Reader) (*Request, error)
    func ReadRequest(b *bufio.Reader) (*Request, error)
    func (r *Request) AddCookie(c *Cookie)
    func (r *Request) BasicAuth() (username, password string, ok bool)
    func (r *Request) Clone(ctx context.Context) *Request
    func (r *Request) Context() context.Context
    func (r *Request) Cookie(name string) (*Cookie, error)
    func (r *Request) Cookies() []*Cookie
    func (r *Request) FormFile(key string) (multipart.File, *multipart.FileHeader, error)
    func (r *Request) FormValue(key string) string
    func (r *Request) MultipartReader() (*multipart.Reader, error)
    func (r *Request) ParseForm() error
    func (r *Request) ParseMultipartForm(maxMemory int64) error
    func (r *Request) PostFormValue(key string) string
    func (r *Request) ProtoAtLeast(major, minor int) bool
    func (r *Request) Referer() string
    func (r *Request) SetBasicAuth(username, password string)
    func (r *Request) UserAgent() string
    func (r *Request) WithContext(ctx context.Context) *Request
    func (r *Request) Write(w io.Writer) error
    func (r *Request) WriteProxy(w io.Writer) error
type Response
    func Get(url string) (resp *Response, err error)
    func Head(url string) (resp *Response, err error)
    func Post(url, contentType string, body io.Reader) (resp *Response, err error)
    func PostForm(url string, data url.Values) (resp *Response, err error)
    func ReadResponse(r *bufio.Reader, req *Request) (*Response, error)
    func (r *Response) Cookies() []*Cookie
    func (r *Response) Location() (*url.URL, error)
    func (r *Response) ProtoAtLeast(major, minor int) bool
    func (r *Response) Write(w io.Writer) error
type ResponseWriter
type RoundTripper
    func NewFileTransport(fs FileSystem) RoundTripper
type SameSite
type ServeMux
    func NewServeMux() *ServeMux
    func (mux *ServeMux) Handle(pattern string, handler Handler)
    func (mux *ServeMux) HandleFunc(pattern string, handler func(ResponseWriter, *Request))
    func (mux *ServeMux) Handler(r *Request) (h Handler, pattern string)
    func (mux *ServeMux) ServeHTTP(w ResponseWriter, r *Request)
type Server
    func (srv *Server) Close() error
    func (srv *Server) ListenAndServe() error
    func (srv *Server) ListenAndServeTLS(certFile, keyFile string) error
    func (srv *Server) RegisterOnShutdown(f func())
    func (srv *Server) Serve(l net.Listener) error
    func (srv *Server) ServeTLS(l net.Listener, certFile, keyFile string) error
    func (srv *Server) SetKeepAlivesEnabled(v bool)
    func (srv *Server) Shutdown(ctx context.Context) error
type Transport
    func (t *Transport) CancelRequest(req *Request)
    func (t *Transport) Clone() *Transport
    func (t *Transport) CloseIdleConnections()
    func (t *Transport) RegisterProtocol(scheme string, rt RoundTripper)
    func (t *Transport) RoundTrip(req *Request) (*Response, error)

パッケージファイル

client.go clone.go cookie.go doc.go filetransport.go fs.go h2_bundle.go header.go http.go jar.go method.go request.go response.go roundtrip.go server.go sniff.go socks_bundle.go status.go transfer.go transport.go

定数

一般的な HTTP メソッド

特に明記しない限り,これらは RFC 7231 のセクション 4.3 で定義されています。

const (
    MethodGet     = "GET"
    MethodHead    = "HEAD"
    MethodPost    = "POST"
    MethodPut     = "PUT"
    MethodPatch   = "PATCH" // RFC 5789
    MethodDelete  = "DELETE"
    MethodConnect = "CONNECT"
    MethodOptions = "OPTIONS"
    MethodTrace   = "TRACE"
)

IANA に登録されている HTTP ステータスコード。 https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml を参照してください。

const (
    StatusContinue           = 100 // RFC 7231, 6.2.1
    StatusSwitchingProtocols = 101 // RFC 7231, 6.2.2
    StatusProcessing         = 102 // RFC 2518, 10.1
    StatusEarlyHints         = 103 // RFC 8297

    StatusOK                   = 200 // RFC 7231, 6.3.1
    StatusCreated              = 201 // RFC 7231, 6.3.2
    StatusAccepted             = 202 // RFC 7231, 6.3.3
    StatusNonAuthoritativeInfo = 203 // RFC 7231, 6.3.4
    StatusNoContent            = 204 // RFC 7231, 6.3.5
    StatusResetContent         = 205 // RFC 7231, 6.3.6
    StatusPartialContent       = 206 // RFC 7233, 4.1
    StatusMultiStatus          = 207 // RFC 4918, 11.1
    StatusAlreadyReported      = 208 // RFC 5842, 7.1
    StatusIMUsed               = 226 // RFC 3229, 10.4.1

    StatusMultipleChoices  = 300 // RFC 7231, 6.4.1
    StatusMovedPermanently = 301 // RFC 7231, 6.4.2
    StatusFound            = 302 // RFC 7231, 6.4.3
    StatusSeeOther         = 303 // RFC 7231, 6.4.4
    StatusNotModified      = 304 // RFC 7232, 4.1
    StatusUseProxy         = 305 // RFC 7231, 6.4.5

    StatusTemporaryRedirect = 307 // RFC 7231, 6.4.7
    StatusPermanentRedirect = 308 // RFC 7538, 3

    StatusBadRequest                   = 400 // RFC 7231, 6.5.1
    StatusUnauthorized                 = 401 // RFC 7235, 3.1
    StatusPaymentRequired              = 402 // RFC 7231, 6.5.2
    StatusForbidden                    = 403 // RFC 7231, 6.5.3
    StatusNotFound                     = 404 // RFC 7231, 6.5.4
    StatusMethodNotAllowed             = 405 // RFC 7231, 6.5.5
    StatusNotAcceptable                = 406 // RFC 7231, 6.5.6
    StatusProxyAuthRequired            = 407 // RFC 7235, 3.2
    StatusRequestTimeout               = 408 // RFC 7231, 6.5.7
    StatusConflict                     = 409 // RFC 7231, 6.5.8
    StatusGone                         = 410 // RFC 7231, 6.5.9
    StatusLengthRequired               = 411 // RFC 7231, 6.5.10
    StatusPreconditionFailed           = 412 // RFC 7232, 4.2
    StatusRequestEntityTooLarge        = 413 // RFC 7231, 6.5.11
    StatusRequestURITooLong            = 414 // RFC 7231, 6.5.12
    StatusUnsupportedMediaType         = 415 // RFC 7231, 6.5.13
    StatusRequestedRangeNotSatisfiable = 416 // RFC 7233, 4.4
    StatusExpectationFailed            = 417 // RFC 7231, 6.5.14
    StatusTeapot                       = 418 // RFC 7168, 2.3.3
    StatusMisdirectedRequest           = 421 // RFC 7540, 9.1.2
    StatusUnprocessableEntity          = 422 // RFC 4918, 11.2
    StatusLocked                       = 423 // RFC 4918, 11.3
    StatusFailedDependency             = 424 // RFC 4918, 11.4
    StatusTooEarly                     = 425 // RFC 8470, 5.2.
    StatusUpgradeRequired              = 426 // RFC 7231, 6.5.15
    StatusPreconditionRequired         = 428 // RFC 6585, 3
    StatusTooManyRequests              = 429 // RFC 6585, 4
    StatusRequestHeaderFieldsTooLarge  = 431 // RFC 6585, 5
    StatusUnavailableForLegalReasons   = 451 // RFC 7725, 3

    StatusInternalServerError           = 500 // RFC 7231, 6.6.1
    StatusNotImplemented                = 501 // RFC 7231, 6.6.2
    StatusBadGateway                    = 502 // RFC 7231, 6.6.3
    StatusServiceUnavailable            = 503 // RFC 7231, 6.6.4
    StatusGatewayTimeout                = 504 // RFC 7231, 6.6.5
    StatusHTTPVersionNotSupported       = 505 // RFC 7231, 6.6.6
    StatusVariantAlsoNegotiates         = 506 // RFC 2295, 8.1
    StatusInsufficientStorage           = 507 // RFC 4918, 11.5
    StatusLoopDetected                  = 508 // RFC 5842, 7.2
    StatusNotExtended                   = 510 // RFC 2774, 7
    StatusNetworkAuthenticationRequired = 511 // RFC 6585, 6
)

DefaultMaxHeaderBytes は, HTTP リクエスト内のヘッダーの最大許容サイズです。これは Server.MaxHeaderBytes を設定することで上書きできます。

const DefaultMaxHeaderBytes = 1 << 20 // 1 MB

DefaultMaxIdleConnsPerHost は, Transport の MaxIdleConnsPerHost のデフォルト値です。

const DefaultMaxIdleConnsPerHost = 2

TimeFormat は, HTTP ヘッダーで時間を生成するときに使用する時間形式です。 time.RFC1123 と似ていますが, GMT をタイムゾーンとしてハードコードしています。正しいフォーマットを生成するには,フォーマット中の時間が UTC でなければなりません。

この時刻フォーマットの解析については, ParseTime を参照してください。

const TimeFormat = "Mon, 02 Jan 2006 15:04:05 GMT"

TrailerPrefix は ResponseWriter.Header マップキーのマジックプレフィックスで,存在する場合,マップエントリは実際には応答トレーラー用であり,応答ヘッダー用ではないことを示します。 ServeHTTP 呼び出しが終了し,値がトレーラーに送信された後に接頭部が除去されます。

このメカニズムは,ヘッダーが書き込まれる前に知られていないトレーラーのみを対象としています。ヘッダーが書き込まれる前にトレーラーのセットが固定されているか既知の場合は,通常の Go トレーラーのメカニズムが優先されます。

https://golang.org/pkg/net/http/#ResponseWriter
https://golang.org/pkg/net/http/#example_ResponseWriter_trailers
const TrailerPrefix = "Trailer:"

変数

var (
    // ErrNotSupported は, HTTP/2 プッシュサポートが利用できないことを示すために, Pusher 実装の Push メソッドによって返されます。
    ErrNotSupported = &ProtocolError{"feature not supported"}

    // 非推奨 : ErrUnexpectedTrailer は, net/http パッケージ内のものから返されることはもうありません。呼び出し元はこの変数とエラーを比較しないでください。
    ErrUnexpectedTrailer = &ProtocolError{"trailer header without chunked transfer encoding"}

    // ErrMissingBoundary は,リクエストの Content-Type に "boundary" パラメータが含まれていない場合に Request.MultipartReader によって返されます。
    ErrMissingBoundary = &ProtocolError{"no multipart boundary param in Content-Type"}

    // ErrNotMultipart は,リクエストの Content-Type が multipart/form-data ではない場合に Request.MultipartReader によって返されます。
    ErrNotMultipart = &ProtocolError{"request Content-Type isn't multipart/form-data"}

    // 非推奨 : ErrHeaderTooLong は, net/http パッケージ内のものから返されることはもうありません。呼び出し元はこの変数とエラーを比較しないでください。
    ErrHeaderTooLong = &ProtocolError{"header too long"}

    // 非推奨 : ErrShortBody は, net/http パッケージ内のものから返されることはもうありません。呼び出し元はこの変数とエラーを比較しないでください。
    ErrShortBody = &ProtocolError{"entity body too short"}

    // 非推奨 : ErrMissingContentLength は, net/http パッケージ内の何からも返されなくなりました。呼び出し元はこの変数とエラーを比較しないでください。
    ErrMissingContentLength = &ProtocolError{"missing ContentLength in HEAD response"}
)

HTTP サーバーによって使用されたエラー。

var (
    // ErrWodyNotAllowed は,HTTP メソッドまたは応答コードでボディが許可されていない場合, ResponseWriter.Write 呼び出しによって返されます。
    ErrBodyNotAllowed = errors.New("http: request method or response status code does not allow body")

    // ErrHijacked は,基になる接続が Hijacker インターフェイスを使用してハイジャックされた場合, ResponseWriter.Write 呼び出しによって返されます。ハイジャックされた接続での 0 バイトの書き込みは,他の副作用なしに ErrHijacked を返します。
    ErrHijacked = errors.New("http: connection has been hijacked")

    // ErrContentLength は, Handler が宣言されたサイズで Content-Length 応答ヘッダを設定し,宣言されたよりも多くのバイト数を書き込もうとしたときに ResponseWriter.Write 呼び出しによって返されます。
    ErrContentLength = errors.New("http: wrote more than the declared Content-Length")

    // 非推奨 : ErrWriteAfterFlush は, net/http パッケージ内のものから返されることはもうありません。呼び出し元はこの変数とエラーを比較しないでください。
    ErrWriteAfterFlush = errors.New("unused")
)
var (
    // ServerContextKey はコンテキストキーです。 context.WithValue を持つ HTTP ハンドラーで使用して,ハンドラーを起動したサーバーにアクセスできます。関連付けられた値は *Server 型になります。
    ServerContextKey = &contextKey{"http-server"}

    // LocalAddrContextKey はコンテキストキーです。 HTTP ハンドラーで context.WithValue を使用して,接続が到着したローカルアドレスにアクセスすることができます。関連付けられた値は net.Addr 型になります。
    LocalAddrContextKey = &contextKey{"local-addr"}
)

DefaultClient はデフォルトの Client で, Get, Head, Post で使用されます。

var DefaultClient = &Client{}

DefaultServeMux is the default ServeMux used by Serve.

var DefaultServeMux = &defaultServeMux

ErrAbortHandler は,ハンドラを中止するためのセンチネルパニック値です。 ServeHTTP からのパニックがクライアントへの応答を中止する間, ErrAbortHandler とのパニックはサーバーのエラーログへのスタックトレースのロギングも抑制します。

var ErrAbortHandler = errors.New("net/http: abort Handler")

ボディが閉じられた後にリクエストボディまたはレスポンスボディを読み込むと, ErrBodyReadAfterClose が返されます。これは通常, HTTP ハンドラがその ResponseWriter に対して WriteHeader または Write を呼び出した後にボディが読み取られるときに発生します。

var ErrBodyReadAfterClose = errors.New("http: invalid Read on closed Body")

ErrHandlerTimeoutisreturnedonResponseWriterWritecallsinhandlerswhichhavetimedout.

var ErrHandlerTimeout = errors.New("http: Handler timeout")

ErrLineTooLong は,不正な形式のチャンクエンコーディングでリクエストボディまたはレスポンスボディを読み取るときに返されます。

var ErrLineTooLong = internal.ErrLineTooLong

ErrMissingFile は,指定されたファイルフィールド名がリクエストに存在しないかファイルフィールドではない場合, FormFile によって返されます。

var ErrMissingFile = errors.New("http: no such file")

ErrNoCookie が Cookie が見つからない場合, Request の Cookie メソッドによって返されます。

var ErrNoCookie = errors.New("http: named cookie not present")

ErrNoLocation は,Location ヘッダーが存在しない場合,Response の Location メソッドによって返されます。

var ErrNoLocation = errors.New("http: no Location header in response")

ErrServerClosedisreturnedbytheServer'sServe,ServeTLS,ListenAndServe,andListenAndServeTLSmethodsafteracalltoShutdownorClose.

var ErrServerClosed = errors.New("http: Server closed")

ErrSkipAltProtocol は, Transport.RegisterProtocol によって定義されたセンチネルエラー値です。

var ErrSkipAltProtocol = errors.New("net/http: skip alternate protocol")

ErrUseLastResponse は Client.CheckRedirect フックによって返され,リダイレクトの処理方法を制御します。返された場合,次のリクエストは送信されず,最新のレスポンスがボディを閉じずに返されます。

var ErrUseLastResponse = errors.New("net/http: use last response")

NoBody は,バイト数のない io.ReadCloser です。 Read は常に EOF を返し, Close は常に nil を返します。 リクエストが 0 バイトであることを明示的に通知するために,発信クライアントリクエストで使用できます。 しかしながら,代わりの方法は単に Request.Body を nil に設定することです。

var NoBody = noBody{}

func CanonicalHeaderKey

func CanonicalHeaderKey(s string) string

CanonicalHeaderKey は,ヘッダーキー s の正規形式を返します。 正規化は,最初の文字とハイフンに続く文字を大文字に変換します。 残りは小文字に変換されます。 たとえば, "accept-encoding" の正規のキーは "Accept-Encoding" です。 s に空白または無効なヘッダーフィールドバイトが含まれている場合は,変更なしで返されます。

func DetectContentType

func DetectContentType(data []byte) string

DetectContentType は https://mimesniff.spec.whatwg.org/ で説明されているアルゴリズムを実装して, data の Content-Type を判別します。 最大 512 バイトのデータしか考慮しません。 DetectContentType は常に有効な MIME タイプを返します。 具体的なものを特定できない場合は, "application/octet-stream" を返します。

func Error

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

Error は指定されたエラーメッセージと HTTP コードでリクエストに応答します。それ以外の場合はリクエストを終了しません。呼び出し側は,これ以上 w への書き込みが行われないようにする必要があります。エラーメッセージはプレーンテキストでなければなりません。

func Handle

func Handle(pattern string, handler Handler)

HandleregistersthehandlerforthegivenpatternintheDefaultServeMux.The ドキュメント ation for ServeMux explains how patterns are matched.

コード:

package http_test

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

type countHandler struct {
    mu sync.Mutex // 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 ExampleHandle() {
    http.Handle("/count", new(countHandler))
    log.Fatal(http.ListenAndServe(":8080", nil))
}

func HandleFunc

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

HandleFuncregistersthehandlerfunctionforthegivenpatternintheDefaultServeMux.The ドキュメント ation for ServeMux explains how patterns are matched.

コード:

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

ListenAndServelistensontheTCPnetworkaddressaddrandthencallsServewithhandlertohandlerequestsonincomingconnections.AcceptedconnectionsareconfiguredtoenableTCPkeep-alives.

The handler is typically nil, in which case the DefaultServeMux is used.

ListenAndServe always returns a non-nil error.

コード:

// Hello world, Web サーバー

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

ListenAndServeTLSactsidenticallytoListenAndServe,exceptthatitexpectsHTTPSconnections.Additionally, ファイル scontainingacertificateandmatchingprivatekeyfortheservermustbeprovided.Ifthecertificateissignedbyacertificateauthority,thecertFileshouldbetheconcatenationoftheserver'scertificate,anyintermediates,andtheCA'scertificate.

コード:

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

// cert.pem と key.pem を生成するために crypto/tls の generate_cert.go を使うことができます。
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

MaxBytesReader は io.LimitReader に似ていますが,着信リクエストボディのサイズを制限するためのものです。 io.LimitReader とは対照的に, MaxBytesReader の結果は ReadCloser であり,制限を超えた Read に対して非 EOF エラーを返し, Close メソッドが呼び出されたときに基になるリーダーを閉じます。

MaxBytesReader は,クライアントが誤ってまたは悪意を持って大量のリクエストを送信したり,サーバーリソースを無駄にしたりするのを防ぎます。

func NotFound

func NotFound(w ResponseWriter, r *Request)

NotFound は HTTP 404 not found エラーでリクエストに応答します。

func ParseHTTPVersion

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

ParseHTTPVersion は, HTTP バージョン文字列を解析します。 "HTTP/1.0" は (1, 0, true) を返します。

func ParseTime 1.1

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

ParseTime (時間をパースする) は, HTTP/1.1 で許可されている 3 つのフォーマット (TimeFormat, time.RFC850, time.ANSIC) のそれぞれを試して,タイムヘッダー (Date: ヘッダーなど) をパースします。

func ProxyFromEnvironment

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

ProxyFromEnvironment は,環境変数 HTTP_PROXY, HTTPS_PROXY ,および NO_PROXY (またはその小文字バージョン) で示されるように,特定のリクエストに使用するプロキシの URL を返します。 https リクエストでは, HTTPS_PROXY が HTTP_PROXY よりも優先されます。

環境値は,完全な URL または "host[:port]" のどちらでもかまいません。この場合, "http" スキームが想定されます。値が異なる形式の場合はエラーが返されます。

環境にプロキシが定義されていない場合,または NO_PROXY で定義されているように,指定されたリクエストにプロキシを使用しない場合は, nil URL および nil エラーが返されます。

特別な場合として, req.URL.Host が "localhost" (ポート番号の有無にかかわらず) の場合, nil URL と nil エラーが返されます。

func ProxyURL

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

ProxyURL は常に同じ URL を返すプロキシ関数 (トランスポートで使用するため) を返します。

func Redirect

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

Redirect は, url へのリダイレクトを使用してリクエストに応答します。これは,リクエストパスに対する相対パスである可能性があります。

渡されたコードは 3xx の範囲内でなければならず,通常は StatusMovedPermanently, StatusFound または StatusSeeOther です。

Content-Type ヘッダーが設定されていない場合, Redirect はそれを "text/html; charset=utf-8" に設定し,小さな HTML ボディを書き込みます。 SettingtheContent-Typeheadertoanyvalue,includingnil,disablesthatbehavior.

func Serve

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

ServeacceptsincomingHTTPconnectionsonthelistenerl,creatinganewservicegoroutineforeach.Theservicegoroutinesreadrequestsandthencallhandlertoreplytothem.

The handler is typically nil, in which case the DefaultServeMux is used.

HTTP/2supportisonlyenablediftheListenerreturns*tls.Connconnectionsandtheywereconfiguredwith"h2"intheTLSConfig.NextProtos.

Serve always returns a non-nil error.

func ServeContent

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

ServeContent は,引数の ReadSeeker の内容を使用してリクエストに応答します。 io.Copy に対する ServeContent の主な利点は, Range リクエストを適切に処理し, MIME タイプを設定し, If-Match, If-Unmodified-Since, If-None-Match, If-Modified-Since, および If-Range リクエストを処理することです。

レスポンスの Content-Type ヘッダーが設定されていない場合, ServeContent は最初に name のファイル拡張子からタイプを推測し,それが失敗した場合は,コンテンツの最初のブロックを読み取って DetectContentType に渡します。 それ以外に name は使われません。 name は空にすることができ,レスポンスには決して送信されません。

modtime がゼロ時刻または UNIX エポックではない場合, ServeContent はそれをレスポンスの Last-Modified ヘッダーに含めます。 リクエストに If-Modified-Since ヘッダーが含まれている場合, ServeContent は modtime を使用してコンテンツを送信する必要があるかどうかを判断します。

content の Seek メソッドは機能する必要があります。 ServeContent は,コンテンツの最後にシークしてサイズを決定します。

呼び出し側が, RFC 7232 のセクション 2.3 に従ってフォーマットされた ETag ヘッダーを w に設定している場合, ServeContent はそれを使って, If-Match, If-None-Match, または If-Range でリクエストを処理します。

*os.File は io.ReadSeeker インターフェースを実装することに注意してください。

func ServeFile

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

ServeFile は,指定されたファイルまたはディレクトリの内容でリクエストに応答します。

引数のファイルまたはディレクトリ名が相対パスの場合, 現在のディレクトリからの相対パスとして解釈され,親ディレクトリに移動することがあります。 引数の name がユーザー入力から構成されている場合は, ServeFile を呼び出す前にサニタイズする必要があります。

予防措置として, ServeFile は r.URL.Path に ".." パス要素が含まれているリクエストを拒否します。 これは,サニタイズせずに r.URL.Path や filepath.Join を危険に使用し, その filepath.Join の結果を name 引数として使用する可能性のある呼び出し元から保護します。

別の特別な場合として, ServeFile は r.URL.Path が "/index.html" で終わるすべてのリクエストを, 最後の "index.html" を含めないパスにリダイレクトします。 このようなリダイレクトを回避するには,パスを変更するか ServeContent を使用してください。

これら 2 つの特別な場合を除いて, ServeFile は提供するファイルまたはディレクトリーの選択に r.URL.Path を使用しません。 name 引数で指定されたファイルまたはディレクトリだけが使用されます。

func ServeTLS 1.9

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

ServeTLSacceptsincomingHTTPSconnectionsonthelistenerl,creatinganewservicegoroutineforeach.Theservicegoroutinesreadrequestsandthencallhandlertoreplytothem.

The handler is typically nil, in which case the DefaultServeMux is used.

Additionally, ファイル scontainingacertificateandmatchingprivatekeyfortheservermustbeprovided.Ifthecertificateissignedbyacertificateauthority,thecertFileshouldbetheconcatenationoftheserver'scertificate,anyintermediates,andtheCA'scertificate.

ServeTLS always returns a non-nil error.

func SetCookie

func SetCookie(w ResponseWriter, cookie *Cookie)

SetCookie は,引数の ResponseWriter のヘッダーに Set-Cookie ヘッダーを追加します。引数のクッキーは有効な名前を持たなければなりません。無効なクッキーは黙って破棄されるかもしれません。

func StatusText

func StatusText(code int) string

StatusText は, HTTP ステータスコードのテキストを返します。 コードが不明な場合は空の文字列を返します。

type Client

Client は HTTP クライアントです。ゼロ値 (DefaultClient) は, DefaultTransport を使うクライアントで,使用可能です。

Client の Transport は通常,内部状態 (キャッシュされた TCP 接続) を持っているので,Client は必要に応じて作成されるのではなく再利用されるべきです。Client は複数のゴルーチンによる平行使用に対して安全です。

Client は RoundTripper (Transport など) よりも上位レベルであり,さらに Cookie やリダイレクトなどの HTTP の詳細を処理します。

リダイレクトに従うと,Client は最初のリクエストで設定されたすべてのヘッダを転送します。

• "Authorization", "WWW-Authenticate", "Cookie" などの機密性の高いヘッダーを信頼できないターゲットに転送する場合。これらのヘッダーは,サブドメインが一致しないあるいはイニシャルドメインが完全一致ではないドメインへのリダイレクトをたどるときに無視されます。たとえば, "foo.com" から "foo.com" または "sub.foo.com" へのリダイレクトは機密ヘッダーを転送しますが, "bar.com" へのリダイレクトは転送しません。

• "Cookie" ヘッダーを nil 以外の cookie Jar で転送するとき。 各リダイレクトは cookie jar の状態を変化させる可能性があるので, リダイレクトは最初のリクエストで設定された cookie を変更する可能性があります。 "Cookie" ヘッダを転送するとき,すべての変換されたクッキーは省略されます。 オリジンが一致すると仮定して, Jar は変換されたクッキーを更新された値で挿入することを期待します。 Jar が nil の場合,最初のクッキーは変更されずに転送されます。

type Client struct {
    // Transport は,個々の HTTP リクエストが行われるメカニズムを指定します。 nil の場合, DefaultTransport が使用されます。
    Transport RoundTripper

    // CheckRedirect はリダイレクトを処理するためのポリシーを指定します。 CheckRedirect が nil 以外の場合,クライアントは HTTP リダイレクトをたどる前にそれを呼び出します。引数 req と via は,次のリクエストとすでに行われたリクエストのうち,最も古いものから順に並べられます。 CheckRedirect がエラーを返す場合, Client の Get メソッドは, Request req を発行する代わりに,前の Response(Body を閉じた状態) と CheckRedirect のエラー (url.Error にラップされた状態) の両方を返します。特別な場合として, CheckRedirect が ErrUseLastResponse を返した場合,最新の応答は本体を閉じずに nil エラーと共に返されます。
    //
    // CheckRedirect が nil の場合,クライアントはデフォルトのポリシーを使用します。これは 10 回の連続したリクエストの後に停止することです。
    CheckRedirect func(req *Request, via []*Request) error

    // Jar はクッキージャーを指定します。
    //
    // Jar はすべてのアウトバウンドリクエストに関連するクッキーを挿入するために使用され,すべてのインバウンドレスポンスのクッキー値で更新されます。 Jar は,クライアントが従うすべてのリダイレクトについて調べられます。
    //
    // Jar が nil の場合, Cookie はリクエストに明示的に設定されている場合にのみ送信されます。
    Jar CookieJar

    // Timeout は,このクライアントによるリクエストの制限時間を指定します。タイムアウトには,接続時間,リダイレクト,および応答ボディの読み取りが含まれます。 Get, Head, Post ,または Do が戻った後もタイマーは動作し続け, Response.Body の読み取りを中断します。
    //
    // タイムアウトがゼロの場合は,タイムアウトしないことを意味します。
    //
    // Client は,リクエストのコンテキストが終了したかのように,内部のトランスポートへのリクエストを取り消します。
    //
    // For compatibility, the Client will also use the deprecated
    // CancelRequest method on Transport if found. New
    // RoundTripper implementations should use the Request's Context
    // for cancellation instead of implementing CancelRequest.
    Timeout time.Duration // Go 1.3
}

func (*Client) CloseIdleConnections 1.12

func (c *Client) CloseIdleConnections()

CloseIdleConnections は,以前のリクエストで以前接続され,現在は "キープアライブ" 状態でアイドル状態になっている, Transport 上の接続をすべて閉じます。現在使用中の接続を中断することはありません。

Client の Transport に CloseIdleConnections メソッドがない場合,このメソッドは何もしません。

func (*Client) Do

func (c *Client) Do(req *Request) (*Response, error)

Do は,クライアントで設定されているポリシー (リダイレクト, Cookie ,認証など) に従って, HTTP リクエストを送信し, HTTP レスポンスを返します。

クライアントポリシー (CheckRedirect など) ,または HTTP の通信に失敗した場合 (ネットワーク接続の問題など) が原因でエラーが返されます。 2xx 以外のステータスコードではエラーは発生しません。

返されたエラーが nil である場合, Response はユーザが閉じることが期待されている nil 以外の Body を含みます。 Body が EOF まで読み込まれずかつ閉じられない場合,Client 内部の RoundTripper (通常は Transport) は,その後の "キープアライブ" 要求のためにサーバーへの持続的 TCP 接続を再利用できない可能性があります。

リクエストボディが nil 以外の場合,エラーが発生した場合でも,内部の Transport によって閉じられます。

エラーが発生した場合,レスポンスは無視されます。 nil 以外のエラーを含む nil 以外の Response は, CheckRedirect が失敗した場合にのみ発生し,Response.Body はすでに閉じられています。

通常は, Do のかわりに Get, Post,または PostForm が使用されます。

サーバーがリダイレクトで応答した場合, Client は最初に CheckRedirect 関数を使用してリダイレクトに従うべきかどうかを判断します。許可されている場合, 301, 302 ,または 303 のリダイレクトにより,後続のリクエストは HTTP メソッド GET (または元のリクエストが HEAD の場合は HEAD) をボディなしで使用します。 307 または 308 リダイレクトは, Request.GetBody 関数が定義されていれば,元の HTTP メソッドとボディを保持します。 NewRequest 関数は,一般的な標準ライブラリのボディタイプに GetBody を自動的に設定します。

返されたエラーはすべて *url.Error 型になります。リクエストがタイムアウトまたはキャンセルされた場合, url.Error 値の Timeout メソッドは true を報告します。

func (*Client) Get

func (c *Client) Get(url string) (resp *Response, err error)

Get は指定された URL に GET を発行します。レスポンスが次のいずれかのリダイレクトコードである場合, Get は Client の CheckRedirect 関数を呼び出した後にリダイレクトに従います。

301 (永続的に移動)
302 (見つかった)
303 (その他を参照)
307 (一時的なリダイレクト)
308 (永続的なリダイレクト)

Client の CheckRedirect 関数が失敗した場合,または HTTP プロトコルエラーが発生した場合はエラーが返されます。 2xx 以外のレスポンスではエラーは発生しません。返されたエラーはすべて *url.Error 型になります。リクエストがタイムアウトまたはキャンセルされた場合, url.Error 値の Timeout メソッドは true を報告します。

err が nil の場合, resp は常に nil 以外の resp.Body を含みます。呼び出し元は,読み取りが終わったら resp.Body を閉じる必要があります。

カスタムヘッダでリクエストをするには, NewRequest と Client.Do を使います。

func (*Client) Head

func (c *Client) Head(url string) (resp *Response, err error)

Head は指定された URL に HEAD を発行します。レスポンスが以下のいずれかのリダイレクトコードである場合, Head は Client の CheckRedirect 関数を呼び出した後にリダイレクトに従います。

301 (永続的に移動)
302 (見つかった)
303 (その他を参照)
307 (一時的なリダイレクト)
308 (永続的なリダイレクト)

func (*Client) Post

func (c *Client) Post(url, contentType string, body io.Reader) (resp *Response, err error)

Post は指定された URL に POST を発行します。

呼び出し元は,読み取りが終わったら resp.Body を閉じる必要があります。

渡されたボディが io.Closer の場合は,リクエスト後に閉じられます。

カスタムヘッダーを設定するには, NewRequest と Client.Do を使用します。

リダイレクトの処理方法の詳細については, Client.Do メソッドのドキュメントを参照してください。

func (*Client) PostForm

func (c *Client) PostForm(url string, data url.Values) (resp *Response, err error)

PostForm は, URL エンコードされたデータのキーと値をリクエストボディとして,指定された URL に POST を発行します。

Content-Type ヘッダーは application/x-www-form-urlencoded に設定されています。他のヘッダを設定するには, NewRequest と Client.Do を使います。

err が nil の場合, resp は常に nil 以外の resp.Body を含みます。呼び出し元は,読み取りが終わったら resp.Body を閉じる必要があります。

リダイレクトの処理方法の詳細については, Client.Do メソッドのドキュメントを参照してください。

type CloseNotifier 1.1

CloseNotifier インターフェースは,内部の接続が切断されたことを検出できる ResponseWriters によって実装されています。

応答の準備ができる前にクライアントが切断した場合,このメカニズムを使用してサーバー上の長時間の操作を取り消すことができます。

非推奨 :CloseNotifier インターフェースは, Go のコンテキストパッケージより前のものです。新しいコードでは代わりに Request.Context を使用してください。

type CloseNotifier interface {
    // CloseNotify は,クライアント接続が切断されたときに最大で 1 つの値 (true) を受け取るチャンネルを返します。
    //
    // CloseNotify は Request.Body が完全に読まれるまで通知を待つことがあります。
    //
    // Handler が戻った後,チャンネルが値を受け取るという保証はありません。
    //
    // プロトコルが HTTP/1.1 であり, HTTP/1.1 パイプライン処理が使用されている間にべき等リクエスト (GET など) を処理している間に CloseNotify が呼び出されると,後続のパイプラインリクエストの到着により戻りチャンネルに値が送信されます。実際には, HTTP/1.1 パイプライン化はブラウザでは有効にされておらず,実際にはあまり見られません。これが問題になる場合は, HTTP/2 を使用するか, POST などのメソッドで CloseNotify のみを使用してください。
    CloseNotify() <-chan bool
}

type ConnState 1.3

AConnStaterepresentsthestateofaclientconnectiontoaserver.It'susedbytheoptionalServer.ConnStatehook.

type ConnState int
const (
    // StateNewrepresentsanewconnectionthatisexpectedtosendarequestimmediately.ConnectionsbeginatthisstateandthentransitiontoeitherStateActiveorStateClosed.
    StateNew ConnState = iota

    // StateActiverepresentsaconnectionthathasread1ormorebytesofarequest.TheServer.ConnStatehookforStateActivefiresbeforetherequesthasenteredahandleranddoesn'tfireagainuntiltherequesthasbeenhandled.Aftertherequestishandled,thestatetransitionstoStateClosed,StateHijacked,orStateIdle.ForHTTP/2,StateActivefiresonthetransitionfromzerotooneactiverequest,andonlytransitionsawayonceallactiverequestsarecomplete.ThatmeansthatConnStatecannotbeusedtodoper-requestwork;ConnStateonlynotestheoverallstateoftheconnection.
    StateActive

    // StateIdlerepresentsaconnectionthathasfinishedhandlingarequestandisinthekeep-alivestate,waitingforanewrequest.ConnectionstransitionfromStateIdletoeitherStateActiveorStateClosed.
    StateIdle

    // StateHijackedrepresentsahijackedconnection.Thisisaterminalstate.ItdoesnottransitiontoStateClosed.
    StateHijacked

    // StateClosedrepresentsaclosedconnection.Thisisaterminalstate.HijackedconnectionsdonottransitiontoStateClosed.
    StateClosed
)

func (ConnState) String 1.3

func (c ConnState) String() string

Cookie は, HTTP 応答の Set-Cookie ヘッダーまたは HTTP 要求の Cookie ヘッダーで送信された HTTP Cookie を表します。

詳細は https://tools.ietf.org/html/rfc6265 を参照してください。

type Cookie struct {
    Name  string
    Value string

    Path       string    // オプション
    Domain     string    // オプション
    Expires    time.Time // オプション
    RawExpires string    // クッキーを読むためだけに用いる

    // MaxAge=0 は, 'Max-Age' 属性が指定されていないことを意味します。
    // MaxAge<0 は Cookie を今削除することを意味します。 'Max-Age: 0' と同じ意味です。
    // MaxAge>0 は Max-Age 属性が存在し,秒単位で与えられることを意味します。
    MaxAge   int
    Secure   bool
    HttpOnly bool
    SameSite SameSite // Go 1.11
    Raw      string
    Unparsed []string // パースされていない属性-値ペアのローテキスト
}

func (*Cookie) String

func (c *Cookie) String() string

String は, Cookie ヘッダー (Name と Value が設定されている場合のみ) または Set-Cookie レスポンスヘッダー (他のフィールドが設定されている場合) で使用されている Cookie のシリアル化を返します。 c が nil または c.Name が無効の場合,空の文字列が返されます。

type CookieJar

CookieJar は, HTTP リクエストでの Cookie の保存と使用を管理します。

CookieJar の実装は,複数のゴルーチンによる平行使用に対して安全でなければなりません。

net/http/cookiejar パッケージは CookieJar の実装を提供します。

type CookieJar interface {
    // SetCookies は,指定された URL に対する応答で Cookie の受信を処理します。 jar のポリシーと実装に応じて, Cookie を保存する場合と保存しない場合があります。
    SetCookies(u *url.URL, cookies []*Cookie)

    // Cookies は,指定された URL に対するリクエストを送信するためにクッキーを返します。 RFC 6265 のような標準的なクッキーの使用制限を守るのは実装次第です。
    Cookies(u *url.URL) []*Cookie
}

type Dir

Dir は,特定のディレクトリツリーに限定されたネイティブファイルシステムを使用して FileSystem を実装します。

FileSystem.Open メソッドは '/' で区切られたパスを取りますが, Dir の文字列値は URL ではなくネイティブファイルシステム上のファイル名なので, filepath.Separator で区切られています (必ずしも '/' とは限りません) 。

Dir はピリオドで始まるファイルとディレクトリへのアクセスを許可します。 それで, .git ディレクトリのような機密ディレクトリや .htpasswd のような機密ファイルを公開する可能性があります。 先頭のピリオドを持つファイルを除外するには,サーバーからファイル/ディレクトリを削除するか,カスタム FileSystem 実装を作成します。

空の Dir は "." として扱われます。

type Dir string

func (Dir) Open

func (d Dir) Open(name string) (File, error)

Open implements FileSystem using os.Open, opening files for reading rooted and relative to the directory d.

type File

File は FileSystem の Open メソッドによって返され, FileServer 実装によってサービスされます。

メソッドは *os.File のメソッドと同じように動作すべきです。

type File interface {
    io.Closer
    io.Reader
    io.Seeker
    Readdir(count int) ([]os.FileInfo, error)
    Stat() (os.FileInfo, error)
}

type FileSystem

FileSystem は,名前付きファイルのコレクションへのアクセスを実装します。 ファイルパス内の要素は,ホストオペレーティングシステムの規則に関係なく, スラッシュ ('/', U+002F) 文字で区切られています。

type FileSystem interface {
    Open(name string) (File, error)
}

type Flusher

Flusher インターフェースは ResponseWriters によって実装され, HTTP ハンドラーがバッファされたデータをクライアントにフラッシュすることを可能にします。

デフォルトの HTTP/1.x および HTTP/2 ResponseWriter 実装は Flusher をサポートしていますが, ResponseWriter ラッパーはサポートしていません。ハンドラは常に実行時にこの機能をテストする必要があります。

Flush をサポートする ResponseWriter でも,クライアントが HTTP プロキシを介して接続されている場合,バッファリングされたデータは応答が完了するまでクライアントに到達しない可能性があります。

type Flusher interface {
    // Flush はバッファされたデータをクライアントに送ります。
    Flush()
}

type Handler

Handler は HTTP リクエストに応答します。

ServeHTTP は応答ヘッダーとデータを ResponseWriter に書き込んでから戻る必要があります。返り値はリクエストが終了したことを知らせます。 ServeHTTP 呼び出しの完了後または完了と平行に ResponseWriter を使用したり, Request.Body から読み取ったりすることは無効です。

HTTP クライアントソフトウェア, HTTP プロトコルバージョン,およびクライアントと Go サーバーの間の仲介者によっては, ResponseWriter に書き込んだ後で Request.Body から読み取ることができない場合があります。慎重なハンドラーは最初に Request.Body を読み,それから返信するべきです。

ボディを読むことを除いて,ハンドラは渡されたリクエストを修正してはいけません。

ServeHTTP がパニックした場合,サーバー (ServeHTTP の呼び出し側) は,パニックの影響がアクティブなリクエストに対して隔離されていると見なします。パニックを回復し,スタックトレースをサーバーエラーログに記録し, HTTP プロトコルに応じてネットワーク接続を閉じるか, HTTP/2 RST_STREAM を送信します。クライアントが中断された応答を見てもサーバがエラーをログに記録しないようにハンドラを中止するには, ErrAbortHandler の値を指定してパニックを発生させます。

type Handler interface {
    ServeHTTP(ResponseWriter, *Request)
}

func FileServer

func FileServer(root FileSystem) Handler

FileServer は,root をルートとするファイルシステムの内容で HTTP リクエストを処理するハンドラを返します。

オペレーティングシステムのファイルシステム実装を使用するには, http.Dir を使用します。

http.Handle("/", http.FileServer(http.Dir("/tmp")))

特別な場合として,返されたファイルサーバーは, "/index.html" で終わるすべてのリクエストを最後の "index.html" を含まないパスにリダイレクトします。

コード:

// 単純な静的 Web サーバー
log.Fatal(http.ListenAndServe(":8080", http.FileServer(http.Dir("/usr/share/doc"))))

例 (DotFileHiding)

コード:

package http_test

import (
    "log"
    "net/http"
    "os"
    "strings"
)

// containsDotFile は, name にピリオドで始まるパス要素が含まれているかどうかを報告します。
// http.FileSystem インターフェースで保証されているように,
// 名前はスラッシュで区切られていると見なされます。
func containsDotFile(name string) bool {
    parts := strings.Split(name, "/")
    for _, part := range parts {
        if strings.HasPrefix(part, ".") {
            return true
        }
    }
    return false
}

// dotFileHidingFile は, dotFileHidingFileSystem で使用される http.File です。
// http.File の Readdir メソッドをラップして,
// ピリオドで始まるファイルとディレクトリを出力から削除できるようにします。
type dotFileHidingFile struct {
    http.File
}

// Readdir は埋め込み File の Readdir メソッドのラッパーで,
// 名前の中にピリオドで始まるすべてのファイルを除外します。
func (f dotFileHidingFile) Readdir(n int) (fis []os.FileInfo, err error) {
    files, err := f.File.Readdir(n)
    for _, file := range files { // ドットファイルを除外する
        if !strings.HasPrefix(file.Name(), ".") {
            fis = append(fis, file)
        }
    }
    return
}

// dotFileHidingFileSystem は, 隠された "ドットファイル"
// が渡されないようにする http.FileSystem です。
type dotFileHidingFileSystem struct {
    http.FileSystem
}

// Open は,名前にパス内のピリオドで始まるファイルまたはディレクトリがある場合に
// 403 パーミッションエラーを返す,埋め込み FileSystem
// の Open メソッドのラッパーです。
func (fs dotFileHidingFileSystem) Open(name string) (http.File, error) {
    if containsDotFile(name) { // ドットファイルの場合, 403 応答を返す
        return nil, os.ErrPermission
    }

    file, err := fs.FileSystem.Open(name)
    if err != nil {
        return nil, err
    }
    return dotFileHidingFile{file}, err
}

func ExampleFileServer_dotFileHiding() {
    fs := dotFileHidingFileSystem{http.Dir(".")}
    http.Handle("/", http.FileServer(fs))
    log.Fatal(http.ListenAndServe(":8080", nil))
}

例 (StripPrefix)

コード:

// 代替 URL パス (/tmpfiles/) でディスク (/tmp) 上のディレクトリを提供するには,
// FileServer がパスを認識する前に StripPrefix を使用してリクエスト URL のパスを変更します。
http.Handle("/tmpfiles/", http.StripPrefix("/tmpfiles/", http.FileServer(http.Dir("/tmp"))))

func NotFoundHandler

func NotFoundHandler() Handler

NotFoundHandler は, "404 ページが見つかりません " という応答で各リクエストに応答する単純なリクエストハンドラを返します。

コード:

mux := http.NewServeMux()

// 404 を返すサンプルハンドラを作成する
mux.Handle("/resources", http.NotFoundHandler())

// 200 を返すサンプルハンドラを作成する
mux.Handle("/resources/people/", newPeopleHandler())

log.Fatal(http.ListenAndServe(":8080", mux))

func RedirectHandler

func RedirectHandler(url string, code int) Handler

RedirectHandlerreturnsarequesthandlerthatredirectseachrequestitreceivestothegivenurlusingthegivenstatuscode.

渡されたコードは 3xx の範囲内でなければならず,通常は StatusMovedPermanently, StatusFound または StatusSeeOther です。

func StripPrefix

func StripPrefix(prefix string, h Handler) Handler

StripPrefix は,リクエスト URL の Path から指定されたプレフィックスを削除し,ハンドラ h を呼び出すことによって HTTP リクエストを処理するハンドラを返します。 StripPrefix は, HTTP 404 not found エラーで応答することによって, prefix で始まっていないパスに対するリクエストを処理します。

コード:

// 代替 URL パス (/tmpfiles/) でディスク (/tmp) 上のディレクトリを提供するには,
// FileServer がパスを認識する前に StripPrefix を使用してリクエスト URL のパスを変更します。
http.Handle("/tmpfiles/", http.StripPrefix("/tmpfiles/", http.FileServer(http.Dir("/tmp"))))

func TimeoutHandler

func TimeoutHandler(h Handler, dt time.Duration, msg string) Handler

TimeoutHandler returns a Handler that runs h with the given time limit.

ThenewHandlercallsh.ServeHTTPtohandleeachrequest,butifacallrunsforlongerthanitstimelimit,thehandlerrespondswitha503ServiceUnavailableerrorandthegivenmessageinitsbody.(Ifmsgisempty,asuitabledefaultmessagewillbesent.)Aftersu チャット imeout,writesbyhtoitsResponseWriterwillreturnErrHandlerTimeout.

TimeoutHandler supports the Flusher and Pusher interfaces but does not support the Hijacker interface.

type HandlerFunc

HandlerFunc 型は,通常の関数を HTTP ハンドラとして使用できるようにするためのアダプタです。 f が適切なシグネチャを持つ関数の場合, HandlerFunc(f) は f を呼び出す Handler です。

type HandlerFunc func(ResponseWriter, *Request)

func (HandlerFunc) ServeHTTP

func (f HandlerFunc) ServeHTTP(w ResponseWriter, r *Request)

ServeHTTP は f(w, r) を呼び出します。

Header は, HTTP ヘッダ内のキーと値のペアを表します。

CanonicalHeaderKey によって返されるように,キーは正規形式である必要があります。

type Header map[string][]string

func (Header) Add

func (h Header) Add(key, value string)

Add は key と value のペアをヘッダに追加します。 key に関連付けられている既存の値に追加されます。 key は大文字と小文字を区別しません。 CanonicalHeaderKey によって正規化されます。

func (Header) Clone

func (h Header) Clone() Header

Clone returns a copy of h or nil if h is nil.

func (Header) Del

func (h Header) Del(key string)

Del は key に関連した値を削除します。 key は大文字と小文字を区別しません。 CanonicalHeaderKey によって正規化されます。

func (Header) Get

func (h Header) Get(key string) string

Get は key に関連付けられている最初の値を取得します。 key に関連付けられている値がない場合, Get は "" を返します。 大文字と小文字は区別されません。 textproto.CanonicalMIMEHeaderKey を使用して,渡された key を正規化します。 キーの複数の値にアクセスする,または非標準キーを使用するには,マップに直接アクセスします。

func (Header) Set

func (h Header) Set(key, value string)

Set は, key に関連付けられているヘッダエントリを 1 つの要素 value に設定します。 key に関連付けられている既存の値を置き換えます。 key は大文字と小文字を区別しません。 textproto.CanonicalMIMEHeaderKey によって正規化されます。 非標準キーを使用するには,マップに直接割り当てます。

func (Header) Write

func (h Header) Write(w io.Writer) error

Write はヘッダをワイヤフォーマットで書き込みます。

func (Header) WriteSubset

func (h Header) WriteSubset(w io.Writer, exclude map[string]bool) error

WriteSubset は,ワイヤーフォーマットでヘッダーを書き込みます。 exclude が nil 以外の場合, exclude[key] == true となるキーは書き込まれません。

type Hijacker

Hijacker インターフェースは, HTTP ハンドラが接続を引き継ぐことを可能にする ResponseWriters によって実装されます。

HTTP/1.x 接続用のデフォルトの ResponseWriter は Hijacker をサポートしていますが, HTTP/2 接続は意図的にはサポートしていません。 ResponseWriter ラッパーも Hijacker をサポートしていない可能性があります。ハンドラは常に実行時にこの機能をテストする必要があります。

type Hijacker interface {
    // ハイジャックは,呼び出し側が接続を引き継ぐことを可能にします。 Hijack を呼び出した後, HTTP サーバーライブラリは接続に関して他に何もしません。
    //
    // 接続を管理して閉じることは,呼び出し側の責任になります。
    //
    // 返された net.Conn には,サーバーの構成に応じて,読み取りまたは書き込みの期限が既に設定されている可能性があります。必要に応じてこれらの期限を設定またはクリアするのは,呼び出し側の責任です。
    //
    // 返された bufio.Reader には,クライアントからの未処理のバッファデータが含まれている可能性があります。
    //
    // Hijack を呼び出した後は,元の Request.Body を使用しないでください。元のリクエストのコンテキストは有効なままで,リクエストの ServeHTTP メソッドが戻るまでキャンセルされません。
    Hijack() (net.Conn, *bufio.ReadWriter, error)
}

コード:

http.HandleFunc("/hijack", func(w http.ResponseWriter, r *http.Request) {
    hj, ok := w.(http.Hijacker)
    if !ok {
        http.Error(w, "webserver doesn't support hijacking", http.StatusInternalServerError)
        return
    }
    conn, bufrw, err := hj.Hijack()
    if err != nil {
        http.Error(w, err.Error(), http.StatusInternalServerError)
        return
    }
    // 接続を閉じることを忘れないでください。
    defer conn.Close()
    bufrw.WriteString("Now we're speaking raw TCP. Say hi: ")
    bufrw.Flush()
    s, err := bufrw.ReadString('\n')
    if err != nil {
        log.Printf("error reading string: %v", err)
        return
    }
    fmt.Fprintf(bufrw, "You said: %q\nBye.\n", s)
    bufrw.Flush()
})

type ProtocolError

ProtocolError は HTTP プロトコルエラーを表します。

非推奨 :http パッケージ内のプロトコルエラーに関連するすべてのエラーが ProtocolError 型であるとは限りません。

type ProtocolError struct {
    ErrorString string
}

func (*ProtocolError) Error

func (pe *ProtocolError) Error() string

type PushOptions 1.8

PushOptions は Pusher.Push のオプションについて記述します。

type PushOptions struct {
    // Method は,リクエストに対する HTTP メソッドを指定します。
    // 設定されているなら,それは "GET" か "HEAD" でなければなりません。空は "GET" を意味します。
    Method string

    // Header (ヘッダー) は追加のリクエストヘッダーを指定します。
    // これには,自動的に追加される ":path" や ":scheme" のような
    // HTTP/2 疑似ヘッダフィールドを含めることはできません。
    Header Header
}

type Pusher 1.8

Pusher は, HTTP/2 サーバープッシュをサポートする ResponseWriters によって実装されたインターフェースです。 より詳しい背景については, https://tools.ietf.org/html/rfc7540#section-8.2 を参照してください。

type Pusher interface {
    // Push は HTTP/2 サーバープッシュを開始します。これは与えられたターゲットとオプションを使って合成リクエストを構築し,そのリクエストを PUSH_PROMISE フレームにシリアライズし,そしてサーバのリクエストハンドラを使ってそのリクエストをディスパッチします。 opts が nil の場合,デフォルトのオプションが使用されます。
    //
    // ターゲットは, ("/path" のような) 絶対パス,または有効なホストと親のリクエストと同じスキームを含む絶対 URL のいずれかでなければなりません。ターゲットがパスの場合は,親リクエストのスキームとホストを継承します。
    //
    // HTTP/2 仕様では,再帰的プッシュや相互認証プッシュは許可されていません。プッシュはこれらの無効なプッシュを検出する場合と検出しない場合があります。ただし,無効なプッシュは,適合クライアントによって検出されキャンセルされます。
    //
    // URL X をプッシュするハンドラーは, URL X のリクエストをトリガーする可能性のあるデータを送信する前に Push を呼び出す必要があります。これにより, X の PUSH_PROMISE を受信する前にクライアントが X のリクエストを発行する競合が回避されます。
    //
    // Push は別のゴルーチンで実行され,到着順は決定論的ではありません。必要な同期は,呼び出し側によって実装される必要があります。
    //
    // クライアントがプッシュを無効にした場合,またはプッシュが内部の接続でサポートされていない場合, Push は ErrNotSupported を返します。
    Push(target string, opts *PushOptions) error
}

type Request

Request は,サーバーによって受信された,またはクライアントによって送信される HTTP リクエストを表します。

フィールドのセマンティクスは,クライアントとサーバーの使用方法によってわずかに異なります。以下のフィールドに関する注記に加えて, Request.Write と RoundTripper のドキュメントを参照してください。

type Request struct {
    // Method は HTTP メソッド (GET, POST, PUT など) を指定します。クライアントリクエストの場合,空の文字列は GET を意味します。
    //
    // Go の HTTP クライアントは CONNECT メソッドによるリクエストの送信をサポートしていません。詳しくは Transport のドキュメントを見てください。
    Method string

    // URL は,リクエストされている URI(サーバーリクエストの場合) またはアクセスする URL(クライアントリクエストの場合) を指定します。
    //
    // サーバーリクエストの場合, URL は RequestURI に格納されている Request-Line で渡された URI から解析されます。ほとんどのリクエストでは, Path と RawQuery 以外のフィールドは空になります。 (RFC7230 ,セクション 5.3 を参照)
    //
    // クライアントリクエストの場合, URL の Host は接続先のサーバーを指定し, Request の Host フィールドは HTTP リクエストで送信する Host ヘッダー値をオプションで指定します。
    URL *url.URL

    // 着信サーバーリクエストのプロトコルバージョン。
    //
    // クライアントリクエストの場合,これらのフィールドは無視されます。 HTTP クライアントコードは常に HTTP/1.1 または HTTP/2 を使用します。詳細は Transport のドキュメントを見てください。
    Proto      string // "HTTP/1.0"
    ProtoMajor int    // 1
    ProtoMinor int    // 0

    // Header には,サーバーによって受信された,またはクライアントによって送信されるリクエストヘッダーフィールドが含まれています。
    //
    // サーバーがヘッダー行を含むリクエストを受け取った場合
    //
    //	Host: example.com
    //	accept-encoding: gzip, deflate
    //	Accept-Language: en-us
    //	fOO: Bar
    //	foo: two
    //
    // それから
    //
    //	Header = map[string][]string{
    //		"Accept-Encoding": {"gzip, deflate"},
    //		"Accept-Language": {"en-us"},
    //		"Foo": {"Bar", "two"},
    //	}
    //
    // 着信リクエストの場合, Host ヘッダーは Request.Host フィールドにプロモートされ,ヘッダーマップから削除されます。
    //
    // HTTP では,ヘッダー名の大文字と小文字は区別されないと定義されています。リクエストパーサーは CanonicalHeaderKey を使用してこれを実装し,最初の文字とハイフンに続くすべての文字を小文字にし,残りを小文字にします。
    //
    // クライアントリクエストの場合, Content-Length や Connection などの特定のヘッダーは必要に応じて自動的に書き込まれ, Header の値は無視されます。 Request.Write メソッドのドキュメントを参照してください。
    Header Header

    // ボディはリクエストのボディです。
    //
    // クライアントリクエストの場合, nil body は, GET リクエストのように,リクエストにボディがないことを意味します。 HTTP クライアントのトランスポートは Close メソッドを呼び出す責任があります。
    //
    // サーバリクエストの場合, Request Body は常に nil 以外ですが,ボディが存在しない場合は直ちに EOF を返します。サーバーはリクエストボディを閉じます。 ServeHTTP ハンドラーは必須ではありません。
    Body io.ReadCloser

    // GetBody は, Body の新しいコピーを返すためのオプションの関数を定義します。リダイレクトでボディを複数回読み取る必要がある場合に,クライアントのリクエストに使用されます。 GetBody を使用するにはまだ Body を設定する必要があります。
    //
    // サーバーリクエストの場合は使用されません。
    GetBody func() (io.ReadCloser, error) // Go 1.8

    // ContentLength は,関連付けられているコンテンツの長さを記録します。値 -1 は,長さが不明であることを示します。値 >= 0 は,指定されたバイト数を Body から読み取ることができることを示します。
    //
    // クライアントリクエストの場合, nil 以外の Body を持つ 0 の値も unknown として扱われます。
    ContentLength int64

    // TransferEncoding は,最も外側から最も内側への転送エンコードをリストします。空のリストは "identity" エンコーディングを表します。 TransferEncoding は通常無視することができます。チャンクエンコーディングは,リクエストを送受信するときに必要に応じて自動的に追加および削除されます。
    TransferEncoding []string

    // Close は,このリクエストに応答した後 (サーバーの場合) ,またはこのリクエストを送信して応答を読み取った後 (クライアントの場合) に接続を閉じるかどうかを示します。
    //
    // サーバーリクエストの場合, HTTP サーバーはこれを自動的に処理します。このフィールドは Handlers では不要です。
    //
    // クライアントリクエストの場合,このフィールドを設定すると, Transport.DisableKeepAlives が設定されている場合と同様に,同じホストへのリクエスト間で TCP 接続が再利用されなくなります。
    Close bool

    // サーバーリクエストの場合, Host は URL が検索されるホストを指定します。 RFC 7230 のセクション 5.4 によると,これは "Host" ヘッダーの値か, URL 自体に指定されているホスト名のいずれかです。 "host:port" という形式になります。国際ドメイン名の場合, Host は Punycode 形式または Unicode 形式になります。必要ならば golang.org/x/net/idna を使ってどちらかの形式に変換してください。 DNS 再バインド攻撃を防ぐために,サーバーハンドラーは, Host ヘッダーに,ハンドラーが信頼できると見なす値があることを検証する必要があります。含まれている ServeMux は,特定のホスト名に登録されたパターンをサポートしているため,その登録済みハンドラーを保護します。
    //
    // クライアントリクエストの場合, Host はオプションで送信するために Host ヘッダーをオーバーライドします。空の場合, Request.Write メソッドは URL.Host の値を使用します。ホストは国際ドメイン名を含むことができます。
    Host string

    // Form contains the parsed form data, including both the URL
    // field's query parameters and the PATCH, POST, or PUT form data.
    // This field is only available after ParseForm is called.
    // The HTTP client ignores Form and uses Body instead.
    Form url.Values

    // PostForm contains the parsed form data from PATCH, POST
    // or PUT body parameters.
    //
    // このフィールドは, ParseForm が呼び出された後にのみ利用可能です。 HTTP クライアントは PostForm を無視し,代わりに Body を使用します。
    PostForm url.Values // Go 1.1

    // MultipartForm は,ファイルのアップロードを含む,解析されたマルチパートフォームです。このフィールドは, ParseMultipartForm が呼び出された後にのみ使用可能です。 HTTP クライアントは MultipartForm を無視し,代わりに Body を使用します。
    MultipartForm *multipart.Form

    // Trailer は,リクエストボディの後に送信される追加のヘッダーを指定します。
    //
    // サーバーリクエストの場合,トレーラーマップには最初はトレーラーキーのみが含まれ,値は nil です。ハンドラーが Body から読み取っている間は, Trailer を参照してはいけません。 Body から読み取ると EOF が返された後, Trailer は再度読み取ることができ,クライアントによって送信された場合は nil 以外の値が入ります。
    //
    // クライアントリクエストの場合は,後で送信するために, Trailer をトレーラキーを含むマップに初期化する必要があります。値は,ゼロまたはその最終値です。チャンクリクエストを送信するには, ContentLength を 0 または -1 にする必要があります。 HTTP リクエストが送信された後,リクエストボディが読み込まれている間にマップ値を更新できます。ボディが EOF を返すと,呼び出し元は Trailer を変更してはいけません。
    //
    // HTTP トレーラーをサポートしている HTTP クライアント,サーバー,またはプロキシはほとんどありません。
    Trailer Header

    // RemoteAddr を使用すると, HTTP サーバーやその他のソフトウェアは,通常はログ記録のために,リクエストを送信したネットワークアドレスを記録できます。このフィールドは ReadRequest によって埋められることはなく,フォーマットも定義されていません。このパッケージの HTTP サーバーは,ハンドラーを呼び出す前に RemoteAddr を "IP:port" アドレスに設定します。このフィールドは HTTP クライアントによって無視されます。
    RemoteAddr string

    // RequestURI は,クライアントからサーバーに送信される Request-Line (RFC 7230 ,セクション 3.1.1) の変更されていない request-target です。通常は URL フィールドを代わりに使用してください。 HTTP クライアントリクエストでこのフィールドを設定するとエラーになります。
    RequestURI string

    // TLS を使用すると, HTTP サーバーやその他のソフトウェアは,リクエストを受信した TLS 接続に関する情報を記録できます。このフィールドは ReadRequest によって埋められません。このパッケージの HTTP サーバーは,ハンドラを呼び出す前に TLS 対応の接続用のフィールドを設定します。それ以外の場合はフィールド nil を残します。このフィールドは HTTP クライアントによって無視されます。
    TLS *tls.ConnectionState

    // Cancel は,オプションのチャンネルで,クローズされた場合,クライアントリクエストがキャンセルされたと見なされるべきであることを示します。 RoundTripper のすべての実装が Cancel をサポートしているとは限りません。
    //
    // サーバーリクエストの場合,このフィールドは適用されません。
    //
    // Deprecated: Set the Request's context with NewRequestWithContext
    // instead. If a Request's Cancel field and context are both
    // set, it is undefined whether Cancel is respected.
    Cancel <-chan struct{} // Go 1.5

    // Response は,このリクエストが作成される原因となったリダイレクト応答です。このフィールドは,クライアントのリダイレクト中にのみ入力されます。
    Response *Response // Go 1.7
    // エクスポートされていないフィールドがあります
}

func NewRequest

func NewRequest(method, url string, body io.Reader) (*Request, error)

NewRequest wraps NewRequestWithContext using the background context.

func NewRequestWithContext

func NewRequestWithContext(ctx context.Context, method, url string, body io.Reader) (*Request, error)

NewRequestWithContext returns a new Request given a method, URL, and optional body.

body が io.Closer でもある場合,返却値の Request.Body は body に設定され,クライアントメソッドの Do , Post , PostForm ,および Transport.RoundTrip によって閉じられます。

NewRequestWithContext returns a Request suitable for use with Client.Do or Transport.RoundTrip. To create a request for use with testing a Server Handler, either use the NewRequest function in the net/http/httptest package, use ReadRequest, or manually update the Request fields. For an outgoing client request, the context controls the entire lifetime of a request and its response: obtaining a connection, sending the request, and reading the response headers and body. See the Request type's documentation for the difference between inbound and outbound request fields.

body の型が *bytes.Buffer, *bytes.Reader ,または *strings.Reader の場合,返されるリクエストの ContentLength は (-1 ではなく) 正確な値に設定され, GetBody が設定されます (したがって, 307 および 308 リダイレクトは body を再生できます) 。 ContentLength が 0 の場合, Body は NoBody に設定されます。

func ReadRequest

func ReadRequest(b *bufio.Reader) (*Request, error)

ReadRequest は b から入ってくるリクエストを読み込んで解析します。

ReadRequest は低レベルの関数であり,特殊なアプリケーションにのみ使用されるべきです。ほとんどのコードはサーバーを使用してリクエストを読み取り, Handler インターフェースを介してそれらを処理します。 ReadRequest は HTTP/1.x リクエストのみをサポートします。 HTTP/2 の場合は, golang.org/x/net/http2 を使用してください。

func (*Request) AddCookie

func (r *Request) AddCookie(c *Cookie)

AddCookie はリクエストにクッキーを追加します。 RFC 6265 セクション 5.4 によると, AddCookie は複数の Cookie ヘッダーフィールドを添付しません。つまり,すべての Cookie がある場合は,それがセミコロンで区切られて同じ行に書き込まれます。

func (*Request) BasicAuth 1.4

func (r *Request) BasicAuth() (username, password string, ok bool)

BasicAuth は,リクエストが HTTP 基本認証を使用している場合,リクエストの Authorization ヘッダーに指定されているユーザー名とパスワードを返します。 RFC 2617 のセクション 2 を参照してください。

func (*Request) Clone

func (r *Request) Clone(ctx context.Context) *Request

Clone returns a deep copy of r with its context changed to ctx. The provided ctx must be non-nil.

For an outgoing client request, the context controls the entire lifetime of a request and its response: obtaining a connection, sending the request, and reading the response headers and body.

func (*Request) Context 1.7

func (r *Request) Context() context.Context

Context はリクエストのコンテキストを返します。コンテキストを変更するには, WithContext を使います。

返されるコンテキストは常に nil 以外です。デフォルトはバックグラウンドコンテキストです。

For outgoing client requests, the context controls cancellation.

着信サーバーリクエストの場合,クライアントの接続が閉じられるとき, (HTTP/2 で) リクエストが取り消されるとき,または ServeHTTP メソッドが戻るときに,コンテキストは取り消されます。

func (*Request) Cookie

func (r *Request) Cookie(name string) (*Cookie, error)

Cookie はリクエストで渡された名前付きクッキーを返します。見つからなかった場合は ErrNoCookie を返します。複数の Cookie が指定の名前と一致する場合, 1 つの Cookie のみが返されます。

func (*Request) Cookies

func (r *Request) Cookies() []*Cookie

Cookies は,リクエストとともに送信された HTTPCookie を解析して返します。

func (*Request) FormFile

func (r *Request) FormFile(key string) (multipart.File, *multipart.FileHeader, error)

FormFile は,渡されたフォームキーの最初のファイルを返します。 FormFile は必要に応じて ParseMultipartForm と ParseForm を呼び出します。

func (*Request) FormValue

func (r *Request) FormValue(key string) string

FormValue は,クエリの名前付きコンポーネントの最初の値を返します。 POST および PUT ボディパラメータは, URL クエリ文字列値よりも優先されます。 FormValue は必要に応じて ParseMultipartForm と ParseForm を呼び出し,これらの関数によって返されたエラーを無視します。キーが存在しない場合, FormValue は空の文字列を返します。同じキーの複数の値にアクセスするには, ParseForm を呼び出してから Request.Form を直接調べます。

func (*Request) MultipartReader

func (r *Request) MultipartReader() (*multipart.Reader, error)

MultipartReader は,これが multipart/form-data または multipart/mixed の POST リクエストである場合は MIME マルチパートリーダーを返し,それ以外の場合は nil とエラーを返します。リクエストボディをストリームとして処理するには, ParseMultipartForm の代わりにこの関数を使用します。

func (*Request) ParseForm

func (r *Request) ParseForm() error

ParseForm は r.Form と r.PostForm を生成します。

すべてのリクエストに対して, ParseForm は URL からの生のクエリを解析し, r.Form を更新します。

POST, PUT ,および PATCH リクエストの場合は,リクエストボディもフォームとして解析し,結果を r.PostForm と r.Form の両方に入れます。リクエストボディパラメータは, r.Form の URL クエリ文字列値よりも優先されます。

他の HTTP メソッドの場合,または Content-Type が application/x-www-form-urlencoded ではない場合,リクエストの Body は読み取られず, r.PostForm はゼロ以外の空の値に初期化されます。

リクエストボディのサイズが MaxBytesReader によってまだ制限されていない場合,サイズは 10MB に制限されます。

ParseMultipartForm は自動的に ParseForm を呼び出します。 ParseForm はべき等です。

func (*Request) ParseMultipartForm

func (r *Request) ParseMultipartForm(maxMemory int64) error

ParseMultipartForm はリクエストボディを multipart/form-data として解析します。リクエストボディ全体が解析され,そのファイル部分の最大 maxMemory バイトまでがメモリに格納され,残りは一時ファイルのディスクに格納されます。必要に応じて, ParseMultipartForm は ParseForm を呼び出します。 ParseMultipartForm を一度呼び出した後は,それ以降の呼び出しは無効です。

func (*Request) PostFormValue 1.1

func (r *Request) PostFormValue(key string) string

PostFormValue は, POST , PATCH ,または PUT リクエストボディの名前付きコンポーネントの最初の値を返します。 URL クエリパラメータは無視されます。 PostFormValue は必要に応じて ParseMultipartForm と ParseForm を呼び出し,これらの関数によって返されたエラーを無視します。キーが存在しない場合, PostFormValue は空の文字列を返します。

func (*Request) ProtoAtLeast

func (r *Request) ProtoAtLeast(major, minor int) bool

ProtoAtLeast は,リクエストで使用された HTTP プロトコルが少なくとも major.minor であるかどうかを報告します。

func (*Request) Referer

func (r *Request) Referer() string

Referer は,リクエストで送信された場合,参照元 URL を返します。

Referer はスペルミスですが,これは HTTP の初期の頃の間違いです。この値は Header["Referer"] として Header マップからも取得できます。メソッドとして利用できるようにすることの利点は,コンパイラが代替 (正しい英語) スペル req.Referrer() を使用するプログラムを診断できますが, Header["Referrer"] を使用するプログラムを診断できないことです。

func (*Request) SetBasicAuth

func (r *Request) SetBasicAuth(username, password string)

SetBasicAuth は,指定されたユーザー名とパスワードで HTTP 基本認証を使用するようにリクエストの Authorization ヘッダーを設定します。

HTTP 基本認証では,渡されたユーザー名とパスワードは暗号化されません。

Some protocols may impose additional requirements on pre-escaping the username and password. For instance, when used with OAuth2, both arguments must be URL encoded first with url.QueryEscape.

func (*Request) UserAgent

func (r *Request) UserAgent() string

UserAgent は,リクエストで送信された場合,クライアントの User-Agent を返します。

func (*Request) WithContext 1.7

func (r *Request) WithContext(ctx context.Context) *Request

WithContext は,コンテキストが ctx に変更された r のシャローコピーを返します。渡される ctx は nil 以外でなければなりません。

発信クライアントリクエストの場合,コンテキストはリクエストとその応答の全存続期間 (接続の取得,リクエストの送信,および応答ヘッダーとボディの読み取り) を制御します。

To create a new request with a context, use NewRequestWithContext. To change the context of a request (such as an incoming) you then also want to modify to send back out, use Request.Clone. Between those two uses, it's rare to need WithContext.

func (*Request) Write

func (r *Request) Write(w io.Writer) error

Write は HTTP/1.1 リクエスト (ヘッダーとボディ) をワイヤーフォーマットで書き込みます。このメソッドは,リクエストの以下のフィールドを調べます。

Host
URL
Method (defaults to "GET")
Header
ContentLength
TransferEncoding
Body

Body が存在し, Content-Length が 0 以下で, TransferEncoding が "identity" に設定されていない場合, Write はヘッダーに "Transfer-Encoding:chunked" を追加します。送信後,ボディは閉じられます。

func (*Request) WriteProxy

func (r *Request) WriteProxy(w io.Writer) error

WriteProxy は Write に似ていますが, HTTP プロキシが期待する形式でリクエストを書き込みます。特に, WriteProxy は,スキームとホストを含​​む RFC 7230 のセクション 5.3 に従って,リクエストの最初の Request-URI 行を絶対 URI で書き込みます。どちらの場合も, WriteProxy は r.Host または r.URL.Host を使用して Host ヘッダーも書き込みます。

type Response

Response (レスポンス,応答) は, HTTP リクエストからのレスポンスを表します。

レスポンスヘッダが受信されると,クライアントとトランスポートはサーバーからレスポンスを返します。 Body フィールドが読み取られるときに,レスポンスボディがオンデマンドでストリーミングされます。

type Response struct {
    Status     string // 例えば "200 OK"
    StatusCode int    // 例えば 200
    Proto      string // 例えば "HTTP/1.0"
    ProtoMajor int    // 例えば 1
    ProtoMinor int    // 例えば 0

    // Header (ヘッダー) は,ヘッダーキーを値にマッピングします。
    // レスポンスに同じキーを持つ複数のヘッダーがある場合は,それらをコンマ区切り文字で連結することができます。
    // (RFC 7230, セクション 3.2.2 では,複数のヘッダーがコンマ区切りのシーケンスと意味的に同等であることが要求されています。)
    // ヘッダー値がこの構造体の他のフィールドと重複する場合 (ContentLength, TransferEncoding, Trailer など),
    // フィールド値が信頼できます。
    //
    // マップ内のキーは正規化されています (CanonicalHeaderKey を参照) 。
    Header Header

    // Body はレスポンスボディを表します。
    //
    // Body フィールドが読み取られるときに,レスポンスボディがオンデマンドでストリーミングされます。ネットワーク接続が失敗した場合,またはサーバーがレスポンスを終了した場合は, Body.Read 呼び出しはエラーを返します。
    //
    // http クライアントとトランスポートは,ボディのないレスポンスや長さゼロのボディのレスポンスであっても,ボディが常に nil 以外であることを保証します。 Body を閉じるのは呼び出し側の責任です。デフォルトの HTTP クライアントのトランスポートは, Body が最後まで読み込まれずに閉じられている場合, HTTP/1.x の " キープアライブ " TCP 接続を再利用できません。
    //
    // サーバが " チャンクされた " Transfer-Encoding でレスポンスした場合, Body は自動的にチャンク解除されます。
    //
    // As of Go 1.12, the Body will also implement io.Writer
    // on a successful "101 Switching Protocols" response,
    // as used by WebSockets and HTTP/2's "h2c" mode.
    Body io.ReadCloser

    // ContentLength は,関連付けられているコンテンツの長さを記録します。値 -1 は,長さが不明であることを示します。 Request.Method が "HEAD" でない限り,値 >= 0 は,指定されたバイト数が Body から読み取られる可能性があることを示します。
    ContentLength int64

    // 最も外側から最も内側への転送エンコードが含まれています。値が nil で, "identity" エンコーディングが使われていることを意味します。
    TransferEncoding []string

    // Close は,ヘッダーが Body の読み取り後に接続を閉じるように指示したかどうかを記録します。値はクライアントへのアドバイスです。 ReadResponse も Response.Write も接続を閉じません。
    Close bool

    // Uncompressed は,レスポンスが圧縮されて送信されたが http パッケージによって解凍されたかどうかを報告します。 true の場合, Body から読み取ると,サーバーから実際に設定された圧縮コンテンツではなく,非圧縮コンテンツが生成され, ContentLength は -1 に設定され, "Content-Length" フィールドと "Content-Encoding" フィールドは responseHeader から削除されます。サーバーから元のレスポンスを取得するには, Transport.DisableCompression を true に設定します。
    Uncompressed bool // Go 1.7

    // Trailer は,トレーラーキーを Header と同じ形式の値にマッピングします。
    //
    // Trailer は,最初は nil 値のみを含み,サーバの "Trailer" ヘッダ値で指定された各キーに対して 1 つの値です。これらの値は Header に追加されません。
    //
    // Trailer は,ボディに対する読み取り呼び出しと平行にアクセスしてはなりません。
    //
    // Body.Read が io.EOF を返した後, Trailer はサーバーから送信されたすべてのトレーラー値を含みます。
    Trailer Header

    // Request は,このレスポンスを取得するために送信されたリクエストです。リクエストのボディはゼロです (すでに消費されています) 。これは,クライアントリクエストに対してのみ取り込まれます。
    Request *Request

    // TLS には,レスポンスが受信された TLS 接続に関する情報が含まれています。暗号化されていないレスポンスでは無効です。ポインターはレスポンス間で共有されるため,変更しないでください。
    TLS *tls.ConnectionState // Go 1.3
}

func Get

func Get(url string) (resp *Response, err error)

Get は指定された URL に GET を発行します。 レスポンスが次のいずれかのリダイレクトコードである場合, Get は最大 10 のリダイレクトまでリダイレクトに従います。

301 (永続的に移動)
302 (見つかった)
303 (その他を参照)
307 (一時的なリダイレクト)
308 (永続的なリダイレクト)

リダイレクトが多すぎる場合,または HTTP プロトコルエラーが発生した場合は,エラーが返されます。 2xx 以外のレスポンスではエラーは発生しません。 返されたエラーはすべて *url.Error 型になります。 リクエストがタイムアウトまたはキャンセルされた場合, url.Error 値の Timeout メソッドは true を返します。

err が nil の場合, resp は常に nil 以外の resp.Body を含みます。呼び出し元は,読み取りが終わったら resp.Body を閉じる必要があります。

Get は DefaultClient.Get のラッパーです。

カスタムヘッダーを使用してリクエストを行うには, NewRequest と DefaultClient.Do を使用します。

コード:

res, err := http.Get("http://www.google.com/robots.txt")
if err != nil {
    log.Fatal(err)
}
robots, err := ioutil.ReadAll(res.Body)
res.Body.Close()
if err != nil {
    log.Fatal(err)
}
fmt.Printf("%s", robots)
func Head(url string) (resp *Response, err error)

Head は指定された URL に HEAD を発行します。レスポンスが以下のいずれかのリダイレクトコードである場合, Head は最大 10 のリダイレクトまでリダイレクトに従います。

301 (永続的に移動)
302 (見つかった)
303 (その他を参照)
307 (一時的なリダイレクト)
308 (永続的なリダイレクト)

Head は DefaultClient.Head のラッパーです。

func Post

func Post(url, contentType string, body io.Reader) (resp *Response, err error)

Post は指定された URL に POST を発行します。

呼び出し元は,読み取りが終わったら resp.Body を閉じる必要があります。

渡されたボディが io.Closer の場合は,リクエスト後に閉じられます。

Post は DefaultClient.Post のラッパーです。

カスタムヘッダーを設定するには, NewRequest と DefaultClient.Do を使用します。

リダイレクトの処理方法の詳細については, Client.Do メソッドのドキュメントを参照してください。

func PostForm

func PostForm(url string, data url.Values) (resp *Response, err error)

PostForm は,URL エンコードされたデータのキーと値をリクエストボディとして,指定された URL に POST を発行します。

Content-Type ヘッダーは application/x-www-form-urlencoded に設定されています。他のヘッダを設定するには, NewRequest と DefaultClient.Do を使います。

err が nil の場合, resp は常に nil 以外の resp.Body を含みます。呼び出し元は,読み取りが終わったら resp.Body を閉じる必要があります。

PostForm は DefaultClient.PostForm のラッパーです。

リダイレクトの処理方法の詳細については, Client.Do メソッドのドキュメントを参照してください。

func ReadResponse

func ReadResponse(r *bufio.Reader, req *Request) (*Response, error)

ReadResponse は r から HTTP レスポンスを読み込んで返します。 req パラメータはオプションで,このレスポンスに対応するリクエストを指定します。 nil の場合, GET リクエストが想定されます。クライアントは resp.Body の読み取りが完了したら resp.Body.Close を呼び出す必要があります。その呼び出しの後,クライアントは resp.Trailer を調べて,レスポンストレーラーに含まれているキーと値のペアを見つけることができます。

func (*Response) Cookies

func (r *Response) Cookies() []*Cookie

Cookies は, Set-Cookie ヘッダーに設定されている Cookie を解析して返します。

func (*Response) Location

func (r *Response) Location() (*url.URL, error)

Location は,もしあれば,レスポンスの "Location" ヘッダの URL を返します。相対的なリダイレクトは,レスポンスのリクエストに対して解決されます。 Location ヘッダーが存在しない場合, ErrNoLocation が返されます。

func (*Response) ProtoAtLeast

func (r *Response) ProtoAtLeast(major, minor int) bool

ProtoAtLeast は,レスポンスで使用された HTTP プロトコルが少なくとも major.minor であるかどうかを報告します。

func (*Response) Write

func (r *Response) Write(w io.Writer) error

Write は,ステータス行,ヘッダー,ボディ,およびオプションのトレーラーを含む HTTP/1.x サーバーレスポンス形式で r を w に書き込みます。

このメソッドは,レスポンス r の以下のフィールドを調べます。

StatusCode
ProtoMajor
ProtoMinor
Request.Method
TransferEncoding
Trailer
Body
ContentLength
Header, 非標準キーの値には予期しない動作があります。

レスポンスボディは送信後に閉じられます。

type ResponseWriter

ResponseWriter インターフェースは, HTTP 応答を構成するために HTTP ハンドラーによって使用されます。

Handler.ServeHTTP メソッドが返された後は, ResponseWriter を使用できません。

type ResponseWriter interface {
    // Header は, WriteHeader によって送信されるヘッダーマップを返します。ヘッダーマップは, Handlers が HTTP トレーラーを設定できるメカニズムでもあります。
    //
    // WriteHeader (または Write) を呼び出した後にヘッダーマップを変更しても,変更されたヘッダーがトレーラーでない限り効果はありません。
    //
    // 予告編を設定する方法は 2 つあります。推奨される方法は, "Trailer" ヘッダを後に来るトレーラキーの名前に設定することによって,後で送るトレーラのヘッダを事前宣言することです。この場合,ヘッダーマップのそれらのキーは,あたかもそれらがトレーラーであるかのように扱われます。例を見てください。 2 番目の方法は,最初の Write の後まで Handler に認識されないトレーラキーの場合,ヘッダマップキーの前に TrailerPrefix 定数値を付けることです。 TrailerPrefix を参照してください。
    //
    // 自動応答ヘッダー ("Date" など) を抑制するには,それらの値を nil に設定します。
    Header() Header

    // Write は, HTTP 応答の一部としてデータを接続に書き込みます。
    //
    // WriteHeader がまだ呼び出されていない場合, Write はデータを書き込む前に WriteHeader(http.StatusOK) を呼び出します。 Header に Content-Type 行が含まれていない場合, Write は最初の 512 バイトの書き込みデータを DetectContentType に渡した結果に Content-Type セットを追加します。さらに,書き込まれたすべてのデータの合計サイズが数 KB 未満で, Flush 呼び出しがない場合は, Content-Length ヘッダーが自動的に追加されます。
    //
    // HTTP プロトコルのバージョンとクライアントによっては, Write または WriteHeader を呼び出すと今後の Request.Body の読み取りが妨げられる可能性があります。 HTTP/1.x リクエストの場合,ハンドラはレスポンスを書く前に必要なリクエストボディデータを読むべきです。ヘッダーがフラッシュされると (明示的な Flusher.Flush 呼び出しまたはフラッシュをトリガーするのに十分なデータの書き込みが原因で) ,リクエストボディは使用できなくなる可能性があります。 HTTP/2 リクエストの場合, Go HTTP サーバーはハンドラーが平行に応答を書き込んでいる間リクエストボディを読み続けることを許可します。ただし,このような動作はすべての HTTP/2 クライアントでサポートされているわけではありません。互換性を最大限にするために,可能であればハンドラは書き込み前に読んでください。
    Write([]byte) (int, error)

    // WriteHeader は,渡されたステータスコードとともに HTTP 応答ヘッダーを送信します。
    //
    // WriteHeader が明示的に呼び出されていない場合, Write への最初の呼び出しは暗黙的な WriteHeader(http.StatusOK) をトリガーします。したがって, WriteHeader への明示的な呼び出しは,主にエラーコードを送信するために使用されます。
    //
    // 渡されたコードは有効な HTTP 1xx-5xx ステータスコードでなければなりません。ヘッダーは 1 つだけ書くことができます。 Go は現在, Request.Body が読み取られたときにサーバーが自動的に送信する 100-continue 応答ヘッダーを除いて,ユーザー定義の 1xx 情報ヘッダーの送信をサポートしていません。
    WriteHeader(statusCode int)
}

例 (Trailers)

HTTP Trailers は, HTTP レスポンスの前ではなく後に来る ヘッダのようなキーと値のペアのセットです。

コード:

mux := http.NewServeMux()
mux.HandleFunc("/sendstrailers", func(w http.ResponseWriter, req *http.Request) {
    // WriteHeader または Write を呼び出す前に, HTTP 応答中に設定するトレーラーを宣言します。これら 3 つのヘッダーは実際にはトレーラーで送信されます。
    w.Header().Set("Trailer", "AtEnd1, AtEnd2")
    w.Header().Add("Trailer", "AtEnd3")

    w.Header().Set("Content-Type", "text/plain; charset=utf-8") // 通常のヘッダ
    w.WriteHeader(http.StatusOK)

    w.Header().Set("AtEnd1", "value 1")
    io.WriteString(w, "This HTTP response has both headers before this text and trailers at the end.\n")
    w.Header().Set("AtEnd2", "value 2")
    w.Header().Set("AtEnd3", "value 3") // これらはトレーラーとなります。
})

type RoundTripper

RoundTripper は,1 つの HTTP トランザクションを実行し,特定のリクエストに対するレスポンスを取得する機能を表すインターフェースです。

RoundTripper は,複数のゴルーチンによる平行使用に対して安全でなければなりません。

type RoundTripper interface {
    // RoundTrip は 1 つの HTTP トランザクションを実行し,渡されたリクエストに対する応答を返します。
    //
    // RoundTrip は応答を解釈しようとしてはいけません。特に, RoundTrip は,レスポンスの HTTP ステータスコードに関係なく,レスポンスを取得した場合は err == nil を返さなければなりません。応答を得られなかった場合に, nil 以外の err を使います。同様に, RoundTrip はリダイレクト,認証,または Cookie などの上位レベルのプロトコル詳細を処理しようとしてはいけません。
    //
    // RoundTrip は,リクエストのボディを消費して閉じる以外は,リクエストを変更してはいけません。 RoundTrip は別のゴルーチンでリクエストのフィールドを読むかもしれません。呼び出し側は,応答の本体が閉じられるまで,リクエストを変更したり再利用したりしないでください。
    //
    // RoundTrip はエラーを含めて常に本体を閉じる必要がありますが,実装によっては RoundTrip が戻った後でも別の goroutine で閉じることがあります。これは,後続のリクエストのために本体を再利用することを望んでいる呼び出し側が,そうする前に Close 呼び出しを待つように手配しなければならないことを意味します。
    //
    // リクエストの URL とヘッダーフィールドは初期化されなければなりません。
    RoundTrip(*Request) (*Response, error)
}

DefaultTransport は Transport のデフォルト実装であり, DefaultClient によって使用されます。必要に応じてネットワーク接続を確立し,後続の呼び出しで再利用するためにそれらをキャッシュします。 $HTTP_PROXY と $NO_PROXY (または $http_proxy と $no_proxy) 環境変数の指示に従って HTTP プロキシを使用します。

var DefaultTransport RoundTripper = &Transport{
    Proxy: ProxyFromEnvironment,
    DialContext: (&net.Dialer{
        Timeout:   30 * time.Second,
        KeepAlive: 30 * time.Second,
        DualStack: true,
    }).DialContext,
    ForceAttemptHTTP2:     true,
    MaxIdleConns:          100,
    IdleConnTimeout:       90 * time.Second,
    TLSHandshakeTimeout:   10 * time.Second,
    ExpectContinueTimeout: 1 * time.Second,
}

func NewFileTransport

func NewFileTransport(fs FileSystem) RoundTripper

NewFileTransport (新しいファイルトランスポート) は,指定された FileSystem を処理する新しい RoundTripper を返します。返された RoundTripper は,着信リクエスト内の URL ホスト,およびリクエストの他のほとんどのプロパティを無視します。

NewFileTransport の一般的な使用例は,次のように "ファイル" プロトコルをトランスポートに登録することです。

t := &http.Transport{}
t.RegisterProtocol("file", http.NewFileTransport(http.Dir("/")))
c := &http.Client{Transport: t}
res, err := c.Get("file:///etc/passwd")
...

type SameSite 1.11

SameSite (同じサイト) を使用すると,サーバーは cookie 属性を定義し,ブラウザはこの cookie をクロスサイトリクエストと一緒に送信できなくなります。主な目的は,クロスオリジン情報漏洩のリスクを軽減し,クロスサイトリクエストフォージェリ攻撃から保護することです。

詳細については https://tools.ietf.org/html/draft-ietf-httpbis-cookie-same-site-00 をご覧ください。

type SameSite int
const (
    SameSiteDefaultMode SameSite = iota + 1
    SameSiteLaxMode
    SameSiteStrictMode
    SameSiteNoneMode
)

type ServeMux

ServeMuxisanHTTPrequestmultiplexer.ItmatchestheURLofeachincomingrequestagainstalistofregisteredpatternsandcallsthehandlerforthepatternthatmostcloselymatchestheURL.

Patterns name fixed, rooted パス s,like"/favicon.ico",orrootedsubtrees,like"/images/"(notethetrailingslash).Longerpatternstakeprecedenceovershorterones,sothatiftherearehandlersregisteredforboth"/images/"and"/images/thumbnails/",thelatterhandlerwillbecalledfor パス sbeginning"/images/thumbnails/"andtheformerwill レシーバ equests for any other パス sinthe"/images/"subtree.

Notethatsinceapatternendinginaslashnamesarootedsubtree,thepattern"/"matchesall パス snotmatchedbyotherregisteredpatterns,notjusttheURLwithPath=="/".

Ifasubtreehasbeenregisteredandarequestisreceivednamingthesubtreerootwithoutitstrailingslash,ServeMuxredirectsthatrequesttothesubtreeroot(addingthetrailingslash).Thisbehaviorcanbeoverriddenwithaseparateregistrationforthe パス withoutthetrailingslash.Forexample,registering"/images/"causesServeMuxtoredirectarequestfor"/images"to"/images/",unless"/images"hasbeenregisteredseparately.

Patternsmayoptionallybeginwithahostname,restrictingmatchestoURLsonthathostonly.Host-specificpatternstakeprecedenceovergeneralpatterns,sothatahandlermightregisterforthetwopatterns"/codesearch"and"codesearch.google.com/"withoutalsotakingoverrequestsfor"http://www.google.com/".

ServeMux also takes care of sanitizing the URL request パス andtheHostheader,strippingtheportnumberandredirectinganyrequestcontaining.or..elementsorrepeatedslashestoanequivalent,cleanerURL.

type ServeMux struct {
    // エクスポートされていないフィールドがあります
}

func NewServeMux

func NewServeMux() *ServeMux

NewServeMux allocates and returns a new ServeMux.

func (*ServeMux) Handle

func (mux *ServeMux) Handle(pattern string, handler Handler)

Handleregistersthehandlerforthegivenpattern.Ifahandleralreadyexistsforpattern,Handlepanics.

コード:

mux := http.NewServeMux()
mux.Handle("/api/", apiHandler{})
mux.HandleFunc("/", func(w http.ResponseWriter, req *http.Request) {
    // "/" パターンはすべてに一致するので,
    // ここでルートにいることを確認する必要があります。
    if req.URL.Path != "/" {
        http.NotFound(w, req)
        return
    }
    fmt.Fprintf(w, "Welcome to the home page!")
})

func (*ServeMux) HandleFunc

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

HandleFunc registers the handler function for the given pattern.

func (*ServeMux) Handler 1.1

func (mux *ServeMux) Handler(r *Request) (h Handler, pattern string)

Handlerreturnsthehandlertouseforthegivenrequest,consultingr.Method,r.Host,andr.URL.Path.Italwaysreturnsanon-nilhandler.Ifthe パス isnotinitscanonicalform,thehandlerwillbeaninternally-generatedhandlerthatredirectstothecanonical パス .Ifthehostcontainsaport,itisignoredwhenmatchinghandlers.

The パス and host are used unchanged for CONNECT requests.

Handleralsoreturnstheregisteredpatternthatmatchestherequestor,inthecaseofinternally-generatedredirects,thepatternthatwillmatchafterfollowingtheredirect.

Ifthereisnoregisteredhandlerthatappliestotherequest,Handlerreturnsa“ ページ not found” handler and an empty pattern.

func (*ServeMux) ServeHTTP

func (mux *ServeMux) ServeHTTP(w ResponseWriter, r *Request)

ServeHTTPdispatchestherequesttothehandlerwhosepatternmostcloselymatchestherequestURL.

type Server

AServerdefinesparametersforrunninganHTTPserver.ThezerovalueforServerisavalidconfiguration.

type Server struct {
    Addr    string  // TCP address to listen on, ":http" if empty
    Handler Handler // handler to invoke, http.DefaultServeMux if nil

    // TLSConfigoptionallyprovidesaTLSconfigurationforusebyServeTLSandListenAndServeTLS.NotethatthisvalueisclonedbyServeTLSandListenAndServeTLS,soit'snotpossibletomodifytheconfigurationwithmethodsliketls.Config.SetSessionTicketKeys.TouseSetSessionTicketKeys,useServer.ServewithaTLSListenerinstead.
    TLSConfig *tls.Config

    // ReadTimeoutisthemaximumdurationforreadingtheentirerequest,includingthebody.
    //
    // BecauseReadTimeoutdoesnotletHandlersmakeper-requestdecisionsoneachrequestbody'sacceptabledeadlineoruploadrate,most ユーザ swillprefertouseReadHeaderTimeout.Itisvalidtousethemboth.
    ReadTimeout time.Duration

    // ReadHeaderTimeout is the amount of time allowed to read
    // request headers. The connection's read deadline is reset
    // after reading the headers and the Handler can decide what
    // is considered too slow for the body. If ReadHeaderTimeout
    // is zero, the value of ReadTimeout is used. If both are
    // zero, there is no timeout.
    ReadHeaderTimeout time.Duration // Go 1.8

    // WriteTimeoutisthemaximumdurationbeforetimingoutwritesoftheresponse.Itisresetwheneveranewrequest'sheaderisread.LikeReadTimeout,itdoesnotletHandlersmakedecisionsonaper-requestbasis.
    WriteTimeout time.Duration

    // IdleTimeout is the maximum amount of time to wait for the
    // next request when keep-alives are enabled. If IdleTimeout
    // is zero, the value of ReadTimeout is used. If both are
    // zero, there is no timeout.
    IdleTimeout time.Duration // Go 1.8

    // MaxHeaderBytescontrolsthemaximumnumberofbytestheserverwillreadparsingtherequestheader'skeysandvalues,includingtherequestline.Itdoesnotlimitthesizeoftherequestbody.Ifzero,DefaultMaxHeaderBytesisused.
    MaxHeaderBytes int

    // TLSNextProtooptionallyspecifiesafunctiontotakeoverownershipoftheprovidedTLSconnectionwhenanNPN/ALPNprotocolupgradehasoccurred.Themapkeyistheprotocolnamenegotiated.TheHandlerargumentshouldbeusedtohandleHTTPrequestsandwillinitializetheRequest'sTLSandRemoteAddrifnotalreadyset.Theconnectionisautomaticallyclosedwhenthefunctionreturns.IfTLSNextProtoisnotnil,HTTP/2supportisnotenabledautomatically.
    TLSNextProto map[string]func(*Server, *tls.Conn, Handler) // Go 1.1

    // ConnStatespecifiesanoptionalcallbackfunctionthatiscalledwhenaclientconnectionchangesstate.SeetheConnStatetypeandassociatedconstantsfordetails.
    ConnState func(net.Conn, ConnState) // Go 1.3

    // ErrorLogspecifiesanoptionalloggerforerrorsacceptingconnections,unexpectedbehaviorfromhandlers,andunderlyingFileSystemerrors.Ifnil,loggingisdoneviathelog パッケージ 's standard logger.
    ErrorLog *log.Logger // Go 1.3

    // BaseContext optionally specifies a function that returns
    // the base context for incoming requests on this server.
    // The provided Listener is the specific Listener that's
    // about to start accepting requests.
    // If BaseContext is nil, the default is context.Background().
    // If non-nil, it must return a non-nil context.
    BaseContext func(net.Listener) context.Context

    // ConnContext optionally specifies a function that modifies
    // the context used for a new connection c. The provided ctx
    // is derived from the base context and has a ServerContextKey
    // value.
    ConnContext func(ctx context.Context, c net.Conn) context.Context
    // エクスポートされていないフィールドがあります
}

func (*Server) Close 1.8

func (srv *Server) Close() error

Closeimmediatelyclosesallactivenet.ListenersandanyconnectionsinstateStateNew,StateActive,orStateIdle.Foragracefulshutdown,useShutdown.

Closedoesnotattempttoclose(anddoesnotevenknowabout)anyhijackedconnections,suchasWebSockets.

ClosereturnsanyerrorreturnedfromclosingtheServer'sunderlyingListener(s).

func (*Server) ListenAndServe

func (srv *Server) ListenAndServe() error

ListenAndServelistensontheTCPnetworkaddresssrv.AddrandthencallsServetohandlerequestsonincomingconnections.AcceptedconnectionsareconfiguredtoenableTCPkeep-alives.

If srv.Addr is blank, ":http" is used.

ListenAndServealwaysreturnsanon-nilerror.AfterShutdownorClose,thereturnederrorisErrServerClosed.

func (*Server) ListenAndServeTLS

func (srv *Server) ListenAndServeTLS(certFile, keyFile string) error

ListenAndServeTLSlistensontheTCPnetworkaddresssrv.AddrandthencallsServeTLStohandlerequestsonincomingTLSconnections.AcceptedconnectionsareconfiguredtoenableTCPkeep-alives.

FilenamescontainingacertificateandmatchingprivatekeyfortheservermustbeprovidedifneithertheServer'sTLSConfig.CertificatesnorTLSConfig.GetCertificatearepopulated.Ifthecertificateissignedbyacertificateauthority,thecertFileshouldbetheconcatenationoftheserver'scertificate,anyintermediates,andtheCA'scertificate.

If srv.Addr is blank, ":https" is used.

ListenAndServeTLSalwaysreturnsanon-nilerror.AfterShutdownorClose,thereturnederrorisErrServerClosed.

func (*Server) RegisterOnShutdown 1.9

func (srv *Server) RegisterOnShutdown(f func())

RegisterOnShutdownregistersafunctiontocallonShutdown.ThiscanbeusedtogracefullyshutdownconnectionsthathaveundergoneNPN/ALPNprotocolupgradeorthathavebeenhijacked.Thisfunctionshouldstartprotocol-specificgracefulshutdown,butshouldnotwaitforshutdowntocomplete.

func (*Server) Serve

func (srv *Server) Serve(l net.Listener) error

ServeacceptsincomingconnectionsontheListenerl,creatinganewservicegoroutineforeach.Theservicegoroutinesreadrequestsandthencallsrv.Handlertoreplytothem.

HTTP/2supportisonlyenablediftheListenerreturns*tls.Connconnectionsandtheywereconfiguredwith"h2"intheTLSConfig.NextProtos.

Servealwaysreturnsanon-nilerrorandclosesl.AfterShutdownorClose,thereturnederrorisErrServerClosed.

func (*Server) ServeTLS 1.9

func (srv *Server) ServeTLS(l net.Listener, certFile, keyFile string) error

ServeTLSacceptsincomingconnectionsontheListenerl,creatinganewservicegoroutineforeach.TheservicegoroutinesperformTLSsetupandthenreadrequests,callingsrv.Handlertoreplytothem.

FilescontainingacertificateandmatchingprivatekeyfortheservermustbeprovidedifneithertheServer'sTLSConfig.CertificatesnorTLSConfig.GetCertificatearepopulated.Ifthecertificateissignedbyacertificateauthority,thecertFileshouldbetheconcatenationoftheserver'scertificate,anyintermediates,andtheCA'scertificate.

ServeTLSalwaysreturnsanon-nilerror.AfterShutdownorClose,thereturnederrorisErrServerClosed.

func (*Server) SetKeepAlivesEnabled 1.3

func (srv *Server) SetKeepAlivesEnabled(v bool)

SetKeepAlivesEnabledcontrolswhetherHTTPkeep-alivesareenabled.Bydefault,keep-alivesarealwaysenabled.Onlyveryresource-constrainedenvironmentsorserversintheprocessofshuttingdownshoulddisablethem.

func (*Server) Shutdown 1.8

func (srv *Server) Shutdown(ctx context.Context) error

Shutdowngracefullyshutsdowntheserverwithoutinterruptinganyactiveconnections.Shutdownworksbyfirstclosingallopenlisteners,thenclosingallidleconnections,andthenwaitingindefinitelyforconnectionstoreturntoidleandthenshutdown.Iftheprovidedcontextexpiresbeforetheshutdowniscomplete,Shutdownreturnsthecontext'serror,otherwiseitreturnsanyerrorreturnedfromclosingtheServer'sunderlyingListener(s).

WhenShutdowniscalled,Serve,ListenAndServe,andListenAndServeTLSimmediatelyreturnErrServerClosed.Makesurethe プログラム doesn't exit and waits instead for Shutdown to return.

ShutdowndoesnotattempttoclosenorwaitforhijackedconnectionssuchasWebSockets.ThecallerofShutdownshouldseparatelynotifysuchlong-livedconnectionsofshutdownandwaitforthemtoclose,ifdesired.SeeRegisterOnShutdownforawaytoregistershutdownnotificationfunctions.

OnceShutdownhasbeencalledonaserver,itmaynotbereused;futurecallstomethodssuchasServewillreturnErrServerClosed.

コード:

var srv http.Server

idleConnsClosed := make(chan struct{})
go func() {
    sigint := make(chan os.Signal, 1)
    signal.Notify(sigint, os.Interrupt)
    <-sigint

    // 割り込みシグナルを受け取りました。シャットダウンします。
    if err := srv.Shutdown(context.Background()); err != nil {
        // リスナーを閉じることによるエラー,またはコンテキストのタイムアウト:
        log.Printf("HTTP server Shutdown: %v", err)
    }
    close(idleConnsClosed)
}()

if err := srv.ListenAndServe(); err != http.ErrServerClosed {
    // リスナーの開始または終了時にエラーが発生しました。
    log.Fatalf("HTTP server ListenAndServe: %v", err)
}

<-idleConnsClosed

type Transport

Transport は, HTTP , HTTPS ,および HTTP プロキシをサポートする RoundTripper の実装です (HTTP または HTTPS with CONNECT) 。

デフォルトでは, Transport は将来の再利用のために接続をキャッシュします。多くのホストにアクセスするとき,これは多くの開いた接続を残すかもしれません。この動作は, Transport の CloseIdleConnections メソッドと, MaxIdleConnsPerHost フィールドと DisableKeepAlives フィールドを使用して管理できます。

トランスポートは必要に応じて作成するのではなく再利用する必要があります。トランスポートは複数のゴルーチンによる平行使用に対して安全です。

Transport は, HTTP および HTTPS リクエストを行うための低レベルのプリミティブです。クッキーやリダイレクトなどの高度な機能については,クライアントを参照してください。

サーバーが HTTP/2 をサポートしているかどうか,およびトランスポートの構成方法に応じて,トランスポートは HTTP URL に HTTP/1.1 を使用し, HTTPS URL に HTTP/1.1 または HTTP/2 を使用します。 DefaultTransport は HTTP/2 をサポートしています。トランスポートで HTTP/2 を明示的に有効にするには, golang.org/x/net/http2 を使用して ConfigureTransport を呼び出します。 HTTP/2 についての詳細はパッケージのドキュメントを参照してください。

1xx の範囲内の状況コードを持つ応答は,自動的に処理される (100 expect-continue) か無視されます。唯一の例外は HTTP ステータスコード 101 (Switching Protocols) です。これは端末ステータスと見なされ, RoundTrip によって返されます。無視された 1xx 応答を確認するには, httptrace トレースパッケージの ClientTrace.Got1xxResponse を使用してください。

リクエストがべき等であり,ボディがないか,またはその Request.GetBody が定義されている場合にのみ,トランスポートはネットワークエラーが発生したときにリクエストを再試行します。 HTTP メソッドに HTTP メソッド GET, HEAD, OPTIONS ,または TRACE がある場合,それらの HTTP リクエストはべき等と見なされます。または,それらのヘッダーマップに "Idempotency-Key" または "X-Idempotency-Key" エントリが含まれている場合。べき等性キー値が長さゼロのスライスの場合,リクエストはべき等性として扱われますが,ヘッダーはワイヤ上に送信されません。

type Transport struct {

    // Proxy は与えられたリクエストに対してプロキシを返す関数を指定します。関数が nil 以外のエラーを返した場合,リクエストは渡されたエラーで中止されます。
    //
    // プロキシタイプは URL スキームによって決まります。 "http" , "https" ,および "socks5" がサポートされています。スキームが空の場合は, "http" が想定されます。
    //
    // Proxy が nil または nil *URL を返す場合,プロキシは使用されません。
    Proxy func(*Request) (*url.URL, error)

    // DialContext は,暗号化されていない TCP 接続を作成するためのダイヤル関数を指定します。 DialContext が nil である (そして以下の非推奨の Dial も nil である) 場合,トランスポートはパッケージ net を使用してダイヤルします。
    //
    // DialContext は RoundTrip の呼び出しと平行に実行されます。ダイヤルを開始する RoundTrip 呼び出しは,後の DialContext が完了する前に前の接続がアイドルになったときに,以前にダイヤルされた接続を使用することになります。
    DialContext func(ctx context.Context, network, addr string) (net.Conn, error) // Go 1.7

    // Dial は,暗号化されていない TCP 接続を作成するためのダイヤル関数を指定します。
    //
    // RoundTrip への呼び出しと平行にダイヤルが実行されます。ダイヤルを開始する RoundTrip 呼び出しは,後のダイヤルが完了する前に前の接続がアイドルになったときに,以前にダイヤルされた接続を使用することになります。
    //
    // 非推奨 : 代わりに DialContext を使用します。これにより,トランスポートはダイヤルが不要になるとすぐにダイヤルをキャンセルできます。両方が設定されている場合, DialContext が優先されます。
    Dial func(network, addr string) (net.Conn, error)

    // DialTLS は,プロキシされていない HTTPS リクエストに対して TLS 接続を作成するためのオプションのダイヤル関数を指定します。
    //
    // DialTLS が nil の場合, Dial と TLSClientConfig が使用されます。
    //
    // DialTLS が設定されている場合, Dial フックは HTTPS リクエストには使用されず, TLSClientConfig および TLSHandshakeTimeout は無視されます。返された net.Conn はすでに TLS ハンドシェイクを過ぎていると見なされます。
    DialTLS func(network, addr string) (net.Conn, error) // Go 1.4

    // TLSClientConfig は, tls.Client とともに使用する TLS 構成を指定します。 nil の場合,デフォルト設定が使用されます。 nil 以外の場合, HTTP/2 サポートはデフォルトで有効にならないかもしれません。
    TLSClientConfig *tls.Config

    // TLSHandshakeTimeout は, TLS ハンドシェイクを待つために待機する最大時間を指定します。ゼロはタイムアウトなしを意味します。
    TLSHandshakeTimeout time.Duration // Go 1.3

    // DisableKeepAlives が true の場合, HTTP キープアライブが無効になり, 1 つの HTTP リクエストに対してサーバーへの接続のみが使用されます。
    //
    // これは,同じ名前の TCP キープアライブとは無関係です。
    DisableKeepAlives bool

    // DisableCompression が true の場合, Request に既存の Accept-Encoding 値が含まれていないときに, Transport が "Accept-Encoding: gzip" リクエストヘッダーを使用して圧縮をリクエストしないようにします。トランスポートが独自に gzip をリクエストし, gzip された応答を受け取ると, Response.Body で透過的にデコードされます。ただし,ユーザーが gzip を明示的にリクエストした場合,自動的に解凍されるわけではありません。
    DisableCompression bool

    // MaxIdleConns は,すべてのホストにわたるアイドル (キープアライブ) 接続の最大数を制御します。ゼロは無制限を意味します。
    MaxIdleConns int // Go 1.7

    // MaxIdleConnsPerHost が 0 以外の場合,ホストごとに保持する最大アイドル (キープアライブ) 接続を制御します。ゼロの場合, DefaultMaxIdleConnsPerHost が使用されます。
    MaxIdleConnsPerHost int

    // MaxConnsPerHost は,ダイヤル,アクティブ,およびアイドル状態の接続を含む,ホストあたりの接続の総数をオプションで制限します。制限違反では,ダイヤルはブロックされます。
    //
    // ゼロは無制限を意味します。
    MaxConnsPerHost int // Go 1.11

    // IdleConnTimeout は,アイドル状態 (キープアライブ) 接続が自動的に閉じられるまでアイドル状態のままになる最大時間です。
    // ゼロは無制限を意味します。
    IdleConnTimeout time.Duration // Go 1.7

    // ResponseHeaderTimeout は,ゼロ以外の場合,リクエストが完全に書き込まれた後でサーバーの応答ヘッダーを待機する時間 (存在する場合はそのボディも含む) を指定します。
    // この時間には,応答ボディを読み取るための時間は含まれていません。
    ResponseHeaderTimeout time.Duration // Go 1.1

    // ExpectContinueTimeout が 0 以外の場合,リクエストに "Expect: 100-continue" ヘッダーが含まれている場合に,リクエストヘッダーを完全に書き込んだ後にサーバーの最初の応答ヘッダーを待つ時間を指定します。ゼロはタイムアウトがないことを意味し,サーバーが承認するのを待たずにボディがすぐに送信されるようにします。この時間には,リクエストヘッダーを送信する時間は含まれていません。
    ExpectContinueTimeout time.Duration // Go 1.6

    // TLSNextProto は, TLS NPN/ALPN プロトコルネゴシエーション後にトランスポートが代替プロトコル (HTTP/2 など) に切り替える方法を指定します。 Transport が空でないプロトコル名で TLS 接続をダイヤルし, TLSNextProto がそのキーのマップエントリ ("h2" など) を含む場合, func はリクエストの権限 ("example.com" または "example" など) で呼び出されます。と TLS 接続です。この関数は RoundTripper を返す必要があります。この RoundTripper はリクエストを処理します。 TLSNextProto が nil 以外の場合, HTTP/2 サポートは自動的に有効になりません。
    TLSNextProto map[string]func(authority string, c *tls.Conn) RoundTripper // Go 1.6

    // ProxyConnectHeader は, CONNECT リクエスト中にプロキシに送信するヘッダーをオプションで指定します。
    ProxyConnectHeader Header // Go 1.8

    // MaxResponseHeaderBytes は,サーバーの応答ヘッダーに許可される応答バイト数の制限を指定します。
    //
    // ゼロはデフォルトの制限を使用することを意味します。
    MaxResponseHeaderBytes int64 // Go 1.7

    // WriteBufferSize specifies the size of the write buffer used
    // when writing to the transport.
    // If zero, a default (currently 4KB) is used.
    WriteBufferSize int

    // ReadBufferSize specifies the size of the read buffer used
    // when reading from the transport.
    // If zero, a default (currently 4KB) is used.
    ReadBufferSize int

    // ForceAttemptHTTP2 controls whether HTTP/2 is enabled when a non-zero
    // Dial, DialTLS, or DialContext func or TLSClientConfig is provided.
    // By default, use of any those fields conservatively disables HTTP/2.
    // To use a custom dialer or TLS config and still attempt HTTP/2
    // upgrades, set this to true.
    ForceAttemptHTTP2 bool
    // エクスポートされていないフィールドがあります
}

func (*Transport) CancelRequest 1.1

func (t *Transport) CancelRequest(req *Request)

CancelRequest は,接続を閉じることによって機内リクエストをキャンセルします。 CancelRequest は RoundTrip が戻った後にのみ呼び出されるべきです。

非推奨 : 代わりに,キャンセル可能なコンテキストを使用してリクエストを作成するには, Request.WithContext を使用してください。 CancelRequest は HTTP/2 リクエストをキャンセルできません。

func (*Transport) Clone

func (t *Transport) Clone() *Transport

Clone returns a deep copy of t's exported fields.

func (*Transport) CloseIdleConnections

func (t *Transport) CloseIdleConnections()

CloseIdleConnections は,以前のリクエストから以前に接続されていたが,現在は " キープアライブ " 状態でアイドル状態になっている接続をすべて閉じます。現在使用中の接続を中断することはありません。

func (*Transport) RegisterProtocol

func (t *Transport) RegisterProtocol(scheme string, rt RoundTripper)

RegisterProtocol は新しいプロトコルを scheme に登録します。 Transport は与えられたスキームを使ってリクエストを rt に渡します。 HTTP リクエストのセマンティクスをシミュレートするのは rt の責任です。

RegisterProtocol は, "ftp" や "file" のようなプロトコルスキームの実装を提供するために他のパッケージで使用することができます。

rt.RoundTrip が ErrSkipAltProtocol を返す場合,トランスポートはあたかもプロトコルが登録されていないかのように,その 1 つのリクエストに対して RoundTrip 自体を処理します。

func (*Transport) RoundTrip

func (t *Transport) RoundTrip(req *Request) (*Response, error)

RoundTrip は RoundTripper インターフェースを実装します。

高レベルの HTTP クライアントサポート (Cookie やリダイレクトの処理など) については, Get, Post, Client 型を参照してください。

RoundTripper インターフェースと同様に, RoundTrip によって返されるエラー型は指定されていません。

サブディレクトリ

名前 概要
..
cgi cgi パッケージは RFC 3875 で定義された CGI (Common Gateway Interface) を実装します。
cookiejar cookiejar パッケージは,インメモリの RFC 6265 に適合した http.CookieJar を実装します。
fcgi fcgi パッケージは, FastCGI プロトコルを実装します。
httptest httptest パッケージは,HTTP テストに便利な関数を提供します。
httptrace httptrace パッケージは, HTTP クライアントリクエストにおけるイベントを追跡する機構を提供します。
httputil httputil パッケージは, net/http パッケージにある関数を補完し,HTTP でよく使われる関数を提供します。
pprof pprof パッケージは,pprof 視覚化ツールのフォーマットで HTTP サーバ ランタイムプロファイルデータを提供します。