Documentation
¶
Overview ¶
urlパッケージはURLを解析し、クエリエスケープを実装します。
RFC 3986を参照してください。このパッケージは基本的にRFC 3986に従いますが、互換性のために一部逸脱する場合があります。 IPv6ゾーンリテラルについてはRFC 6874に従います。
Index ¶
- func JoinPath(base string, elem ...string) (result string, err error)
- func PathEscape(s string) string
- func PathUnescape(s string) (string, error)
- func QueryEscape(s string) string
- func QueryUnescape(s string) (string, error)
- type Error
- type EscapeError
- type InvalidHostError
- type URL
- func (u *URL) EscapedFragment() string
- func (u *URL) EscapedPath() string
- func (u *URL) Hostname() string
- func (u *URL) IsAbs() bool
- func (u *URL) JoinPath(elem ...string) *URL
- func (u *URL) MarshalBinary() (text []byte, err error)
- func (u *URL) Parse(ref string) (*URL, error)
- func (u *URL) Port() string
- func (u *URL) Query() Values
- func (u *URL) Redacted() string
- func (u *URL) RequestURI() string
- func (u *URL) ResolveReference(ref *URL) *URL
- func (u *URL) String() string
- func (u *URL) UnmarshalBinary(text []byte) error
- type Userinfo
- type Values
Examples ¶
- ParseQuery
- PathEscape
- PathUnescape
- QueryEscape
- QueryUnescape
- URL
- URL (Roundtrip)
- 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
- Values
- Values.Add
- Values.Del
- Values.Encode
- Values.Get
- Values.Has
- Values.Set
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func JoinPath ¶ added in v1.19.0
JoinPathは、提供されたパス要素をbaseの既存パスに結合した URL 文字列を返します。 結果のパスから ./ や ../ 要素が除去されます。 パス要素は PathEscape によって生成されるエスケープ形式である必要があります。
func PathEscape ¶ added in v1.8.0
PathEscapeは、文字列を安全に URL パスセグメント内に配置できるようにエスケープします。 必要に応じて特殊文字(/を含む)を%XXシーケンスで置き換えます。
Example ¶
package main
import (
"github.com/shogo82148/std/fmt"
"github.com/shogo82148/std/net/url"
)
func main() {
path := url.PathEscape("my/cool+blog&about,stuff")
fmt.Println(path)
}
Output: my%2Fcool+blog&about%2Cstuff
func PathUnescape ¶ added in v1.8.0
PathUnescapeは PathEscape の逆の変換を行います。形式が"%AB"の各3バイトエンコードされた部分文字列をhexデコードされたバイト0xABに変換します。もし%の後に2桁の16進数が続かない場合、エラーが返されます。
PathUnescapeは QueryUnescape と同じですが、'+'を' '(スペース)に変換しない点が異なります。
Example ¶
package main
import (
"github.com/shogo82148/std/fmt"
"github.com/shogo82148/std/log"
"github.com/shogo82148/std/net/url"
)
func main() {
escapedPath := "my%2Fcool+blog&about%2Cstuff"
path, err := url.PathUnescape(escapedPath)
if err != nil {
log.Fatal(err)
}
fmt.Println(path)
}
Output: my/cool+blog&about,stuff
func QueryEscape ¶
QueryEscapeは、文字列をエスケープして、安全に URL クエリ内に配置できるようにします。
Example ¶
package main
import (
"github.com/shogo82148/std/fmt"
"github.com/shogo82148/std/net/url"
)
func main() {
query := url.QueryEscape("my/cool+blog&about,stuff")
fmt.Println(query)
}
Output: my%2Fcool%2Bblog%26about%2Cstuff
func QueryUnescape ¶
QueryUnescapeは QueryEscape の逆変換を行います "%AB"のような形式の3バイトエンコードされた部分文字列を 16進数でデコードされたバイト0xABに変換します もし%の後に2桁の16進数が続かない場合、エラーが返されます。
Example ¶
package main
import (
"github.com/shogo82148/std/fmt"
"github.com/shogo82148/std/log"
"github.com/shogo82148/std/net/url"
)
func main() {
escapedQuery := "my%2Fcool%2Bblog%26about%2Cstuff"
query, err := url.QueryUnescape(escapedQuery)
if err != nil {
log.Fatal(err)
}
fmt.Println(query)
}
Output: my/cool+blog&about,stuff
Types ¶
type EscapeError ¶
type EscapeError string
func (EscapeError) Error ¶
func (e EscapeError) Error() string
type InvalidHostError ¶ added in v1.6.0
type InvalidHostError string
func (InvalidHostError) Error ¶ added in v1.6.0
func (e InvalidHostError) Error() string
type URL ¶
type URL struct {
Scheme string
Opaque string
User *Userinfo
Host string
Path string
RawPath string
OmitHost bool
ForceQuery bool
RawQuery string
Fragment string
RawFragment string
}
URLは解析されたURL(厳密にはURIリファレンス)を表します。
全般的な形式は次のようになります:
[スキーム:][//[ユーザー情報@]ホスト][/パス][?クエリ][#フラグメント]
スキームの後にスラッシュで始まらないURLは次のように解釈されます:
スキーム:透明部分[?クエリ][#フラグメント]
Hostフィールドには、URLのホストとポートのサブコンポーネントが含まれます。 ポートが存在する場合、コロンでホストから分離されます。 ホストがIPv6アドレスの場合、角括弧で囲む必要があります: "[fe80::1]:80"。 net.JoinHostPort 関数は、必要に応じてホストに角括弧を追加して、ホストとポートを文字列に結合します。
Pathフィールドは、デコードされた形式で保存されます:/%47%6f%2fは/Go/になります。 結果として、Path内のどのスラッシュが生のURL内のスラッシュであり、どのスラッシュが%2fであるかを区別することはできません。 この区別はほとんど重要ではありませんが、重要な場合は、コードは URL.EscapedPath メソッドを使用する必要があります。 このメソッドは、Pathの元のエンコーディングを保持します。
RawPathフィールドは、デフォルトのパスのエンコードがエスケープされたパスと異なる場合にのみ設定されるオプションのフィールドです。 詳細については、EscapedPathメソッドを参照してください。
URLのStringメソッドは、パスを取得するためにEscapedPathメソッドを使用します。
Example ¶
package main
import (
"github.com/shogo82148/std/fmt"
"github.com/shogo82148/std/log"
"github.com/shogo82148/std/net/url"
)
func main() {
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)
}
Output: https://google.com/search?q=golang
Example (Roundtrip) ¶
package main
import (
"github.com/shogo82148/std/fmt"
"github.com/shogo82148/std/log"
"github.com/shogo82148/std/net/url"
)
func main() {
// Parse + Stringは元のエンコーディングを保持します。
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())
}
Output: /foo/bar /foo%2fbar https://example.com/foo%2fbar
func Parse ¶
Parseは生のURLを URL 構造に解析します。
URLは相対的なもの(ホストなしのパス)または絶対的なもの(スキームで始まる)である可能性があります。 スキームなしでホスト名とパスを解析しようとすることは無効ですが、解析の曖昧さにより、 エラーを返さない場合があります。
func ParseRequestURI ¶
ParseRequestURIは生のURLを URL 構造体に解析します。これは、URLがHTTPリクエストで受け取られたものであることを前提としており、urlは絶対URIまたは絶対パスとしてのみ解釈されます。 文字列urlには#fragmentの接尾辞がないことが前提とされています。 (ウェブブラウザはURLをウェブサーバーに送信する前に#fragmentを取り除きます。)
func (*URL) EscapedFragment ¶ added in v1.15.0
EscapedFragmentはu.Fragmentのエスケープ形式を返します。 一般的には、任意のフラグメントには複数のエスケープ形式が存在します。 u.Fragmentが有効なエスケープである場合、EscapedFragmentはu.RawFragmentを返します。 そうでない場合、EscapedFragmentはu.RawFragmentを無視し、独自のエスケープ形式を計算します。 URL.String メソッドは、その結果を構築するためにEscapedFragmentを使用します。 一般的には、コードはu.RawFragmentを直接読む代わりにEscapedFragmentを呼び出すべきです。
Example ¶
package main
import (
"github.com/shogo82148/std/fmt"
"github.com/shogo82148/std/log"
"github.com/shogo82148/std/net/url"
)
func main() {
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())
}
Output: Fragment: x/y/z RawFragment: x/y%2Fz EscapedFragment: x/y%2Fz
func (*URL) EscapedPath ¶ added in v1.5.0
EscapedPathはu.Pathのエスケープされた形式を返します。 一般的には、任意のパスには複数のエスケープされた形式が存在します。 EscapedPathはu.RawPathがu.Pathの有効なエスケープである場合にはu.RawPathを返します。 そうでない場合、EscapedPathはu.RawPathを無視し、独自のエスケープ形式を計算します。 URL.String メソッドと URL.RequestURI メソッドは、それぞれの結果を構築するためにEscapedPathを使用します。 一般的に、コードはu.RawPathを直接読むのではなく、EscapedPathを呼び出すべきです。
Example ¶
package main
import (
"github.com/shogo82148/std/fmt"
"github.com/shogo82148/std/log"
"github.com/shogo82148/std/net/url"
)
func main() {
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())
}
Output: Path: /x/y/z RawPath: /x/y%2Fz EscapedPath: /x/y%2Fz
func (*URL) Hostname ¶ added in v1.8.0
Hostnameは、存在する場合は有効なポート番号を削除してu.Hostを返します。
結果が角かっこで囲まれている場合、それはリテラルIPv6アドレスですので、 結果から角かっこは削除されます。
Example ¶
package main
import (
"github.com/shogo82148/std/fmt"
"github.com/shogo82148/std/log"
"github.com/shogo82148/std/net/url"
)
func main() {
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())
}
Output: example.org 2001:0db8:85a3:0000:0000:8a2e:0370:7334
func (*URL) IsAbs ¶
IsAbsは URL が絶対であるかどうかを報告します。 絶対とは、空ではないスキームを持っていることを意味します。
Example ¶
package main
import (
"github.com/shogo82148/std/fmt"
"github.com/shogo82148/std/net/url"
)
func main() {
u := url.URL{Host: "example.com", Path: "foo"}
fmt.Println(u.IsAbs())
u.Scheme = "http"
fmt.Println(u.IsAbs())
}
Output: false true
func (*URL) JoinPath ¶ added in v1.19.0
JoinPathは、提供されたパス要素を既存のパスに結合した新しい URL を返します。 結果のパスから ./ や ../ 要素が除去されます。 複数の / 文字のシーケンスは単一の / に縮小されます。 パス要素は PathEscape によって生成されるエスケープ形式である必要があります。
Example ¶
package main
import (
"github.com/shogo82148/std/fmt"
"github.com/shogo82148/std/log"
"github.com/shogo82148/std/net/url"
)
func main() {
u, err := url.Parse("https://example.com/foo/bar")
if err != nil {
log.Fatal(err)
}
fmt.Println(u.JoinPath("baz", "qux"))
}
Output: https://example.com/foo/bar/baz/qux
func (*URL) MarshalBinary ¶ added in v1.8.0
Example ¶
package main
import (
"github.com/shogo82148/std/fmt"
"github.com/shogo82148/std/log"
"github.com/shogo82148/std/net/url"
)
func main() {
u, _ := url.Parse("https://example.org")
b, err := u.MarshalBinary()
if err != nil {
log.Fatal(err)
}
fmt.Printf("%s\n", b)
}
Output: https://example.org
func (*URL) Parse ¶
Parseはレシーバのコンテキストで URL を解析します。提供されたURLは相対的または絶対的である可能性があります。Parseは解析の失敗時にはnil、errを返し、それ以外の場合は URL.ResolveReference と同じ値を返します。
Example ¶
package main
import (
"github.com/shogo82148/std/fmt"
"github.com/shogo82148/std/log"
"github.com/shogo82148/std/net/url"
)
func main() {
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)
}
}
Output: https://example.org/foo
func (*URL) Port ¶ added in v1.8.0
Portはu.Hostのポート部分を返しますが、先頭のコロンは除かれます。
もしu.Hostに有効な数値のポートが含まれていない場合、Portは空の文字列を返します。
Example ¶
package main
import (
"github.com/shogo82148/std/fmt"
"github.com/shogo82148/std/log"
"github.com/shogo82148/std/net/url"
)
func main() {
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())
}
Output: 8080
func (*URL) Query ¶
QueryはRawQueryを解析し、対応する値を返します。 不正な値の組み合わせは静かに破棄されます。 エラーをチェックするには ParseQuery を使用してください。
Example ¶
package main
import (
"github.com/shogo82148/std/fmt"
"github.com/shogo82148/std/log"
"github.com/shogo82148/std/net/url"
)
func main() {
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(""))
}
Output: [1 2] 3
func (*URL) Redacted ¶ added in v1.15.0
Redactedは URL.String と似ていますが、パスワードを「xxxxx」で置き換えます。 u.User内のパスワードのみが伏せられます。
Example ¶
package main
import (
"github.com/shogo82148/std/fmt"
"github.com/shogo82148/std/net/url"
)
func main() {
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())
}
Output: https://user:xxxxx@example.com/foo/bar https://me:xxxxx@example.com/foo/bar
func (*URL) RequestURI ¶
RequestURIは、uのHTTPリクエストで使用される、エンコードされたpath?queryまたはopaque?queryの文字列を返します。
Example ¶
package main
import (
"github.com/shogo82148/std/fmt"
"github.com/shogo82148/std/log"
"github.com/shogo82148/std/net/url"
)
func main() {
u, err := url.Parse("https://example.org/path?foo=bar")
if err != nil {
log.Fatal(err)
}
fmt.Println(u.RequestURI())
}
Output: /path?foo=bar
func (*URL) ResolveReference ¶
ResolveReferenceは、RFC 3986 Section 5.2 に従って、絶対ベースURI uからURIリファレンスを絶対URIに解決します。URIリファレンスは相対または絶対のどちらでもかまいません。ResolveReferenceは常に新しい URL インスタンスを返しますが、返されたURLがベースまたはリファレンスと同じであってもです。refが絶対URLの場合、ResolveReferenceはbaseを無視してrefのコピーを返します。
Example ¶
package main
import (
"github.com/shogo82148/std/fmt"
"github.com/shogo82148/std/log"
"github.com/shogo82148/std/net/url"
)
func main() {
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))
}
Output: http://example.com/search?q=dotnet
func (*URL) String ¶
Stringは URL を有効なURL文字列に再構築します。 結果の一般的な形式は次のいずれかです:
scheme:opaque?query#fragment scheme://userinfo@host/path?query#fragment
もしu.Opaqueが空でない場合、Stringは最初の形式を使用します。 そうでなければ、2番目の形式を使用します。 ホスト内の非ASCII文字はエスケープされます。 パスを取得するために、Stringはu.EscapedPath()を使用します。
2番目の形式では、以下のルールが適用されます:
- もしu.Schemeが空なら、scheme:は省略されます。
- もしu.Userがnilなら、userinfo@は省略されます。
- もしu.Hostが空なら、host/は省略されます。
- もしu.Schemeとu.Hostが空であり、u.Userがnilなら、 scheme://userinfo@host/全体が省略されます。
- もしu.Hostが空でなく、u.Pathが/で始まるなら、 host/pathの形式は独自の/を追加しません。
- もしu.RawQueryが空なら、?queryは省略されます。
- もしu.Fragmentが空なら、#fragmentは省略されます。
Example ¶
package main
import (
"github.com/shogo82148/std/fmt"
"github.com/shogo82148/std/net/url"
)
func main() {
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())
}
Output: https://me:pass@example.com/foo/bar?x=1&y=2#anchor https:opaque?x=1&y=2#anchor
func (*URL) UnmarshalBinary ¶ added in v1.8.0
Example ¶
package main
import (
"github.com/shogo82148/std/fmt"
"github.com/shogo82148/std/log"
"github.com/shogo82148/std/net/url"
)
func main() {
u := &url.URL{}
err := u.UnmarshalBinary([]byte("https://example.org/foo"))
if err != nil {
log.Fatal(err)
}
fmt.Printf("%s\n", u)
}
Output: https://example.org/foo
type Userinfo ¶
type Userinfo struct {
// contains filtered or unexported fields
}
Userinfo型は、URL のユーザー名とパスワードの詳細を不変なカプセル化します。既存のUserinfo値には、ユーザー名が設定されていることが保証されています(RFC 2396で許可されているように、空にすることも可能です)、また、オプションでパスワードも持つことができます。
func UserPassword ¶
UserPasswordは提供されたユーザー名とパスワードを含む Userinfo を返します。 この機能は、レガシーウェブサイトでのみ使用するべきです。 RFC 2396は、この方法でUserinfoを解釈することを「推奨されない」と警告しています。 「URIなどで平文で認証情報を渡すことは、ほとんどの場合セキュリティリスクとなっている」と述べています。
type Values ¶
Valuesは文字列のキーを値のリストにマップします。 通常、クエリパラメータやフォームの値に使用されます。 http.Headerマップとは異なり、Valuesマップのキーは大文字小文字を区別します。
Example ¶
package main
import (
"github.com/shogo82148/std/fmt"
"github.com/shogo82148/std/net/url"
)
func main() {
v := url.Values{}
v.Set("name", "Ava")
v.Add("friend", "Jess")
v.Add("friend", "Sarah")
v.Add("friend", "Zoe")
fmt.Println(v.Encode())
fmt.Println(v.Get("name"))
fmt.Println(v.Get("friend"))
fmt.Println(v["friend"])
}
Output: friend=Jess&friend=Sarah&friend=Zoe&name=Ava Ava Jess [Jess Sarah Zoe]
func ParseQuery ¶
ParseQueryはURLエンコードされたクエリ文字列を解析して、 各キーに指定された値をリストしたマップを返します。 ParseQueryは常に、最初にエンコードできないエラーが見つかった場合を示すnon-nilのマップを返します。エラーの詳細はerrに記載されます。
クエリはアンパサンドで区切られたキー=値のリストとして期待されます。 イコール記号がない設定は、空の値に設定されたキーとして解釈されます。 URLエンコードされていないセミコロンが含まれる設定は無効と見なされます。
Example ¶
m, err := url.ParseQuery(`x=1&y=2&y=3`)
if err != nil {
log.Fatal(err)
}
fmt.Println(toJSON(m))
Output: {"x":["1"], "y":["2", "3"]}
func (Values) Add ¶
Addはkeyに値を追加します。keyと関連付けられた既存の値に追加します。
Example ¶
package main
import (
"github.com/shogo82148/std/fmt"
"github.com/shogo82148/std/net/url"
)
func main() {
v := url.Values{}
v.Add("cat sounds", "meow")
v.Add("cat sounds", "mew")
v.Add("cat sounds", "mau")
fmt.Println(v["cat sounds"])
}
Output: [meow mew mau]
func (Values) Del ¶
Delはキーに関連付けられた値を削除します。
Example ¶
package main
import (
"github.com/shogo82148/std/fmt"
"github.com/shogo82148/std/net/url"
)
func main() {
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"])
}
Output: [meow mew mau] []
func (Values) Encode ¶
Encodeは値をキーでソートされた形式で「URLエンコード」します ("bar=baz&foo=quux")
Example ¶
package main
import (
"github.com/shogo82148/std/fmt"
"github.com/shogo82148/std/net/url"
)
func main() {
v := url.Values{}
v.Add("cat sounds", "meow")
v.Add("cat sounds", "mew/")
v.Add("cat sounds", "mau$")
fmt.Println(v.Encode())
}
Output: cat+sounds=meow&cat+sounds=mew%2F&cat+sounds=mau%24
func (Values) Get ¶
Getは指定したキーに関連付けられた最初の値を返します。 キーに関連付けられた値がない場合、Getは空の文字列を返します。 複数の値にアクセスするには、直接マップを使用してください。
Example ¶
package main
import (
"github.com/shogo82148/std/fmt"
"github.com/shogo82148/std/net/url"
)
func main() {
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"))
}
Output: "meow" ""
func (Values) Has ¶ added in v1.17.0
Hasは与えられたキーが設定されているかどうかを確認します。
Example ¶
package main
import (
"github.com/shogo82148/std/fmt"
"github.com/shogo82148/std/net/url"
)
func main() {
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"))
}
Output: true false
func (Values) Set ¶
Setはキーを値にセットします。既存の値を置き換えます。
Example ¶
package main
import (
"github.com/shogo82148/std/fmt"
"github.com/shogo82148/std/net/url"
)
func main() {
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"])
}
Output: [meow mew mau] [meow]