docs: supplement ctx.Response.Header decs in response.md (#760)

cloudwego · Aug 11, 2023 · fa3face · fa3face · vercel · Aug 11, 2023
1 parent a90a24b
commit fa3face
Show file tree

Hide file tree

Showing 4 changed files with 138 additions and 16 deletions.
diff --git a/content/en/docs/hertz/tutorials/basic-feature/context/request.md b/content/en/docs/hertz/tutorials/basic-feature/context/request.md
@@ -664,7 +664,7 @@ Use `RequestContext.Request.Header` to obtain the RequestHeader object, which pr
 | `func (h *RequestHeader) SetConnectionClose(close bool)`|Set connectionClose |
 | `func (h *RequestHeader) ResetConnectionClose()`|Reset connectionClose to false and delete Connection Header|
 | `func (h *RequestHeader) SetByteRange(startPos, endPos int)`|Set Range (Range: bytes=startPos-endPos)|
-| `func (h *RequestHeader) SetMultipartFormBoundary(boundary string)`| Set the boundary for Content Type=multipart/form data |
+| `func (h *RequestHeader) SetMultipartFormBoundary(boundary string)`| Set the boundary for Content-Type=multipart/form data |
 | `func (h *RequestHeader) MultipartFormBoundary() []byte`|Get the value of boundary |
 | `func (h *RequestHeader) Trailer() *Trailer`|Get Trailer|
 | `func (h *RequestHeader) Cookie(key string) []byte`|Obtain the value of Cookie key as key |
@@ -685,24 +685,24 @@ Use `RequestContext.Request.Header` to obtain the RequestHeader object, which pr
 | `func (h *RequestHeader) HasAcceptEncodingBytes(acceptEncoding []byte) bool`|Determine whether Accept-Encoding exists and whether Accept-Encoding includes acceptEncoding|
 | `func (h *RequestHeader) RawHeaders() []byte`|Get original Header |
 | `func (h *RequestHeader) SetRawHeaders(r []byte)`  | Set original Header |
-| `func (h *RequestHeader) Add(key, value string)`| Add or set the header with the key as key. (The key will overwrite the following headers: Content Type, Content Length, Connection, Cookie, Transfer Encoding, Host, User Agent)|
+| `func (h *RequestHeader) Add(key, value string)`| Set the header key value to set multiple headers for the same key, but the key will overwrite the following headers: Content-Type, Content-Length, Connection, Cookie, Transfer-Encoding, Host, User-Agent|
 | `func (h *RequestHeader) InitBufValue(size int)`|Initialize buffer size |
 | `func (h *RequestHeader) GetBufValue() []byte`|Get the value of the buffer |
 | `func (h *RequestHeader) SetCanonical(key, value []byte)`|Set the Header key value, assuming that the key is in canonical form |
-| `func (h *RequestHeader) Set(key, value string)`|Set Header Key Values |
-| `func (h *RequestHeader) SetBytesKV(key, value []byte)`|Set Header Key Values |
+| `func (h *RequestHeader) Set(key, value string)`|Set the header key value to set a single header for the same key |
+| `func (h *RequestHeader) SetBytesKV(key, value []byte)`|Set the header key value of type `[]byte` to set a single header for the same key |
 | `func (h *RequestHeader) DelBytes(key []byte)`|Delete key value pairs with key in the header |
-| `func (h *RequestHeader) AddArgBytes(key, value []byte, noValue bool)`|Add Header key value (key is not Content Type, Content Length, Connection, Cookie, Transfer Encoding, Host, User Agent)|
-| `func (h *RequestHeader) SetArgBytes(key, value []byte, noValue bool)`|Set Header key value (key is not Content Type, Content Length, Connection, Cookie, Transfer Encoding, Host, User Agent)|
+| `func (h *RequestHeader) AddArgBytes(key, value []byte, noValue bool)`|Add Header key value (different from `Add`, the key must not be normalized and will not undergo special processing when it is Content-Type, Content-Length, Connection, Cookie, Transfer-Encoding, Host, or User-Agent)|
+| `func (h *RequestHeader) SetArgBytes(key, value []byte, noValue bool)`|Set Header key value (different from `Set`, The key must not be normalized and will not undergo special processing when it is Content-Type, Content-Length, Connection, Cookie, Transfer-Encoding, Host, or User-Agent)|
 | `func (h *RequestHeader) AppendBytes(dst []byte) []byte`|Attach the complete header to the dst and return |
 | `func (h *RequestHeader) Header() []byte`|Obtain the complete header of type `[]byte` |
 | `func (h *RequestHeader) String() string`|Obtain the complete header |
 | `func (h *RequestHeader) CopyTo(dst *RequestHeader)`|Obtain a copy of RequestHeader |
 | `func (h *RequestHeader) VisitAll(f func(key, value []byte))`|Traverse the key values of all headers and execute the f function |
-| `func (h *RequestHeader) VisitAllCustomHeader(f func(key, value []byte))`|Traverse the key values of all headers and execute the f function, except for Content Type, Content Length, Cookie, Host, User Agent|
+| `func (h *RequestHeader) VisitAllCustomHeader(f func(key, value []byte))`|Traverse the key values of all headers and execute the f function, except for Content-Type, Content-Length, Cookie, Host, User-Agent|
 | `func (h *RequestHeader) Len() int`|Return the number of key value pairs in the header |
 | `func (h *RequestHeader) DisableNormalizing()`|Disable the normalization of header name (capitalize the first letter and the first letter after the Em dash)|
-| `func (h *RequestHeader) IsDisableNormalizing() bool`|Whether to disable standardized for header name |
+| `func (h *RequestHeader) IsDisableNormalizing() bool`|Whether to disable standardized for header name, default not disabled |
 | `func (h *RequestHeader) ResetSkipNormalize()`|Reset Headers except for disableNormalizing status |
 | `func (h *RequestHeader) Reset()`|Reset Headers |
 

diff --git a/content/en/docs/hertz/tutorials/basic-feature/context/response.md b/content/en/docs/hertz/tutorials/basic-feature/context/response.md
@@ -274,7 +274,68 @@ h.GET("/user", func(c context.Context, ctx *app.RequestContext) {
 
 ### ResponseHeader
 
-Use RequestContext.Response.Header to obtain the ResponseHeader object, which is basically consistent with the [RequestHeader](/docs/hertz/tutorials/basic-feature/context/request/#requestheader-object) object and the provided functions.
+Use RequestContext.Response.Header to obtain the ResponseHeader object, this object provides the following methods to obtain/set the response header.
+
+|Function Signature | Description |
+|:--|:--|
+|`func (h *ResponseHeader) IsHTTP11() bool` |Determine if it is the `HTTP/1.1` protocol, and true indicates it is the `HTTP/1.1` protocol  |
+|`func (h *ResponseHeader) SetHeaderLength(length int)`  |Set the length of the response header |
+|`func (h *ResponseHeader) GetHeaderLength()` |Get the length of the response header |
+|`func (h *ResponseHeader) SetContentRange(startPos, endPos, contentLength int)` |Set `Content-Range: bytes startPos-endPos/contentLength` in the response header, such as `Content-Range: bytes 1-5/10` |
+|`func (h *ResponseHeader) NoDefaultContentType() bool` |Obtain the default sending behavior when no Content-Type is specified. False indicates sending the default Content-Type value, true indicates not sending, and the default Content-Type value is `text/plain; charset=utf-8` |
+|`func (h *ResponseHeader) SetNoDefaultContentType(b bool)` |Set the default sending behavior when no Content-Type is specified. False indicates sending the default Content-Type value, true indicates not sending, and the default Content-Type value is `text/plain; charset=utf-8` |
+|`func (h *ResponseHeader) SetContentType(contentType string)` |Set Content-Type |
+|`func (h *ResponseHeader) ContentType() []byte` |Obtain Content-Type |
+|`func (h *ResponseHeader) SetContentTypeBytes(contentType []byte)` |Set Content-Type |
+|`func (h *ResponseHeader) ContentLength() int` |Obtain Content-Length, which can be a negative value. -1 represents `Transfer-Encoding: chunked`, -2 represents `Transfer-Encoding: identity` |
+|`func (h *ResponseHeader) SetContentLength(contentLength int)` |Set Content-Length, which can be a negative value. -1 represents `Transfer-Encoding: chunked`, -2 represents `Transfer-Encoding: identity` |
+|`func (h *ResponseHeader) SetContentLengthBytes(contentLength []byte)` |Set Content-Length for type `[]byte`, which can be a negative value. -1 represents `Transfer-Encoding: chunked`, -2 represents `Transfer-Encoding: identity` |
+|`func (h *ResponseHeader) CopyTo(dst *ResponseHeader)` |Return a copy of the response header, which can be used when there is competitive access to the response header |
+|`func (h *ResponseHeader) GetHeaders() []argsKV` |Return all response headers in the form of key value pairs |
+|`func (h *ResponseHeader) VisitAll(f func(key, value []byte))` |Visit all the key values of all headers and execute the f function |
+|`func (h *ResponseHeader) Get(key string) string` |Obtain the value of key, concurrency security |
+|`func (h *ResponseHeader) GetAll(key string) []string` |Obtain all values of key with type `[]byte` (used to obtain multiple values with the same key),  concurrency safety |
+|`func (h *ResponseHeader) Peek(key string) []byte` |Obtain a key value of type `[]byte` as key, which is not secure for concurrency, and using `Get` when competing for access |
+|`func (h *ResponseHeader) PeekAll(key string) [][]byte` |Obtain all values of type `[]byte` key as key (used to obtain multiple values with the same key), which is not secure for concurrency, and uses `GetAll` when competing for access |
+|`func (h *ResponseHeader) Set(key, value string)` |Set the header key value to set a single header for the same key |
+|`func (h *ResponseHeader) SetBytesV(key string, value []byte)` |Set the header key value of type `[]byte` to set a single header for the same key |
+|`func (h *ResponseHeader) Add(key, value string)` |Set the header key value to set multiple headers for the same key, but the key will overwrite the following headers: Content Type, Content Length, Connection, Cookie, Transfer Encoding, Host, User Agent |
+| `func (h *ResponseHeader) AddArgBytes(key, value []byte, noValue bool)`|Add Header key value (different from `Add`, the key must not be normalized and will not undergo special processing when it is Content-Type, Content-Length, Content-Encoding, Connection, Server, Set-Cookie, Transfer-Encoding)|
+| `func (h *ResponseHeader) SetArgBytes(key, value []byte, noValue bool)`|Set Header key value (different from `Set`, the key must not be normalized and will not undergo special processing when it is Content-Type, Content-Length, Content-Encoding, Connection, Server, Set-Cookie, Transfer-Encoding)|
+|`func (h *ResponseHeader) Del(key string)` |Delete key value pairs with key in the header |
+|`func (h *ResponseHeader) DelBytes(key []byte)` |Delete key value pairs with key in the header |
+|`func (h *ResponseHeader) AppendBytes(dst []byte) []byte` |Attach the complete header to the dst and return |
+|`func (h *ResponseHeader) Header() []byte` |Obtain the complete header of type `[]byte` |
+|`func (h *ResponseHeader) PeekLocation() []byte` |Return the value with key `Location` in the header  |
+|`func (h *ResponseHeader) Cookie(cookie *Cookie) bool` |Fill cookie for the given cookie.Key, and return false if the cookie.Key is missing |
+|`func (h *RequestHeader) FullCookie() []byte` |Return the complete cookie as a byte array |
+|`func (h *ResponseHeader) SetCookie(cookie *Cookie)` |Set Cookie Key Values |
+|`func (h *ResponseHeader) VisitAllCookie(f func(key, value []byte))` |Visit all the key values of all cookies and execute the f function |
+|`func (h *ResponseHeader) DelAllCookies()` |Delete all cookies |
+|`func (h *ResponseHeader) DelCookie(key string)` |Delete cookie with key in the response header. To delete cookies from the client, use the `DelClientCookie` function |
+|`func (h *ResponseHeader) DelCookieBytes(key []byte)` |Delete cookie with key in the response header. To delete cookies from the client, use the `DelClientCookieBytes` function |
+|`func (h *ResponseHeader) DelClientCookie(key string)` |Remove the cookie from the client |
+|`func (h *ResponseHeader) DelClientCookieBytes(key []byte)` |Remove the cookie from the client |
+|`func (h *ResponseHeader) SetConnectionClose(close bool)`|Set the `Connection: close` flag in the response header |
+|`func (h *ResponseHeader) ConnectionClose() bool` |Determine if Connection: close is included |
+|`func (h *ResponseHeader) ContentEncoding() []byte` |Obtion Content-Encoding |
+|`func (h *ResponseHeader) SetContentEncoding(contentEncoding string)` |Set Content-Encoding |
+|`func (h *ResponseHeader) SetContentEncodingBytes(contentEncoding []byte)` |Set Content-Encoding |
+|`func (h *ResponseHeader) SetCanonical(key, value []byte)` |Set the Header key value, assuming that the key is in canonical form |
+|`func (h *ResponseHeader) Server() []byte` |Return the value with key `Server` in the header |
+|`func (h *ResponseHeader) SetServerBytes(server []byte)` |Set the key in the header to the value of Server |
+|`func (h *ResponseHeader) MustSkipContentLength() bool` |Determine if there is a response body (according to the HTTP/1.1 protocol, there is no response body when the response status codes are 1xx, 204, or 304) |
+|`func (h *ResponseHeader) StatusCode() int` |Obtion StatusCode |
+|`func (h *ResponseHeader) SetStatusCode(statusCode int)`|Set StatusCode |
+|`func (h *ResponseHeader) Len() int` |Return the number of headers |
+|`func (h *ResponseHeader) DisableNormalizing()` |Disable the normalization of header name (capitalize the first letter and the first letter after the Em dash) |
+|`func (h *ResponseHeader) IsDisableNormalizing() bool` |Whether to disable the normalization of header names, default not disabled |
+|`func (h *ResponseHeader) Trailer() *Trailer` |Get Trailer |
+|`func (h *ResponseHeader) SetProtocol(p string)` |Set protocol name |
+|`func (h *ResponseHeader) GetProtocol() string` |Get protocol name |
+|`func (h *ResponseHeader) Reset()`|Reset the response header |
+|`func (h *ResponseHeader) ResetSkipNormalize()` |Reset the response header, except for the `disableNormalizing` state |
+|`func (h *ResponseHeader) ResetConnectionClose()` |Reset the connectionClose flag to false and delete the Connection Header |
 
 ## Render
 

diff --git a/content/zh/docs/hertz/tutorials/basic-feature/context/request.md b/content/zh/docs/hertz/tutorials/basic-feature/context/request.md
@@ -685,15 +685,15 @@ h.Post("/user", func(c context.Context, ctx *app.RequestContext) {
 | `func (h *RequestHeader) HasAcceptEncodingBytes(acceptEncoding []byte) bool`|判断是否存在 Accept-Encoding 以及 Accept-Encoding 是否包含 acceptEncoding|
 | `func (h *RequestHeader) RawHeaders() []byte`|获取原始 Header |
 | `func (h *RequestHeader) SetRawHeaders(r []byte)`  | 设置原始 Header |
-| `func (h *RequestHeader) Add(key, value string)`| 添加或设置键为 key 的 Header ( key 会覆盖以下 Header: Content-Type, Content-Length, Connection, Cookie, Transfer-Encoding, Host, User-Agent)|
+| `func (h *RequestHeader) Add(key, value string)`| 添加或设置键为 key 的 Header，用于为同一个 Key 设置多个 Header，但 key 会覆盖以下 Header: Content-Type, Content-Length, Connection, Cookie, Transfer-Encoding, Host, User-Agent|
 | `func (h *RequestHeader) InitBufValue(size int)`|初始化缓冲区大小 |
 | `func (h *RequestHeader) GetBufValue() []byte`|获取缓冲区的值 |
 | `func (h *RequestHeader) SetCanonical(key, value []byte)`|设置 Header 键值，假设该键是规范形式 |
-| `func (h *RequestHeader) Set(key, value string)`|设置 Header 键值 |
-| `func (h *RequestHeader) SetBytesKV(key, value []byte)`|设置 Header 键值 |
+| `func (h *RequestHeader) Set(key, value string)`|设置 Header 键值，用于为同一个 Key 设置单个 Header |
+| `func (h *RequestHeader) SetBytesKV(key, value []byte)`|设置 `[]byte` 类型的 Header 键值，用于为同一个 Key 设置单个 Header |
 | `func (h *RequestHeader) DelBytes(key []byte)`|删除 Header 中键为 key 的键值对 |
-| `func (h *RequestHeader) AddArgBytes(key, value []byte, noValue bool)`|添加 Header 键值（key 不为 Content-Type, Content-Length, Connection, Cookie, Transfer-Encoding, Host, User-Agent）|
-| `func (h *RequestHeader) SetArgBytes(key, value []byte, noValue bool)`|设置 Header 键值（key 不为 Content-Type, Content-Length, Connection, Cookie, Transfer-Encoding, Host, User-Agent）|
+| `func (h *RequestHeader) AddArgBytes(key, value []byte, noValue bool)`|添加 Header 键值（与 `Add` 不同，key 一定不会被规范化且 key 为 Content-Type, Content-Length, Connection, Cookie, Transfer-Encoding, Host, User-Agent 时不会做特殊处理）|
+| `func (h *RequestHeader) SetArgBytes(key, value []byte, noValue bool)`|设置 Header 键值（与 `Set` 不同，key 一定不会被规范化且 key 为 Content-Type, Content-Length, Connection, Cookie, Transfer-Encoding, Host, User-Agent 时不会做特殊处理）|
 | `func (h *RequestHeader) AppendBytes(dst []byte) []byte`|将完整的 Header 附加到 dst 中并返回 |
 | `func (h *RequestHeader) Header() []byte`|获取 `[]byte` 类型的完整的 Header |
 | `func (h *RequestHeader) String() string`|获取完整的 Header |
@@ -702,7 +702,7 @@ h.Post("/user", func(c context.Context, ctx *app.RequestContext) {
 | `func (h *RequestHeader) VisitAllCustomHeader(f func(key, value []byte))`|遍历所有 Header 的键值并执行 f 函数，以下 key 除外：Content-Type, Content-Length, Cookie, Host, User-Agent）|
 | `func (h *RequestHeader) Len() int`|返回 Header 的数量 |
 | `func (h *RequestHeader) DisableNormalizing()`|禁用 Header 名字的规范化 (首字母和破折号后第一个字母大写)|
-| `func (h *RequestHeader) IsDisableNormalizing() bool`|是否禁用 Header 名字的规范化 |
+| `func (h *RequestHeader) IsDisableNormalizing() bool`|是否禁用 Header 名字的规范化，默认不禁用 |
 | `func (h *RequestHeader) ResetSkipNormalize()`|重置 Headers，除了 disableNormalizing 状态 |
 | `func (h *RequestHeader) Reset()`|重置 Headers |