package url · Go 標準庫中文參考

# package url `import "net/url"` url包解析URL并實現了查詢的逸碼，參見[RFC 3986](http://tools.ietf.org/html/rfc3986)。 ## Index * [func QueryEscape(s string) string](#QueryEscape) * [func QueryUnescape(s string) (string, error)](#QueryUnescape) * [type Error](#Error) * [func (e \*Error) Error() string](#Error.Error) * [type EscapeError](#EscapeError) * [func (e EscapeError) Error() string](#EscapeError.Error) * [type URL](#URL) * [func Parse(rawurl string) (url \*URL, err error)](#Parse) * [func ParseRequestURI(rawurl string) (url \*URL, err error)](#ParseRequestURI) * [func (u \*URL) IsAbs() bool](#URL.IsAbs) * [func (u \*URL) Query() Values](#URL.Query) * [func (u \*URL) RequestURI() string](#URL.RequestURI) * [func (u \*URL) String() string](#URL.String) * [func (u \*URL) Parse(ref string) (\*URL, error)](#URL.Parse) * [func (u \*URL) ResolveReference(ref \*URL) \*URL](#URL.ResolveReference) * [type Userinfo](#Userinfo) * [func User(username string) \*Userinfo](#User) * [func UserPassword(username, password string) \*Userinfo](#UserPassword) * [func (u \*Userinfo) Username() string](#Userinfo.Username) * [func (u \*Userinfo) Password() (string, bool)](#Userinfo.Password) * [func (u \*Userinfo) String() string](#Userinfo.String) * [type Values](#Values) * [func ParseQuery(query string) (m Values, err error)](#ParseQuery) * [func (v Values) Get(key string) string](#Values.Get) * [func (v Values) Set(key, value string)](#Values.Set) * [func (v Values) Add(key, value string)](#Values.Add) * [func (v Values) Del(key string)](#Values.Del) * [func (v Values) Encode() string](#Values.Encode) ### Examples * [URL](#example-URL) * [Values](#example-Values) ## func [QueryEscape](https://github.com/golang/go/blob/master/src/net/url/url.go#L173 "View Source") ``` func QueryEscape(s string) string ``` QueryEscape函數對s進行轉碼使之可以安全的用在URL查詢里。 ## func [QueryUnescape](https://github.com/golang/go/blob/master/src/net/url/url.go#L112 "View Source") ``` func QueryUnescape(s string) (string, error) ``` QueryUnescape函數用于將QueryEscape轉碼的字符串還原。它會把%AB改為字節0xAB，將'+'改為' '。如果有某個%后面未跟兩個十六進制數字，本函數會返回錯誤。 ## type [Error](https://github.com/golang/go/blob/master/src/net/url/url.go#L18 "View Source") ``` type Error struct { Op string URL string Err error } ``` Error會報告一個錯誤，以及導致該錯誤發生的URL和操作。 ### func (\*Error) [Error](https://github.com/golang/go/blob/master/src/net/url/url.go#L24 "View Source") ``` func (e *Error) Error() string ``` ## type [EscapeError](https://github.com/golang/go/blob/master/src/net/url/url.go#L59 "View Source") ``` type EscapeError string ``` ### func (EscapeError) [Error](https://github.com/golang/go/blob/master/src/net/url/url.go#L61 "View Source") ``` func (e EscapeError) Error() string ``` ## type [URL](https://github.com/golang/go/blob/master/src/net/url/url.go#L230 "View Source") ``` type URL struct { Scheme string Opaque string // 編碼后的不透明數據 User *Userinfo // 用戶名和密碼信息 Host string // host或host:port Path string RawQuery string // 編碼后的查詢字符串，沒有'?' Fragment string // 引用的片段（文檔位置），沒有'#' } ``` URL類型代表一個解析后的URL（或者說，一個URL參照）。URL基本格式如下： ``` scheme://[userinfo@]host/path[?query][#fragment] ``` scheme后不是冒號加雙斜線的URL被解釋為如下格式： ``` scheme:opaque[?query][#fragment] ``` 注意路徑字段是以解碼后的格式保存的，如/%47%6f%2f會變成/Go/。這導致我們無法確定Path字段中的斜線是來自原始URL還是解碼前的%2f。除非一個客戶端必須使用其他程序/函數來解析原始URL或者重構原始URL，這個區別并不重要。此時，HTTP服務端可以查詢req.RequestURI，而HTTP客戶端可以使用URL{Host: "example.com", Opaque: "//example.com/Go%2f"}代替{Host: "example.com", Path: "/Go/"}。 Example ``` 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 ``` ### func [Parse](https://github.com/golang/go/blob/master/src/net/url/url.go#L333 "View Source") ``` func Parse(rawurl string) (url *URL, err error) ``` Parse函數解析rawurl為一個URL結構體，rawurl可以是絕對地址，也可以是相對地址。 ### func [ParseRequestURI](https://github.com/golang/go/blob/master/src/net/url/url.go#L353 "View Source") ``` func ParseRequestURI(rawurl string) (url *URL, err error) ``` ParseRequestURI函數解析rawurl為一個URL結構體，本函數會假設rawurl是在一個HTTP請求里，因此會假設該參數是一個絕對URL或者絕對路徑，并會假設該URL沒有#fragment后綴。（網頁瀏覽器會在去掉該后綴后才將網址發送到網頁服務器） ### func (\*URL) [IsAbs](https://github.com/golang/go/blob/master/src/net/url/url.go#L624 "View Source") ``` func (u *URL) IsAbs() bool ``` 函數在URL是絕對URL時才返回真。 ### func (\*URL) [Query](https://github.com/golang/go/blob/master/src/net/url/url.go#L677 "View Source") ``` func (u *URL) Query() Values ``` Query方法解析RawQuery字段并返回其表示的Values類型鍵值對。 ### func (\*URL) [RequestURI](https://github.com/golang/go/blob/master/src/net/url/url.go#L684 "View Source") ``` func (u *URL) RequestURI() string ``` RequestURI方法返回編碼好的path?query或opaque?query字符串，用在HTTP請求里。 ### func (\*URL) [String](https://github.com/golang/go/blob/master/src/net/url/url.go#L443 "View Source") ``` func (u *URL) String() string ``` String將URL重構為一個合法URL字符串。 ### func (\*URL) [Parse](https://github.com/golang/go/blob/master/src/net/url/url.go#L631 "View Source") ``` func (u *URL) Parse(ref string) (*URL, error) ``` Parse方法以u為上下文來解析一個URL，ref可以是絕對或相對URL。本方法解析失敗會返回nil, err；否則返回結果和ResolveReference一致。 ### func (\*URL) [ResolveReference](https://github.com/golang/go/blob/master/src/net/url/url.go#L645 "View Source") ``` func (u *URL) ResolveReference(ref *URL) *URL ``` 本方法根據一個絕對URI將一個URI補全為一個絕對URI，參見[RFC 3986](http://tools.ietf.org/html/rfc3986)?節?5.2。參數ref可以是絕對URI或者相對URI。ResolveReference總是返回一個新的URL實例，即使該實例和u或者ref完全一樣。如果ref是絕對URI，本方法會忽略參照URI并返回ref的一個拷貝。 ## type [Userinfo](https://github.com/golang/go/blob/master/src/net/url/url.go#L261 "View Source") ``` type Userinfo struct { // 內含隱藏或非導出字段 } ``` Userinfo類型是一個URL的用戶名和密碼細節的一個不可修改的封裝。一個真實存在的Userinfo值必須保證有用戶名（但根據?[RFC 2396](http://tools.ietf.org/html/rfc2396)可以是空字符串）以及一個可選的密碼。 ### func [User](https://github.com/golang/go/blob/master/src/net/url/url.go#L242 "View Source") ``` func User(username string) *Userinfo ``` User函數返回一個用戶名設置為username的不設置密碼的\*Userinfo。 ### func [UserPassword](https://github.com/golang/go/blob/master/src/net/url/url.go#L253 "View Source") ``` func UserPassword(username, password string) *Userinfo ``` UserPassword函數返回一個用戶名設置為username、密碼設置為password的\*Userinfo。這個函數應該只用于老式的站點，因為風險很大，不建議使用，參見[RFC 2396](http://tools.ietf.org/html/rfc2396)。 ### func (\*Userinfo) [Username](https://github.com/golang/go/blob/master/src/net/url/url.go#L268 "View Source") ``` func (u *Userinfo) Username() string ``` Username方法返回用戶名。 ### func (\*Userinfo) [Password](https://github.com/golang/go/blob/master/src/net/url/url.go#L273 "View Source") ``` func (u *Userinfo) Password() (string, bool) ``` 如果設置了密碼返回密碼和真，否則會返回假。 ### func (\*Userinfo) [String](https://github.com/golang/go/blob/master/src/net/url/url.go#L282 "View Source") ``` func (u *Userinfo) String() string ``` String方法返回編碼后的用戶信息，格式為"username[:password]"。 ## type [Values](https://github.com/golang/go/blob/master/src/net/url/url.go#L482 "View Source") ``` type Values map[string][]string ``` Values將建映射到值的列表。它一般用于查詢的參數和表單的屬性。不同于http.Header這個字典類型，Values的鍵是大小寫敏感的。 Example ``` 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"]) ``` Output: ``` Ava Jess [Jess Sarah Zoe] ``` ### func [ParseQuery](https://github.com/golang/go/blob/master/src/net/url/url.go#L521 "View Source") ``` func ParseQuery(query string) (m Values, err error) ``` ParseQuery函數解析一個URL編碼的查詢字符串，并返回可以表示該查詢的Values類型的字典。本函數總是返回一個包含了所有合法查詢參數的非nil字典，err用來描述解碼時遇到的（如果有）第一個錯誤。 ### func (Values) [Get](https://github.com/golang/go/blob/master/src/net/url/url.go#L488 "View Source") ``` func (v Values) Get(key string) string ``` Get會獲取key對應的值集的第一個值。如果沒有對應key的值集會返回空字符串。獲取值集請直接用map。 ### func (Values) [Set](https://github.com/golang/go/blob/master/src/net/url/url.go#L501 "View Source") ``` func (v Values) Set(key, value string) ``` Set方法將key對應的值集設為只有value，它會替換掉已有的值集。 ### func (Values) [Add](https://github.com/golang/go/blob/master/src/net/url/url.go#L507 "View Source") ``` func (v Values) Add(key, value string) ``` Add將value添加到key關聯的值集里原有的值的后面。 ### func (Values) [Del](https://github.com/golang/go/blob/master/src/net/url/url.go#L512 "View Source") ``` func (v Values) Del(key string) ``` Del刪除key關聯的值集。 ### func (Values) [Encode](https://github.com/golang/go/blob/master/src/net/url/url.go#L563 "View Source") ``` func (v Values) Encode() string ``` Encode方法將v編碼為url編碼格式("bar=baz&foo=quux")，編碼時會以鍵進行排序。