@colin4k1024/tsp 2.4.0

package/skills/goframe-v2/references/WEB/346/234/215/345/212/241/345/274/200/345/217/221/Cookie.md

@@ -0,0 +1,82 @@
+## 基本介绍
+
+接口文档： [https://pkg.go.dev/github.com/gogf/gf/v2/net/ghttp#Cookie](https://pkg.go.dev/github.com/gogf/gf/v2/net/ghttp#Cookie)
+
+常用方法：
+
+```go
+type Cookie
+    func GetCookie(r *Request) *Cookie
+    func (c *Cookie) Contains(key string) bool
+    func (c *Cookie) Flush()
+    func (c *Cookie) Get(key string, def ...string) string
+    func (c *Cookie) GetSessionId() string
+    func (c *Cookie) Map() map[string]string
+    func (c *Cookie) Remove(key string)
+    func (c *Cookie) RemoveCookie(key, domain, path string)
+    func (c *Cookie) Set(key, value string)
+    func (c *Cookie) SetCookie(key, value, domain, path string, maxAge time.Duration, httpOnly ...bool)
+    func (c *Cookie) SetHttpCookie(httpCookie *http.Cookie)
+    func (c *Cookie) SetSessionId(id string)
+```
+
+任何时候都可以通过 `*ghttp.Request` 对象获取到当前请求对应的 `Cookie` 对象，因为 `Cookie` 和 `Session` 都是和请求会话相关，因此都属于 `ghttp.Request` 的成员对象，并对外公开。 `Cookie` 对象不需要手动 `Close`，请求流程结束后， `HTTP Server` 会自动关闭掉。
+
+此外， `Cookie` 中封装了两个 `SessionId` 相关的方法：
+
+1. `Cookie.GetSessionId()` 用于获取当前请求提交的 `SessionId`，每个请求的 `SessionId` 都是唯一的，并且伴随整个请求流程，该值可能为空。
+2. `Cookie.SetSessionId(id string)` 用于自定义设置 `SessionId` 到 `Cookie` 中，返回给客户端（往往是浏览器）存储，随后客户端每一次请求在 `Cookie` 中可带上该 `SessionId`。
+
+在设置 `Cookie` 变量的时候可以给定过期时间，该时间为可选参数，默认的 `Cookie` 过期时间为一年。
+:::tip
+默认的 `SessionId` 在 `Cookie` 中的存储名称为 `gfsession`。
+:::
+## 使用示例
+
+```go
+package main
+
+import (
+    "github.com/gogf/gf/v2/frame/g"
+    "github.com/gogf/gf/v2/os/gtime"
+    "github.com/gogf/gf/v2/net/ghttp"
+)
+
+func main() {
+    s := g.Server()
+    s.BindHandler("/cookie", func(r *ghttp.Request) {
+        datetime := r.Cookie.Get("datetime")
+        r.Cookie.Set("datetime", gtime.Datetime())
+        r.Response.Write("datetime:", datetime)
+    })
+    s.SetPort(8199)
+    s.Run()
+}
+```
+
+执行外层的 `main.go`，可以尝试刷新页面 [http://127.0.0.1:8199/cookie](http://127.0.0.1:8199/cookie) ，显示的时间在一直变化。
+
+对于控制器对象而言，从基类控制器中继承了很多会话相关的对象指针，可以看做alias，可以直接使用，他们都是指向的同一个对象：
+
+```go
+type Controller struct {
+    Request  *ghttp.Request  // 请求数据对象
+    Response *ghttp.Response // 返回数据对象(r.Response)
+    Server   *ghttp.Server   // WebServer对象(r.Server)
+    Cookie   *ghttp.Cookie   // COOKIE操作对象(r.Cookie)
+    Session  *ghttp.Session  // SESSION操作对象
+    View     *View           // 视图对象
+}
+```
+
+由于对于Web开发者来讲， `Cookie` 都已经是非常熟悉的组件了，相关 `API` 也非常简单，这里便不再赘述。
+
+## `Cookie` 会话过期
+
+`Cookie` 的有效期默认是1年，如果我们期望Cookie随着用户的浏览会话过期，像这样：
+
+那么我们仅需要通过 `SetCookie` 来设置 `Cookie` 键值对并将 `maxAge` 参数设置为 `0` 即可。像这样：
+
+```
+r.Cookie.SetCookie("MyCookieKey", "MyCookieValue", "", "/", 0)
+```

package/skills/goframe-v2/references/WEB/346/234/215/345/212/241/345/274/200/345/217/221/HTTPClient/HTTPClient-/344/273/243/347/220/206Proxy/350/256/276/347/275/256.md

@@ -0,0 +1,40 @@
+## 代理 `Proxy` 设置
+
+HTTP客户端发起请求时可以设置代理服务器地址 `proxyURL`，该该特性使用 `SetProxy*` 相关方法实现。代理主要支持 `http` 和 `socks5` 两种形式，分别为 `http://USER:PASSWORD@IP:PORT` 或 `socks5://USER:PASSWORD@IP:PORT` 形式。
+
+方法列表：
+
+```go
+func (c *Client) SetProxy(proxyURL string)
+func (c *Client) Proxy(proxyURL string) *Client
+```
+
+我们来看下客户端设置 `proxyURL` 的示例。
+
+## 普通调用示例
+
+使用 `SetProxy` 配置方法。
+
+```go
+client := g.Client()
+client.SetProxy("http://127.0.0.1:1081")
+client.SetTimeout(5 * time.Second)
+response, err := client.Get(gctx.New(), "https://api.ip.sb/ip")
+if err != nil {
+    fmt.Println(err)
+}
+response.RawDump()
+```
+
+## 链式调用示例
+
+使用 `Proxy` 链式方法。
+
+```go
+client := g.Client()
+response, err := client.Proxy("http://127.0.0.1:1081").Get(gctx.New(), "https://api.ip.sb/ip")
+if err != nil {
+    fmt.Println(err)
+}
+fmt.Println(response.RawResponse())
+```

package/skills/goframe-v2/references/WEB/346/234/215/345/212/241/345/274/200/345/217/221/HTTPClient/HTTPClient-/345/237/272/346/234/254/344/275/277/347/224/250.md

@@ -0,0 +1,149 @@
+## 基本使用
+
+最基本的 `HTTP` 客户端使用是通过 `HTTP Method` 同名的几个操作方法来发送请求， **但需要注意的是返回的结果对象需要执行 `Close` 防止内存溢出**。我们来看几个 `HTTP` 客户端请求的简单示例。
+
+### 发送 `GET` 请求，打印出返回值
+
+```go
+r, err := g.Client().Get(ctx, "https://goframe.org")
+if err != nil {
+    panic(err)
+}
+defer r.Close()
+fmt.Println(r.ReadAllString())
+```
+
+### 发送 `GET` 请求，下载远程文件
+
+```go
+r, err := g.Client().Get(ctx, "https://goframe.org/cover.png")
+if err != nil {
+    panic(err)
+}
+defer r.Close()
+gfile.PutBytes("/Users/john/Temp/cover.png", r.ReadAll())
+```
+
+下载文件操作，小文件下载非常简单。需要注意的是，如果远程文件比较大时，服务端会分批返回数据，因此会需要客户端发多个 `GET` 请求，每一次通过 `Header` 来请求分批的文件范围长度，感兴趣的同学可自行研究相关细节。
+
+### 发送 `POST` 请求，打印出返回值
+
+```go
+r, err := g.Client().Post(ctx, "http://127.0.0.1:8199/form", "name=john&age=18")
+if err != nil {
+    panic(err)
+}
+defer r.Close()
+fmt.Println(r.ReadAllString())
+```
+
+传递多参数的时候用户可以使用 `&` 符号进行连接，注意参数值往往需要通过 `gurl.Encode` 编码一下。
+
+### 发送 `POST` 请求，参数为 `map` 类型，打印出返回值
+
+```go
+r, err := g.Client().Post(
+    ctx,
+    "http://127.0.0.1:8199/form",
+    g.Map{
+        "submit"   : "1",
+        "callback" : "http://127.0.0.1/callback?url=http://baidu.com",
+    },
+)
+if err != nil {
+    panic(err)
+}
+defer r.Close()
+fmt.Println(r.ReadAllString())
+```
+
+传递多参数的时候用户可以使用 `&` 符号进行连接，也可以直接使用 `map`（ **其实之前也提到，任意数据类型都支持，包括 `struct`**）。
+
+### 发送 `POST` 请求，参数为 `JSON` 数据，打印出返回值
+
+```go
+r, err := g.Client().Post(
+    ctx,
+    "http://user.svc/v1/user/create",
+    `{"passport":"john","password":"123456","password-confirm":"123456"}`,
+)
+if err != nil {
+    panic(err)
+}
+defer r.Close()
+fmt.Println(r.ReadAllString())
+```
+
+可以看到，通过 `ghttp` 客户端发送 `JSON` 数据请求非常方便，直接通过 `Post` 方法提交即可。当没有显式设置 `ContentType` 时，客户端会自动识别参数类型并将请求的 `Content-Type` 设置为 `application/json`。
+
+### 发送 `DELETE` 请求，打印出返回值
+
+```go
+r, err := g.Client().Delete(ctx, "http://user.svc/v1/user/delete/1", "10000")
+if err != nil {
+    panic(err)
+}
+defer r.Close()
+fmt.Println(r.ReadAllString())
+```
+
+## `*Bytes` 及 `*Content` 方法
+
+以 `Bytes` 及 `Content` 后缀结尾的请求方法为直接获取返回内容的 **快捷方法**，这些方法将会自动读取服务端返回内容 **并自动关闭请求连接**。 `*Bytes` 方法用于获取 `[]byte` 类型结果， `*Content` 方法用于获取 `string` 类型结果。 **需要注意的是，如果请求执行失败，返回内容将会为空。**
+
+### 发送 `GET` 请求，打印出返回值
+
+```go
+// 返回content为[]bytes类型
+content := g.Client().GetBytes(ctx, "https://goframe.org")
+```
+
+```go
+// 返回content为string类型
+content := g.Client().GetContent(ctx, "https://goframe.org")
+```
+
+### 发送 `POST` 请求，打印出返回值
+
+```go
+// 返回content为[]bytes类型
+content := g.Client().PostBytes(
+    ctx,
+    "http://user.svc/v1/user/create",
+    `{"passport":"john","password":"123456","password-confirm":"123456"}`,
+)
+```
+
+```go
+// 返回content为string类型
+content := g.Client().PostContent(
+    ctx,
+    "http://user.svc/v1/user/create",
+    `{"passport":"john","password":"123456","password-confirm":"123456"}`,
+)
+```
+
+## `*Var` 方法
+
+以 `Var` 后缀结尾的请求方法直接请求并获取 `HTTP` 接口结果为 `g.Var` 泛型类型 **便于下一步执行类型转换，特别是将请求结果转换到结构体对象上**。往往用于服务端返回格式为 `JSON/XML` 的情况，通过返回的 `g.Var` 泛型对象可根据需要自动解析。此外，如果请求失败或者请求结果为空，会返回一个空的 `g.Var` 泛型对象，不影响转换方法调用。
+
+使用示例：
+
+```go
+type User struct {
+    Id   int
+    Name string
+}
+```
+
+```go
+// Struct
+var user *User
+g.Client().GetVar(ctx, url).Scan(&user)
+```
+
+```go
+// Struct数组
+var users []*User
+g.Client().GetVar(ctx, url).Scan(&users)
+```

package/skills/goframe-v2/references/WEB/346/234/215/345/212/241/345/274/200/345/217/221/HTTPClient/HTTPClient-/345/270/270/350/247/201/351/227/256/351/242/230.md

@@ -0,0 +1,37 @@
+## 是否需要保存复用创建的 `gclient.Client` 对象
+
+无论是通过 `g.Client` 或者 `gclient.New` 方法创建 `gclient.Client` 对象，该对象都应该保存下来复用，而不是每一次都新建 `Client` 对象，这样可以提高效率、降低资源使用、使用方式对 `GC` 友好。该对象内建连接池设计，可充分管理大量的短连接请求。由于 `Client` 对象对资源消耗不是很高，所以很多同学可能都没太注意这个点。
+
+什么情况下我应该新建 `gclient.Client` 对象而不是复用呢？你可以按照业务模块的解耦设计，每个业务模块单独管理维护自己的 `gclient.Client` 对象。也可以当针对不同的场景，使用 `Client` 的配置不同时，那么可以新建不同的 `Client` 来使用。
+
+## `invalid semicolon separator in query`
+
+**问题原因**：默认 **表单请求** 中带 `;` 字符是非法的（需要 `urlencode`）。具体请参考讨论： [https://github.com/golang/go/issues/25192](https://github.com/golang/go/issues/25192)
+
+**错误示例**：
+
+```bash
+curl localhost:8000/Execute -d '{
+    "Component": "mysql",
+    "ResourceId": "cdb-gy6hm0ee",
+    "Port": 6379,
+    "SQL": "show databases;",
+    "UserName": "root",
+    "Password": ""
+}'
+```
+
+**修复示例**：
+
+提交请求的时候需要注明 `ContentType`，例如这里应当标明是 `JSON` 请求。
+
+```bash
+curl -X POST -H "Content-Type: application/json" localhost:8000/Execute -d '{
+    "Component": "mysql",
+    "ResourceId": "cdb-gy6hm0ee",
+    "Port": 6379,
+    "SQL": "show databases;",
+    "UserName": "root",
+    "Password": ""
+}'
+```

package/skills/goframe-v2/references/WEB/346/234/215/345/212/241/345/274/200/345/217/221/HTTPClient/HTTPClient-/346/213/246/346/210/252/345/231/250/344/270/255/351/227/264/344/273/266.md

@@ -0,0 +1,171 @@
+## 基本介绍
+
+`HTTPClient` 支持强大的拦截器/中间件特性，该特性使得对于客户端的全局请求拦截及注入成为了可能，例如修改/注入提交参数、修改/注入返回参数、基于客户端的参数校验等等。中间件的注入通过以下方法实现：
+
+```go
+func (c *Client) Use(handlers ...HandlerFunc) *Client
+```
+
+在中间件中通过 `Next` 方法执行下一步流程， `Next` 方法定义如下：
+
+```go
+func (c *Client) Next(req *http.Request) (*Response, error)
+```
+
+## 中间件类型
+
+`HTTPClient` 中间件功能同 `HTTPServer` 的中间件功能类似，同样也是分为了前置中间件和后置中间件两种。
+
+### 前置中间件
+
+处理逻辑位于 `Next` 方法之前，格式形如：
+
+```go
+c := g.Client()
+c.Use(func(c *gclient.Client, r *http.Request) (resp *gclient.Response, err error) {
+    // 自定义处理逻辑
+    resp, err = c.Next(r)
+    return resp, err
+})
+```
+
+### 后置中间件
+
+处理逻辑位于 `Next` 方法之后，格式形如：
+
+```go
+c := g.Client()
+c.Use(func(c *gclient.Client, r *http.Request) (resp *gclient.Response, err error) {
+    resp, err = c.Next(r)
+    // 自定义处理逻辑
+    return resp, err
+})
+```
+
+## 使用示例
+
+我们来一个代码示例更好介绍使用，该示例通过给客户端增加拦截器，对提交的JSON数据注入自定义的额外参数，这些额外参数实现对提交参数的签名生成体积签名相关参数提交，也就是实现一版简单的接口参数安全校验。
+
+### 服务端
+
+服务端的逻辑很简单，就是把客户端提交的 `JSON` 参数按照 `map` 解析后再构造成 `JSON` 字符串返回给客户端。
+:::note
+往往服务端也需要通过中间件进行签名校验，我这里偷了一个懒，直接返回了客户端提交的数据。体谅一下文档维护作者😸。
+:::
+```go
+package main
+
+import (
+    "github.com/gogf/gf/v2/frame/g"
+    "github.com/gogf/gf/v2/net/ghttp"
+)
+
+func main() {
+    s := g.Server()
+    s.Group("/", func(group *ghttp.RouterGroup) {
+        group.ALL("/", func(r *ghttp.Request) {
+            r.Response.Write(r.GetMap())
+        })
+    })
+    s.SetPort(8199)
+    s.Run()
+}
+```
+
+### 客户端
+
+客户端的逻辑是实现基本的客户端参数提交、拦截器注入、签名相关参数注入以及签名参数生成。
+
+```go
+package main
+
+import (
+    "bytes"
+    "fmt"
+    "io/ioutil"
+    "net/http"
+
+    "github.com/gogf/gf/v2/container/garray"
+    "github.com/gogf/gf/v2/crypto/gmd5"
+    "github.com/gogf/gf/v2/frame/g"
+    "github.com/gogf/gf/v2/internal/json"
+    "github.com/gogf/gf/v2/net/gclient"
+    "github.com/gogf/gf/v2/os/gctx"
+    "github.com/gogf/gf/v2/os/gtime"
+    "github.com/gogf/gf/v2/util/gconv"
+    "github.com/gogf/gf/v2/util/guid"
+    "github.com/gogf/gf/v2/util/gutil"
+)
+
+const (
+    appId     = "123"
+    appSecret = "456"
+)
+
+// 注入统一的接口签名参数
+func injectSignature(jsonContent []byte) []byte {
+    var m map[string]interface{}
+    _ = json.Unmarshal(jsonContent, &m)
+    if len(m) > 0 {
+        m["appid"] = appId
+        m["nonce"] = guid.S()
+        m["timestamp"] = gtime.Timestamp()
+        var (
+            keyArray   = garray.NewSortedStrArrayFrom(gutil.Keys(m))
+            sigContent string
+        )
+        keyArray.Iterator(func(k int, v string) bool {
+            sigContent += v
+            sigContent += gconv.String(m[v])
+            return true
+        })
+        m["signature"] = gmd5.MustEncryptString(gmd5.MustEncryptString(sigContent) + appSecret)
+        jsonContent, _ = json.Marshal(m)
+    }
+    return jsonContent
+}
+
+func main() {
+    c := g.Client()
+    c.Use(func(c *gclient.Client, r *http.Request) (resp *gclient.Response, err error) {
+        bodyBytes, _ := ioutil.ReadAll(r.Body)
+        if len(bodyBytes) > 0 {
+            // 注入签名相关参数，修改Request原有的提交参数
+            bodyBytes = injectSignature(bodyBytes)
+            r.Body = ioutil.NopCloser(bytes.NewBuffer(bodyBytes))
+            r.ContentLength = int64(len(bodyBytes))
+        }
+        return c.Next(r)
+    })
+    content := c.ContentJson().PostContent(gctx.New(), "http://127.0.0.1:8199/", g.Map{
+        "name": "goframe",
+        "site": "https://goframe.org",
+    })
+    fmt.Println(content)
+}
+```
+
+### 运行测试
+
+先运行服务端：
+
+```bash
+$ go run server.go
+
+  SERVER  | DOMAIN  | ADDRESS | METHOD | ROUTE |      HANDLER      | MIDDLEWARE
+----------|---------|---------|--------|-------|-------------------|-------------
+  default | default | :8199   | ALL    | /     | main.main.func1.1 |
+----------|---------|---------|--------|-------|-------------------|-------------
+
+2021-05-18 09:23:41.865 97906: http server started listening on [:8199]
+```
+
+再运行客户端：
+
+```bash
+$ go run client.go
+{"appid":"123","name":"goframe","nonce":"12vd8tx23l6cbfz9k59xehk1002pixfo","signature":"578a90b67bdc63d551d6a18635307ba2","site":"https://goframe.org","timestamp":1621301076}
+$
+```
+
+可以看到，服务端接受到的参数多了多了几项，包括 `appid/nonce/timestamp/signature`，这些参数往往都是签名校验算法所需要的参数。

package/skills/goframe-v2/references/WEB/346/234/215/345/212/241/345/274/200/345/217/221/HTTPClient/HTTPClient-/346/226/207/344/273/266/344/270/212/344/274/240.md

@@ -0,0 +1,187 @@
+`GoFrame` 支持非常方便的表单文件上传功能，并且HTTP客户端对上传功能进行了必要的封装并极大简化了上传功能调用。
+:::warning
+注意哦：上传文件大小受到 `ghttp.Server` 的 `ClientMaxBodySize` 配置影响： [https://pkg.go.dev/github.com/gogf/gf/v2/net/ghttp#ServerConfig](https://pkg.go.dev/github.com/gogf/gf/v2/net/ghttp#ServerConfig) 默认支持的上传文件大小为 `8MB`。
+:::
+## 服务端
+
+在服务端通过 `Request` 对象获取上传文件：
+
+```go
+package main
+
+import (
+    "github.com/gogf/gf/v2/frame/g"
+    "github.com/gogf/gf/v2/net/ghttp"
+)
+
+// Upload uploads files to /tmp .
+func Upload(r *ghttp.Request) {
+    files := r.GetUploadFiles("upload-file")
+    names, err := files.Save("/tmp/")
+    if err != nil {
+        r.Response.WriteExit(err)
+    }
+    r.Response.WriteExit("upload successfully: ", names)
+}
+
+// UploadShow shows uploading simgle file page.
+func UploadShow(r *ghttp.Request) {
+    r.Response.Write(`
+    <html>
+    <head>
+        <title>GoFrame Upload File Demo</title>
+    </head>
+        <body>
+            <form enctype="multipart/form-data" action="/upload" method="post">
+                <input type="file" name="upload-file" />
+                <input type="submit" value="upload" />
+            </form>
+        </body>
+    </html>
+    `)
+}
+
+// UploadShowBatch shows uploading multiple files page.
+func UploadShowBatch(r *ghttp.Request) {
+    r.Response.Write(`
+    <html>
+    <head>
+        <title>GoFrame Upload Files Demo</title>
+    </head>
+        <body>
+            <form enctype="multipart/form-data" action="/upload" method="post">
+                <input type="file" name="upload-file" />
+                <input type="file" name="upload-file" />
+                <input type="submit" value="upload" />
+            </form>
+        </body>
+    </html>
+    `)
+}
+
+func main() {
+    s := g.Server()
+    s.Group("/upload", func(group *ghttp.RouterGroup) {
+        group.POST("/", Upload)
+        group.ALL("/show", UploadShow)
+        group.ALL("/batch", UploadShowBatch)
+    })
+    s.SetPort(8199)
+    s.Run()
+}
+```
+
+该服务端提供了3个接口：
+
+1. [http://127.0.0.1:8199/upload/show](http://127.0.0.1:8199/upload/show) 地址用于展示单个文件上传的H5页面；
+2. [http://127.0.0.1:8199/upload/batch](http://127.0.0.1:8199/upload/batch) 地址用于展示多个文件上传的H5页面；
+3. [http://127.0.0.1:8199/upload](http://127.0.0.1:8199/upload) 接口用于真实的表单文件上传，该接口同时支持单个文件或者多个文件上传；
+
+我们这里访问 [http://127.0.0.1:8199/upload/show](http://127.0.0.1:8199/upload/show) 选择需要上传的单个文件，提交之后可以看到文件上传成功到服务器上。
+
+**关键代码说明**
+
+1. 我们在服务端可以通过 `r.GetUploadFiles` 方法获得上传的所有文件对象，也可以通过 `r.GetUploadFile` 获取单个上传的文件对象。
+2. 在 `r.GetUploadFiles("upload-file")` 中的参数 `"upload-file"` 为本示例中客户端上传时的表单文件域名称，开发者可以根据前后端约定在客户端中定义，以方便服务端接收表单文件域参数。
+3. 通过 `files.Save` 可以将上传的多个文件方便地保存到指定的目录下，并返回保存成功的文件名。如果是批量保存，只要任意一个文件保存失败，都将会立即返回错误。此外， `Save` 方法的第二个参数支持随机自动命名上传文件。
+4. 通过 `group.POST("/", Upload)` 注册的路由仅支持 `POST` 方式访问。
+
+## 客户端
+
+### 单文件上传
+
+```go
+package main
+
+import (
+    "fmt"
+
+    "github.com/gogf/gf/v2/frame/g"
+    "github.com/gogf/gf/v2/os/gctx"
+    "github.com/gogf/gf/v2/os/glog"
+)
+
+func main() {
+    var (
+        ctx  = gctx.New()
+        path = "/home/john/Workspace/Go/github.com/gogf/gf/v2/version.go"
+    )
+    result, err := g.Client().Post(ctx, "http://127.0.0.1:8199/upload", "upload-file=@file:"+path)
+    if err != nil {
+        glog.Fatalf(ctx, `%+v`, err)
+    }
+    defer result.Close()
+    fmt.Println(result.ReadAllString())
+}
+```
+
+注意到了吗？文件上传参数格式使用了 `参数名=@file:文件路径` ，HTTP客户端将会自动解析 **文件路径** 对应的文件内容并读取提交给服务端。原本复杂的文件上传操作被 `gf` 进行了封装处理，用户只需要使用 `@file:+文件路径` 来构成参数值即可。其中， `文件路径` 请使用本地文件绝对路径。
+
+首先运行服务端程序之后，我们再运行这个上传客户端（注意修改上传的文件路径为本地真实文件路径），执行后可以看到文件被成功上传到服务器的指定路径下。
+
+### 多文件上传
+
+```go
+package main
+
+import (
+    "fmt"
+
+    "github.com/gogf/gf/v2/frame/g"
+    "github.com/gogf/gf/v2/os/gctx"
+    "github.com/gogf/gf/v2/os/glog"
+)
+
+func main() {
+    var (
+        ctx   = gctx.New()
+        path1 = "/Users/john/Pictures/logo1.png"
+        path2 = "/Users/john/Pictures/logo2.png"
+    )
+    result, err := g.Client().Post(
+        ctx,
+        "http://127.0.0.1:8199/upload",
+        fmt.Sprintf(`upload-file=@file:%s&upload-file=@file:%s`, path1, path2),
+    )
+    if err != nil {
+        glog.Fatalf(ctx, `%+v`, err)
+    }
+    defer result.Close()
+    fmt.Println(result.ReadAllString())
+}
+```
+
+可以看到，多个文件上传提交参数格式为 `参数名=@file:xxx&参数名=@file:xxx...`，也可以使用 `参数名[]=@file:xxx&参数名[]=@file:xxx...` 的形式。
+
+首先运行服务端程序之后，我们再运行这个上传客户端（注意修改上传的文件路径为本地真实文件路径），执行后可以看到文件被成功上传到服务器的指定路径下。
+
+## 自定义文件名称
+
+很简单，修改 `FileName` 属性即可。
+
+```go
+s := g.Server()
+s.BindHandler("/upload", func(r *ghttp.Request) {
+    file := r.GetUploadFile("TestFile")
+    if file == nil {
+        r.Response.Write("empty file")
+        return
+    }
+    file.Filename = "MyCustomFileName.txt"
+    fileName, err := file.Save(gfile.TempDir())
+    if err != nil {
+        r.Response.Write(err)
+        return
+    }
+    r.Response.Write(fileName)
+})
+s.SetPort(8999)
+s.Run()
+```
+
+## 规范路由接收上传文件
+
+服务端如果通过规范路由方式，那么可以通过结构化的参数获取上传文件：
+
+- 参数接收的数据类型使用 `*ghttp.UploadFile`
+- 如果需要接口文档也支持文件类型，那么参数的标签中设置 `type` 为 `file` 类型

package/skills/goframe-v2/references/WEB/346/234/215/345/212/241/345/274/200/345/217/221/HTTPClient/HTTPClient-/347/233/221/346/216/247/346/214/207/346/240/207.md

@@ -0,0 +1,24 @@
+`HTTP` 客户端支持监控指标能力，默认是关闭的不影响性能，只有在 `metric` 特性全局开启时该组件才会默认开启监控指标计算和生成功能。
+
+## 指标列表
+
+| **指标名称** | **指标类型** | **指标单位** | **指标描述** |
+| --- | --- | --- | --- |
+| `http.client.request.duration` | `Histogram` | `ms` | 客户端请求执行的时间开销。 |
+| `http.client.request.duration_total` | `Counter` | `ms` | 每个请求使用的总时间开销。 |
+| `http.client.connection.duration` | `Histogram` | `ms` | 创建连接所使用的时间开销。 |
+| `http.client.request.total` | `Counter` |  | 已经执行完毕的请求总数。 |
+| `http.client.request.active` | `Gauge` |  | 当前正在处理的请求数量。 |
+| `http.client.request.body_size` | `Counter` | `bytes` | 请求的字节总大小。 |
+| `http.client.response.body_size` | `Counter` | `bytes` | 返回的字节总大小。 |
+
+## 属性列表
+
+| **Label名称** | **Label描述** | **Label示例** |
+| --- | --- | --- |
+| `server.address` | 请求的目标服务地址。可能是域名、IP地址。 | `goframe.org`<br />`10.0.1.132` |
+| `server.port` | 请求的目标服务端口。 | `8000` |
+| `http.request.method` | 请求的方法名称。 | `GET`; `POST`; `DELETE` |
+| `http.response.status_code` | 处理返回的 `HTTP` 状态码。 | `200` |
+| `url.schema` | 使用的请求协议。 | `http`<br />`https` |
+| `network.protocol.version` | 请求协议版本。 | `1.0`<br />`1.1` |