...
Run Format

Source file src/net/http/doc.go

     1	// Copyright 2011 The Go Authors. All rights reserved.
     2	// Use of this source code is governed by a BSD-style
     3	// license that can be found in the LICENSE file.
     4	
     5	/*
     6	Package http provides HTTP client and server implementations.
     7	
     8	Get, Head, Post, and PostForm make HTTP (or HTTPS) requests:
     9	
    10		resp, err := http.Get("http://example.com/")
    11		...
    12		resp, err := http.Post("http://example.com/upload", "image/jpeg", &buf)
    13		...
    14		resp, err := http.PostForm("http://example.com/form",
    15			url.Values{"key": {"Value"}, "id": {"123"}})
    16	
    17	The client must close the response body when finished with it:
    18	
    19		resp, err := http.Get("http://example.com/")
    20		if err != nil {
    21			// handle error
    22		}
    23		defer resp.Body.Close()
    24		body, err := ioutil.ReadAll(resp.Body)
    25		// ...
    26	
    27	For control over HTTP client headers, redirect policy, and other
    28	settings, create a Client:
    29	
    30		client := &http.Client{
    31			CheckRedirect: redirectPolicyFunc,
    32		}
    33	
    34		resp, err := client.Get("http://example.com")
    35		// ...
    36	
    37		req, err := http.NewRequest("GET", "http://example.com", nil)
    38		// ...
    39		req.Header.Add("If-None-Match", `W/"wyzzy"`)
    40		resp, err := client.Do(req)
    41		// ...
    42	
    43	For control over proxies, TLS configuration, keep-alives,
    44	compression, and other settings, create a Transport:
    45	
    46		tr := &http.Transport{
    47			MaxIdleConns:       10,
    48			IdleConnTimeout:    30 * time.Second,
    49			DisableCompression: true,
    50		}
    51		client := &http.Client{Transport: tr}
    52		resp, err := client.Get("https://example.com")
    53	
    54	Clients and Transports are safe for concurrent use by multiple
    55	goroutines and for efficiency should only be created once and re-used.
    56	
    57	ListenAndServe starts an HTTP server with a given address and handler.
    58	The handler is usually nil, which means to use DefaultServeMux.
    59	Handle and HandleFunc add handlers to DefaultServeMux:
    60	
    61		http.Handle("/foo", fooHandler)
    62	
    63		http.HandleFunc("/bar", func(w http.ResponseWriter, r *http.Request) {
    64			fmt.Fprintf(w, "Hello, %q", html.EscapeString(r.URL.Path))
    65		})
    66	
    67		log.Fatal(http.ListenAndServe(":8080", nil))
    68	
    69	More control over the server's behavior is available by creating a
    70	custom Server:
    71	
    72		s := &http.Server{
    73			Addr:           ":8080",
    74			Handler:        myHandler,
    75			ReadTimeout:    10 * time.Second,
    76			WriteTimeout:   10 * time.Second,
    77			MaxHeaderBytes: 1 << 20,
    78		}
    79		log.Fatal(s.ListenAndServe())
    80	
    81	Starting with Go 1.6, the http package has transparent support for the
    82	HTTP/2 protocol when using HTTPS. Programs that must disable HTTP/2
    83	can do so by setting Transport.TLSNextProto (for clients) or
    84	Server.TLSNextProto (for servers) to a non-nil, empty
    85	map. Alternatively, the following GODEBUG environment variables are
    86	currently supported:
    87	
    88		GODEBUG=http2client=0  # disable HTTP/2 client support
    89		GODEBUG=http2server=0  # disable HTTP/2 server support
    90		GODEBUG=http2debug=1   # enable verbose HTTP/2 debug logs
    91		GODEBUG=http2debug=2   # ... even more verbose, with frame dumps
    92	
    93	The GODEBUG variables are not covered by Go's API compatibility
    94	promise. Please report any issues before disabling HTTP/2
    95	support: https://golang.org/s/http2bug
    96	
    97	The http package's Transport and Server both automatically enable
    98	HTTP/2 support for simple configurations. To enable HTTP/2 for more
    99	complex configurations, to use lower-level HTTP/2 features, or to use
   100	a newer version of Go's http2 package, import "golang.org/x/net/http2"
   101	directly and use its ConfigureTransport and/or ConfigureServer
   102	functions. Manually configuring HTTP/2 via the golang.org/x/net/http2
   103	package takes precedence over the net/http package's built-in HTTP/2
   104	support.
   105	
   106	*/
   107	package http
   108	

View as plain text