Пакет url
Обзор
Пакет url анализирует URL-адреса и реализует экранирование запросов.
Индекс
Примеры
- ParseQuery
- PathEscape
- PathUnescape
- QueryEscape
- QueryUnescape
- URL
- URL.EscapedFragment
- URL.EscapedPath
- URL.Hostname
- URL.IsAbs
- URL.JoinPath
- URL.MarshalBinary
- URL.Parse
- URL.Port
- URL.Query
- URL.Redacted
- URL.RequestURI
- URL.ResolveReference
- URL.String
- URL.UnmarshalBinary
- URL (Раундтрип)
- Values
- Values.Add
- Values.Del
- Values.Encode
- Values.Get
- Values.Has
- Values.Set
Файлы пакета
url.go
func JoinPath 1.19
func JoinPath(base string, elem ...string) (result string, err error)
JoinPath возвращает строку URL с объединенными элементами пути к существующему пути base, а результирующий путь очищается от элементов ./ или ../.
func PathEscape 1.8
func PathEscape(s string) string
PathEscape экранирует строку, чтобы она могла безопасно размещаться в сегменте пути URL, заменяя специальные символы (включая /) на последовательности %XX по мере необходимости.
Пример
Код:
path := url.PathEscape("my/cool+blog&about,stuff")
fmt.Println(path)
Вывод:
my%2Fcool+blog&about%2Cstuff
func PathUnescape 1.8
func PathUnescape(s string) (string, error)
PathUnescape выполняет обратное преобразование PathEscape, преобразуя каждую 3-байтовую закодированную подстроку вида «%AB» в шестнадцатерично декодированный байт 0xAB. Возвращает ошибку, если любой «%» не следует за двумя шестнадцатеричными цифрами.
PathUnescape идентичен QueryUnescape, за исключением того, что он не экранирует '+' в ' ' (пробел).
Пример
Код:
escapedPath := "my%2Fcool+blog&about%2Cstuff"
path, err := url.PathUnescape(escapedPath)
if err != nil {
log.Fatal(err)
}
fmt.Println(path)
Вывод:
my/cool+blog&about,stuff
func QueryEscape
func QueryEscape(s string) string
QueryEscape экранирует строку, чтобы она могла безопасно размещаться в запросе URL.
Пример
Код:
query := url.QueryEscape("my/cool+blog&about,stuff")
fmt.Println(query)
Вывод:
my%2Fcool%2Bblog%26about%2Cstuff
func QueryUnescape
func QueryUnescape(s string) (string, error)
QueryUnescape выполняет обратное преобразование QueryEscape, преобразуя каждую 3-байтовую закодированную подстроку вида «%AB» в шестнадцатерично декодированный байт 0xAB. Возвращает ошибку, если любой «%» не следует за двумя шестнадцатеричными цифрами.
Пример
Код:
escapedQuery := "my%2Fcool%2Bblog%26about%2Cstuff"
query, err := url.QueryUnescape(escapedQuery)
if err != nil {
log.Fatal(err)
}
fmt.Println(query)
Вывод:
my/cool+blog&about,stuff
тип Error
Error сообщает об ошибке и операции и URL, которые ее вызвали.
type Error struct {
Op string
URL string
Err error
}
func (*Error) Error
func (e *Error) Error() string
func (*Error) Temporary 1.6
func (e *Error) Temporary() bool
func (*Error) Timeout 1.6
func (e *Error) Timeout() bool
func (*Error) Unwrap 1.13
func (e *Error) Unwrap() error
тип EscapeError
type EscapeError string
func (EscapeError) Error
func (e EscapeError) Error() string
тип InvalidHostError 1.6
type InvalidHostError string
func (InvalidHostError) Error 1.6
func (e InvalidHostError) Error() string
тип URL
URL представляет собой обработанный URL-адрес (в техническом смысле, URI-ссылка).
Общий представленный вид:
[scheme:][//[userinfo@]host][/]path[?query][#fragment]
URL, которые не начинаются с косой черты после схемы, интерпретируются как:
scheme:opaque[?query][#fragment]
Поле Host содержит компоненты хоста и порта URL-адреса. Когда порт присутствует, он отделяется от хоста двоеточием. Когда хост является IPv6-адресом, он должен быть заключен в квадратные скобки: "[fe80::1]:80". Функция net.JoinHostPort объединяет хост и порт в строку, подходящую для поля Host, добавляя квадратные скобки к хосту при необходимости.
Обратите внимание, что поле Path хранится в декодированной форме: /%47%6f%2f становится /Go/. Следствием является невозможность определить, какие косые черты в Path были косыми чертами в исходном URL-адресе, а какие — %2f. Это различие редко имеет значение, но когда это необходимо, код должен использовать метод URL.EscapedPath, который сохраняет исходное кодирование Path.
Поле RawPath — необязательное поле, которое устанавливается только тогда, когда стандартное кодирование Path отличается от экранированного пути. Подробнее см. в методе EscapedPath.
Метод String объекта URL использует метод EscapedPath для получения пути.
type URL struct {
Scheme string
Opaque string // encoded opaque data
User *Userinfo // username and password information
Host string // host or host:port (see Hostname and Port methods)
Path string // path (relative paths may omit leading slash)
RawPath string // encoded path hint (see EscapedPath method); added in Go 1.5
OmitHost bool // do not emit empty host (authority); added in Go 1.19
ForceQuery bool // append a query ('?') even if RawQuery is empty; added in Go 1.7
RawQuery string // encoded query values, without '?'
Fragment string // fragment for references, without '#'
RawFragment string // encoded fragment hint (see EscapedFragment method); added in Go 1.15
}
Пример
Код:
u, err := url.Parse("http://bing.com/search?q=dotnet")
if err != nil {
log.Fatal(err)
}
u.Scheme = "https"
u.Host = "google.com"
q := u.Query()
q.Set("q", "golang")
u.RawQuery = q.Encode()
fmt.Println(u)
Вывод:
https://google.com/search?q=golang
Пример (Раундтрип)
Код:
// Parse + String preserve the original encoding.
u, err := url.Parse("https://example.com/foo%2fbar")
if err != nil {
log.Fatal(err)
}
fmt.Println(u.Path)
fmt.Println(u.RawPath)
fmt.Println(u.String())
Вывод:
/foo/bar /foo%2fbar https://example.com/foo%2fbar
func Parse
func Parse(rawURL string) (*URL, error)
Parse анализирует исходный URL-адрес в структуру URL.
URL-адрес может быть относительным (путь без хоста) или абсолютным (начинающимся со схемы). Попытка проанализировать имя хоста и путь без схемы недействительна, но необязательно возвращает ошибку из-за неоднозначностей при анализе.
func ParseRequestURI
func ParseRequestURI(rawURL string) (*URL, error)
ParseRequestURI анализирует исходный URL-адрес в структуру URL. Предполагается, что URL-адрес получен в HTTP-запросе, поэтому URL-адрес интерпретируется только как абсолютный URI или абсолютный путь. Строка url предполагается не содержащей суффикса #fragment. (Веб-браузеры удаляют #fragment перед отправкой URL-адреса веб-серверу.)
func (*URL) AppendBinary 1.24
func (u *URL) AppendBinary(b []byte) ([]byte, error)
func (*URL) EscapedFragment 1.15
func (u *URL) EscapedFragment() string
EscapedFragment возвращает экранированную форму u.Fragment. В целом существует несколько возможных экранированных форм любого фрагмента. EscapedFragment возвращает u.RawFragment, если это действительное экранирование u.Fragment. В противном случае EscapedFragment игнорирует u.RawFragment и вычисляет собственную экранированную форму. Метод URL.String использует EscapedFragment для построения своего результата. В общем случае код должен вызывать EscapedFragment вместо непосредственного чтения u.RawFragment.
Пример
Код:
u, err := url.Parse("http://example.com/#x/y%2Fz")
if err != nil {
log.Fatal(err)
}
fmt.Println("Fragment:", u.Fragment)
fmt.Println("RawFragment:", u.RawFragment)
fmt.Println("EscapedFragment:", u.EscapedFragment())
Вывод:
Fragment: x/y/z RawFragment: x/y%2Fz EscapedFragment: x/y%2Fz
func (*URL) EscapedPath 1.5
func (u *URL) EscapedPath() string
EscapedPath возвращает экранированную форму u.Path. В целом существует несколько возможных экранированных форм любого пути. EscapedPath возвращает u.RawPath, если это действительное экранирование u.Path. В противном случае EscapedPath игнорирует u.RawPath и вычисляет собственную экранированную форму. Методы URL.String и URL.RequestURI используют EscapedPath для построения своих результатов. В общем случае код должен вызывать EscapedPath вместо непосредственного чтения u.RawPath.
Пример
Код:
u, err := url.Parse("http://example.com/x/y%2Fz")
if err != nil {
log.Fatal(err)
}
fmt.Println("Path:", u.Path)
fmt.Println("RawPath:", u.RawPath)
fmt.Println("EscapedPath:", u.EscapedPath())
Вывод:
Path: /x/y/z RawPath: /x/y%2Fz EscapedPath: /x/y%2Fz
func (*URL) Hostname 1.8
func (u *URL) Hostname() string
Hostname возвращает u.Host, удаляя любой допустимый номер порта, если он присутствует.
Если результат заключён в квадратные скобки, как это происходит с литеральными адресами IPv6, то квадратные скобки из результата удаляются.
Пример
Код:
u, err := url.Parse("https://example.org:8000/path")
if err != nil {
log.Fatal(err)
}
fmt.Println(u.Hostname())
u, err = url.Parse("https://[2001:0db8:85a3:0000:0000:8a2e:0370:7334]:17000")
if err != nil {
log.Fatal(err)
}
fmt.Println(u.Hostname())
Вывод:
example.org 2001:0db8:85a3:0000:0000:8a2e:0370:7334
func (*URL) IsAbs
func (u *URL) IsAbs() bool
IsAbs сообщает, является ли URL абсолютным. Абсолютным означает, что у него есть непустой схему.
Пример
Код:
u := url.URL{Host: "example.com", Path: "foo"}
fmt.Println(u.IsAbs())
u.Scheme = "http"
fmt.Println(u.IsAbs())
Вывод:
false true
func (*URL) JoinPath 1.19
func (u *URL) JoinPath(elem ...string) *URL
JoinPath возвращает новый URL с предоставленными элементами пути, соединёнными с любым существующим путём, и полученный путь очищен от элементов ./ или ../. Любые последовательности нескольких символов / будут сведены к одному /.
Пример
Код:
u, err := url.Parse("https://example.com/foo/bar")
if err != nil {
log.Fatal(err)
}
fmt.Println(u.JoinPath("baz", "qux"))
Вывод:
https://example.com/foo/bar/baz/qux
func (*URL) MarshalBinary 1.8
func (u *URL) MarshalBinary() (text []byte, err error)
Пример
Код:
u, _ := url.Parse("https://example.org")
b, err := u.MarshalBinary()
if err != nil {
log.Fatal(err)
}
fmt.Printf("%s\n", b)
Вывод:
https://example.org
func (*URL) Parse
func (u *URL) Parse(ref string) (*URL, error)
Parse парсит URL в контексте получателя. Предоставленный URL может быть относительным или абсолютным. Parse возвращает nil, err при сбое разбора, в противном случае его возвращаемое значение такое же, как у URL.ResolveReference.
Пример
Код:
u, err := url.Parse("https://example.org")
if err != nil {
log.Fatal(err)
}
rel, err := u.Parse("/foo")
if err != nil {
log.Fatal(err)
}
fmt.Println(rel)
_, err = u.Parse(":foo")
if _, ok := err.(*url.Error); !ok {
log.Fatal(err)
}
Вывод:
https://example.org/foo
func (*URL) Port 1.8
func (u *URL) Port() string
Port возвращает часть порта u.Host без ведущей двоеточия.
Если u.Host не содержит допустимого числового порта, Port возвращает пустую строку.
Пример
Код:
u, err := url.Parse("https://example.org")
if err != nil {
log.Fatal(err)
}
fmt.Println(u.Port())
u, err = url.Parse("https://example.org:8080")
if err != nil {
log.Fatal(err)
}
fmt.Println(u.Port())
Вывод:
8080
func (*URL) Query
func (u *URL) Query() Values
Query парсит RawQuery и возвращает соответствующие значения. Он безмолвно отбрасывает неправильно сформированные пары ключ-значение. Чтобы проверить ошибки, используйте ParseQuery.
Пример
Код:
u, err := url.Parse("https://example.org/?a=1&a=2&b=&=3&&&&")
if err != nil {
log.Fatal(err)
}
q := u.Query()
fmt.Println(q["a"])
fmt.Println(q.Get("b"))
fmt.Println(q.Get(""))
Вывод:
[1 2] 3
func (*URL) Redacted 1.15
func (u *URL) Redacted() string
Redacted аналогичен URL.String, но заменяет любой пароль на "xxxxx". Заменяется только пароль в u.User.
Пример
Код:
u := &url.URL{
Scheme: "https",
User: url.UserPassword("user", "password"),
Host: "example.com",
Path: "foo/bar",
}
fmt.Println(u.Redacted())
u.User = url.UserPassword("me", "newerPassword")
fmt.Println(u.Redacted())
Вывод:
https://user:xxxxx@example.com/foo/bar https://me:xxxxx@example.com/foo/bar
func (*URL) RequestURI
func (u *URL) RequestURI() string
RequestURI возвращает закодированную строку пути?запрос или непрозрачную?строку запроса, которая использовалась бы в HTTP-запросе для u.
Пример
Код:
u, err := url.Parse("https://example.org/path?foo=bar")
if err != nil {
log.Fatal(err)
}
fmt.Println(u.RequestURI())
Вывод:
/path?foo=bar
func (*URL) ResolveReference
func (u *URL) ResolveReference(ref *URL) *URL
ResolveReference разрешает ссылку URI в абсолютный URI от абсолютного базового URI u, согласно RFC 3986 Раздел 5.2. Ссылка URI может быть относительной или абсолютной. ResolveReference всегда возвращает новый экземпляр URL, даже если возвращаемый URL идентичен либо базовому, либо ссылке. Если ref является абсолютным URL, то ResolveReference игнорирует base и возвращает копию ref.
Пример
Код:
u, err := url.Parse("../../..//search?q=dotnet")
if err != nil {
log.Fatal(err)
}
base, err := url.Parse("http://example.com/directory/")
if err != nil {
log.Fatal(err)
}
fmt.Println(base.ResolveReference(u))
Вывод:
http://example.com/search?q=dotnet
func (*URL) String
func (u *URL) String() string
String повторно собирает URL в допустимую строку URL. Общий вид результата — один из:
scheme:opaque?query#fragment scheme://userinfo@host/path?query#fragment
Если u.Opaque не пусто, String использует первый формат; в противном случае он использует второй формат. Любые не-ASCII символы в имени хоста экранируются. Для получения пути String использует u.EscapedPath().
Во втором формате применяются следующие правила:
- если u.Scheme пусто, схема: опускается.
- если u.User равен nil, userinfo@ опускается.
- если u.Host пусто, host/ опускается.
- если u.Scheme и u.Host пусты, а u.User равен nil, вся схема://userinfo@host/ опускается.
- если u.Host не пусто, а u.Path начинается с /, формат host/path не добавляет свой /.
- если u.RawQuery пусто, ?query опускается.
- если u.Fragment пусто, #fragment опускается.
Пример
Код:
u := &url.URL{
Scheme: "https",
User: url.UserPassword("me", "pass"),
Host: "example.com",
Path: "foo/bar",
RawQuery: "x=1&y=2",
Fragment: "anchor",
}
fmt.Println(u.String())
u.Opaque = "opaque"
fmt.Println(u.String())
Вывод:
https://me:pass@example.com/foo/bar?x=1&y=2#anchor https:opaque?x=1&y=2#anchor
func (*URL) UnmarshalBinary 1.8
func (u *URL) UnmarshalBinary(text []byte) error
Пример
Код:
u := &url.URL{}
err := u.UnmarshalBinary([]byte("https://example.org/foo"))
if err != nil {
log.Fatal(err)
}
fmt.Printf("%s\n", u)
Вывод:
https://example.org/foo
type Userinfo
Тип Userinfo — это неизменяемая оболочка данных имени пользователя и пароля для URL. Существующее значение Userinfo гарантированно имеет установленное имя пользователя (возможно, пустое, как разрешено RFC 2396) и необязательно пароль.
type Userinfo struct {
// contains filtered or unexported fields
}
func User
func User(username string) *Userinfo
User возвращает Userinfo, содержащий предоставленное имя пользователя и без установленного пароля.
func UserPassword
func UserPassword(username, password string) *Userinfo
UserPassword возвращает Userinfo, содержащий предоставленное имя пользователя и пароль.
Эта функциональность должна использоваться только с устаревшими веб-сайтами. RFC 2396 предупреждает, что интерпретация Userinfo таким образом «НЕ РЕКОМЕНДУЕТСЯ, так как передача информации об аутентификации в открытом тексте (например, в URI) оказалась риском для безопасности почти во всех случаях, когда она использовалась».
func (*Userinfo) Password
func (u *Userinfo) Password() (string, bool)
Password возвращает пароль, если он установлен, и установлен ли он.
func (*Userinfo) String
func (u *Userinfo) String() string
String возвращает закодированную информацию userinfo в стандартном формате "username[:password]".
func (*Userinfo) Username
func (u *Userinfo) Username() string
Username возвращает имя пользователя.
type Values
Values отображает строковый ключ на список значений. Он обычно используется для параметров запроса и значений форм. В отличие от карты http.Header, ключи в карте Values чувствительны к регистру.
type Values map[string][]string
Пример
Код:
v := url.Values{}
v.Set("name", "Ava")
v.Add("friend", "Jess")
v.Add("friend", "Sarah")
v.Add("friend", "Zoe")
// v.Encode() == "name=Ava&friend=Jess&friend=Sarah&friend=Zoe"
fmt.Println(v.Get("name"))
fmt.Println(v.Get("friend"))
fmt.Println(v["friend"])
Вывод:
Ava Jess [Jess Sarah Zoe]
func ParseQuery
func ParseQuery(query string) (Values, error)
ParseQuery парсит URL-кодированную строку запроса и возвращает карту, перечисляющую значения, указанные для каждого ключа. ParseQuery всегда возвращает непустую карту, содержащую все найденные действительные параметры запроса; err описывает первую ошибку декодирования, если таковая имеется.
Запрос ожидается как список настроек key=value, разделённых амперсандом. Настройка без знака равенства интерпретируется как ключ, установленный в пустое значение. Настройки, содержащие не закодированную в URL точку с запятой, считаются недопустимыми.
Пример
Код:
m, err := url.ParseQuery(`x=1&y=2&y=3`)
if err != nil {
log.Fatal(err)
}
fmt.Println(toJSON(m))
Вывод:
{"x":["1"], "y":["2", "3"]}
func (Values) Add
func (v Values) Add(key, value string)
Add добавляет значение к ключу. Он добавляет к любым существующим значениям, связанным с ключом.
Пример
Код:
v := url.Values{}
v.Add("cat sounds", "meow")
v.Add("cat sounds", "mew")
v.Add("cat sounds", "mau")
fmt.Println(v["cat sounds"])
Вывод:
[meow mew mau]
func (Values) Del
func (v Values) Del(key string)
Del удаляет значения, связанные с ключом.
Пример
Код:
v := url.Values{}
v.Add("cat sounds", "meow")
v.Add("cat sounds", "mew")
v.Add("cat sounds", "mau")
fmt.Println(v["cat sounds"])
v.Del("cat sounds")
fmt.Println(v["cat sounds"])
Вывод:
[meow mew mau] []
func (Values) Encode
func (v Values) Encode() string
Encode кодирует значения в форму «кодированной по URL» ("bar=baz&foo=quux"), отсортированную по ключу.
Пример
Код:
v := url.Values{}
v.Add("cat sounds", "meow")
v.Add("cat sounds", "mew/")
v.Add("cat sounds", "mau$")
fmt.Println(v.Encode())
Вывод:
cat+sounds=meow&cat+sounds=mew%2F&cat+sounds=mau%24
func (Values) Get
func (v Values) Get(key string) string
Get получает первое значение, связанное с заданным ключом. Если значений, связанных с ключом, нет, Get возвращает пустую строку. Чтобы получить доступ к нескольким значениям, используйте карту напрямую.
Пример
Код:
v := url.Values{}
v.Add("cat sounds", "meow")
v.Add("cat sounds", "mew")
v.Add("cat sounds", "mau")
fmt.Printf("%q\n", v.Get("cat sounds"))
fmt.Printf("%q\n", v.Get("dog sounds"))
Вывод:
"meow" ""
func (Values) Has 1.17
func (v Values) Has(key string) bool
Has проверяет, установлен ли данный ключ.
Пример
Код:
v := url.Values{}
v.Add("cat sounds", "meow")
v.Add("cat sounds", "mew")
v.Add("cat sounds", "mau")
fmt.Println(v.Has("cat sounds"))
fmt.Println(v.Has("dog sounds"))
Вывод:
true false
func (Values) Set
func (v Values) Set(key, value string)
Метод set устанавливает значение ключа. Он заменяет любые существующие значения.
Пример
Код:
v := url.Values{}
v.Add("cat sounds", "meow")
v.Add("cat sounds", "mew")
v.Add("cat sounds", "mau")
fmt.Println(v["cat sounds"])
v.Set("cat sounds", "meow")
fmt.Println(v["cat sounds"])
Вывод:
[meow mew mau] [meow]
© Google, Inc.
Licensed under the Creative Commons Attribution License 3.0.
http://golang.org/pkg/net/url/
