package url

import "net/url"

url 包解析了 URL 并实现了查询的转码，参见 RFC 3986。

Index

• func QueryEscape(s string) string

• func QueryUnescape(s string) (string, error)

• type Error

  • func (e *Error) Error() string

• type EscapeError

  • func (e EscapeError) Error() string

• type URL

  • func Parse (rawurl string) (url *URL, err error)
  • func ParseRequestURI (rawurl string) (url *URL, err error)
  • func (u *URL) IsAbs() bool
  • func (u *URL) Query() Values
  • func (u *URL) RequestURI() string
  • func (u *URL) String() string
  • func (u URL) Parse(ref string) (URL, error)
  • func (u *URL) ResolveReference(ref *URL) *URL

• type Userinfo

  • func User(username string) *Userinfo
  • func UserPassword(username, password string) *Userinfo
  • func (u *Userinfo) Username() string
  • func (u *Userinfo) Password() (string, bool)
  • func (u *Userinfo) String() string

• type Values

  • func ParseQuery(query string) (m Values, err error)
  • func (v Values) Get(key string) string
  • func (v Values) Set(key, value string)
  • func (v Values) Add(key, value string)
  • func (v Values) Del(key string)
  • func (v Values) Encode() string

• URL

• Values

func QueryEscape

func QueryEscape(s string) string

QueryEscape 函数对 s 进行转码使之可以安全的用在 URL 查询里。

func QueryUnescape

func QueryUnescape(s string) (string, error)

QueryUnescape 函数用于将QueryEscape转码的字符串还原。它会把%AB改为字节0xAB，将'+'改为''。如果有某个%后面未跟两个十六进制的数字，本函数会返回错误。

type Error

type Error struct {
    Op  string
    URL string
    Err error
}

Error 会报告一个错误，以及该错误发生的URL和操作。

func (*Error) Error

func (e *Error) Error() string

type EscapeError

type EscapeError string

func (EscapeError) Error

func (e EscapeError) Error() string

type URL

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/"}。

func Parse

func Parse(rawurl string) (url *URL, err error)

Parse 函数解析 rawurl 为一个 URL 结构体，rawurl 可以是绝对地址，也可以是相对地址。

func ParseRequestURI

func ParseRequestURI(rawurl string) (url *URL, err error)

ParseRequestURI 函数解析 rawurl 为一个 URL 结构体，本函数会假设 rawurl 是在一个 HTTP 请求里，因此会假设该参数是一个绝对 URL 或者绝对路径，并会假设该 URL 没有 #fragment 后缀。（网页浏览器会在去掉该后缀才将网址发送到网页浏览器）。

func (*URL) IsAbs

func (u *URL) IsAbs() bool

函数在 URL 是绝对 URL 时才返回真。

func (*URL) Query

func (u *URL) Query() Values

Query 方法解析 RawQuery 字段并返回表示的 Values 类型键值对。

func (*URL) RequestURI

func (u *URL) RequestURI() string

RequestURI 方法返回编码好的 path?query 或 opaque?query 字符串，用在 HTTP 请求里。

func (*URL) String

func (u *URL) String() string

String 将 URL 重构为一个合法 URL 字符串。

func (*URL) Parse

func (u *URL) Parse(ref string) (*URL, error)

Parse 方法以 u 为上下文来解析一个 URL，ref 可以是绝对或相对 URL。

本方法解析失败会返回 nil, err; 否则返回结果和 ResolveReference 一致。

func (*URL) ResolveReference

func (u *URL) ResolveReference (ref *URL) *URL

本方法根据一个绝对 URI 将一个 URL 补全为一个 绝对URI。参数 ref 可以是绝对 URI 或者相对 URI。ResolveReference 总是返回一个新的 URL 实例，即使该实例和 u 或者 ref 完全一样。如果 ref 是绝对 URI，本方法会忽略参照 URI 并返回 ref 的一个拷贝。

type Userinfo

type Userinfo struct {
    // 内含隐藏或非导出字段
}

Userinfo 类型是一个 URL 的用户名和细节的一个不可修改的封装。一个真实存在的 Userinfo 值必须保证有用户名以及一个可选的密码。

func User

func User(username string) *Userinfo

User 函数返回一个用户名设置为 username 的不设置密码的 *Userinfo。

func UserPassword

func UserPassword(username, password string) *Userinfo

UserPassword 函数返回一个用户名设置为 username、密码设置为 password 的 *Userinfo。

func (*Userinfo) Username

func (u *Userinfo) Username() string

Username 方法返回用户名。

func (*Userinfo) Password

func (u *Userinfo) Password() (string, bool)

如果设置了密码返回密码和真，否则会返回假。

func (*Userinfo) String

func (u *Userinfo) String() string

String 方法返回编码后的用户信息，格式为 "username[:password]"。

type Values

type Value map[string][]string

Values 将建映射到值的列表。它一般用于查询的参数和表单的属性。不同于 http.Header 这个字典类型，Values 的键是大小写敏感的。

func ParseQuery

func ParseQuery(query string) (m Values, err error)

ParseQuery 函数解析一个 URL 编码的查询字符串，并返回可以表示该查询的 Values 类型的字典。本函数总是返回一个包含了所有合法查询参数的非 nil 字典，err 用来描述解码时遇到的（如果有）第一个错误。

func (Values) Get

func (v Values) Get(key string) string

Get 会获取 key 对应的值集的第一个值。如果没有对应 key 的值集会返回空字符串。获取值集请直接用 map。

func (Values) Set

func (v Values) Set(key, value string)

Set 方法将 key 对应的值集设为只有 value，它会替换掉已有的值集。

func (Values) Add

func (v Values) Add(key, value string)

Add 将 value 添加到 key 关联的值集里面原有的值后面。

func (Values) Del

func (v Values) Del (key string)

Del 删除 key 关联的值集。

func (Values) Encode

func (v Values) Encode() string

Encode 方法将 v 编码为 url 编码格式（"bar=baz&foo=quux")，编码时会以键进行排序。