diff --git a/content/en/docs/hertz/faq/_index.md b/content/en/docs/hertz/faq/_index.md index 6bf12d3629b..f4ba2c939d8 100644 --- a/content/en/docs/hertz/faq/_index.md +++ b/content/en/docs/hertz/faq/_index.md @@ -35,6 +35,10 @@ For very vast requests cases, use a combination of streaming and go net. If the framework reports the following error codes, you can check it for possible causes. If there is an error code other than the following, the error code is not caused by the framework and needs to be located by the user to see whether it is set by itself or by some middleware. +### 403 + +This status code is returned only when the `fs` feature is enabled and a directory index is accessed without permission. Hertz does not return `403` in other scenarios. + ### 404 1. Access to the wrong port, commonly access to the debug port. @@ -43,10 +47,18 @@ If the framework reports the following error codes, you can check it for possibl 1. Check whether all expected routes are registered correctly based on the startup log. 2. Check that the access method is correct. +### 413 + +The request body sent by the client exceeds the maximum size configured by [`WithMaxRequestBodySize`](../reference/config.md) on the server side. The default limit is 4 MB. + ### 417 The server returns `false` after executing the custom `ContinueHandler` (the server actively rejects the subsequent body of the 100 Continue). +### 431 + +The request header sent by the client exceeds the maximum size configured by [`WithMaxHeaderBytes`](../reference/config.md) on the server side. The default limit is 1 MB. + ### 500 1. Throwing the panic in middleware or in `handlerFunc`. diff --git a/content/en/docs/hertz/getting-started/_index.md b/content/en/docs/hertz/getting-started/_index.md index b7c684d405b..440159bf46d 100644 --- a/content/en/docs/hertz/getting-started/_index.md +++ b/content/en/docs/hertz/getting-started/_index.md @@ -10,7 +10,7 @@ description: "Preparation of Hertz development environment, quick start, and bas ## Set Up Golang Development Environment 1. If you haven't set up your Golang environment yet, you can refer to [Golang Install](https://go.dev/doc/install). -2. We recommend that you use the latest version of Golang, or make sure it's >= v1.16. You can choose to use the earlier versions, but the compatibility and stability are not guaranteed. +2. We recommend that you use the latest version of Golang, or make sure it's >= v1.19. You can choose to use the earlier versions, but the compatibility and stability are not guaranteed. 3. Make sure the go mod support is enabled (for Golang versions >= v1.15, it is enabled by default). > Currently, Hertz supports Linux, macOS, and Windows systems. diff --git a/content/en/docs/hertz/reference/config.md b/content/en/docs/hertz/reference/config.md index ec5358dce26..d77b11b3997 100644 --- a/content/en/docs/hertz/reference/config.md +++ b/content/en/docs/hertz/reference/config.md @@ -23,8 +23,8 @@ func main() { | Configuration Name | Type | Description | | :-------------------------------- | :----------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| WithTransport | network.NewTransporter | Replace the transport. Default：netpoll.NewTransporter | -| WithHostPorts | string | Specify the listening address and port | +| WithTransport | network.NewTransporter | Replace the transport. The default depends on platform and environment variables: netpoll on linux/darwin with amd64/arm64 when `HERTZ_NO_NETPOLL=true` is not set; falls back to standard for TLS; standard otherwise. | +| WithHostPorts | string | Specify the listening address and port. Default: :8888 | | WithKeepAliveTimeout | time.Duration | Set the keep-alive time of tcp persistent connection, generally no need to modify it, you should more pay attention to idleTimeout rather than modifying it. Default: 1min. | | WithReadTimeout | time.Duration | The timeout of data reading. Default：3min. | | WithIdleTimeout | time.Duration | The free timeout of the request link for persistent connection. Default: 3min. | @@ -46,15 +46,16 @@ func main() { | WithALPN | bool | Whether to enable ALPN. Default: false. | | WithTracer | tracer.Tracer | Inject tracer implementation, if not inject Tracer. Default: close. | | WithTraceLevel | stats.Level | Set trace level, Default: LevelDetailed. | -| WithWriteTimeout | time.Duration | The timeout of data writing. Default：infinite. | +| WithWriteTimeout | time.Duration | The timeout of data writing. Default: 0 (unlimited). Only enabled in netpoll transport when value > 0. | | WithRedirectFixedPath | bool | If enabled, if the current request path does not match, the server will try to repair the request path and re-match, if the match is successful and the request is a GET request, it will return status code 301 for redirect, other requests will return 308 for redirect. Disabled by default | | WithBasePath | string | Set the base path, which must be prefixed and suffixed with `/`. The default is `/` | -| WithMaxKeepBodySize | int | Sets the maximum size of the request body and response body to be retained during reclaim. Unit: Byte. Default value: 4 _ 1024 _ 1024 | +| WithMaxKeepBodySize | int | Sets the maximum size of the request body and response body to be retained during reclaim. Unit: Byte. Default value: `4 * 1024 * 1024` (4MB) | | WithGetOnly | bool | If enabled, only GET requests are accepted. Disabled by default | | WithKeepAlive | bool | If enabled, use HTTP keepalive. Enabled by default | -| WithAltTransport | network.NewTransporter | Set up the alternate transport. Default value: netpoll.NewTransporter | +| WithAltTransport | network.NewTransporter | Set up the alternate transport. Default value: nil. This configuration is only for extension purposes, set it explicitly if needed. | | WithH2C | bool | Sets whether H2C is enabled. Disabled by default | -| WithReadBufferSize | int | Set the read buffer size while limiting the HTTP header size. Default value: 4 \* 1024 | +| WithReadBufferSize | int | Set the read buffer size. Default value: 4 \* 1024 | +| WithMaxHeaderBytes | int | Set the maximum bytes of HTTP request header. Default 1MB (1 << 20), returns 431 Request Header Fields Too Large if exceeded | | WithRegistry | registry.Registry, \*registry.Info | Setup registry configuration, service registration information. Default value: registry.NoopRegistry, nil | | WithAutoReloadRender | bool, time.Duration | Set up the automatic reload rendering configuration. Default value: false, 0 | | WithDisablePrintRoute | bool | Sets whether debugPrintRoute is disabled. Default disable | @@ -62,14 +63,6 @@ func main() { | WithOnConnect | func(ctx context.Context, conn network.Conn) context.Context | Set the onConnect function. It can received data from connection in netpoll. In go net, it will be called after converting tls connection. Default value: nil | | WithDisableHeaderNamesNormalizing | bool | Sets whether or not to disable Request and Response Header name normalization (capitalization of the first letter and the first letter after a dash) | -Server Connection limitation: - -- If you are using the standard network library, there is no such restriction. -- If netpoll is used, the maximum number of connections is 10000 (this is - the [gopool](https://github.com/bytedance/gopkg/blob/b9c1c36b51a6837cef4c2223e11522e3a647460c/util/gopool/gopool.go#L46)) - used at the bottom of netpoll. Yes, the modification method is also very simple, just call the function provided by - gopool: `gopool.SetCap(xxx)` (you can call it once in main.go). - ## Client The configuration items on the Client side all use `client.xxx` when initializing the Client, such as: @@ -88,17 +81,17 @@ func main() { | Configuration Name | Type | Description | | :-------------------------------- | :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | WithDialTimeout | time.Duration | Connection establishment timeout. Default: 1s. | -| WithMaxConnsPerHost | int | Set the maximum number of connections for every host. Default: 512. | +| WithMaxConnsPerHost | int | Set the maximum number of connections for every host. Default: 0 (<=0 means unlimited). | | WithMaxIdleConnDuration | time.Duration | Set the idle connection timeout, which will close the connection after the timeout Default: 10s. | -| WithMaxConnDuration | time.Duration | Set the maximum keep-alive time of the connection, when the timeout expired, the connection will be closed after the current request is completed. Default: infinite. | +| WithMaxConnDuration | time.Duration | Set the maximum keep-alive time of the connection, when the timeout expired, the connection will be closed after the current request is completed. Default: 0 (unlimited). | | WithMaxConnWaitTimeout | time.Duration | Set the maximum time to wait for an idle connection. Default: no wait. | | WithKeepAlive | bool | Whether to use persistent connection. Default: true. | -| WithRetryConfig | ...retry.Option | Set the retry config of client. Hertz version >= v0.4.0. | +| WithRetryConfig | ...retry.Option | Set the retry config of client. Hertz version >= v0.4.0. Not enabled by default; calling `WithRetryConfig()` sets `MaxAttemptTimes=1` (no retry). To enable retry, set explicitly, e.g.: `client.WithRetryConfig(retry.WithMaxAttemptTimes(3))` | | ~~WithMaxIdempotentCallAttempts~~ | int | Set the maximum number of calls. If a call fails, it will be retried. Default: 1 (That is no retry). v0.4.0 is obsolete. Only available before v0.4.0. It is recommended to upgrade Hertz version >= v0.4.0 and use WithRetryConfig instead. | -| WithClientReadTimeout | time.Duration | Set the maximum time to read the response. Default: infinite. | +| WithClientReadTimeout | time.Duration | Set the maximum time to read the response. Default: 0 (unlimited). Recommended to set an explicit timeout in production. | | WithTLSConfig | \*tls.Config | Set the client's TLS config for mutual TLS authentication. | -| WithDialer | network.Dialer | Set the network library used by the client. Default: netpoll. | +| WithDialer | network.Dialer | Set the network library used by the client. The default depends on platform and environment variables: netpoll on linux/darwin with amd64/arm64 when `HERTZ_NO_NETPOLL=true` is not set; falls back to standard for TLS; standard otherwise. | | WithResponseBodyStream | bool | Set whether to use stream processing. Default: false. | | WithDialFunc | client.DialFunc | Set Dial Function. | -| WithWriteTimeout | time.Duration | The timeout of data writing. Default：infinite. | +| WithWriteTimeout | time.Duration | The timeout of data writing. Default: 0 (unlimited). | | WithHostClientConfigHook | func(hc interface{}) error | Set the function hook for re-configure the host client. The function needs to assert the parameter hc as the required struct, such as http1.HostClient, and then perform specific processing. | diff --git a/content/en/docs/hertz/reference/version.md b/content/en/docs/hertz/reference/version.md index 445b2fca071..50334376a17 100644 --- a/content/en/docs/hertz/reference/version.md +++ b/content/en/docs/hertz/reference/version.md @@ -8,6 +8,12 @@ description: "Hertz version description." Hertz complies with the [Semantic Version 2.0.0](https://semver.org/lang/zh-CN/) release version. +**Current Version: [![Release](https://img.shields.io/github/v/release/cloudwego/hertz)](https://github.com/cloudwego/hertz/releases)** + - Master version number: Upgrade this version number if the API provided by Hertz becomes incompatible - Secondary version number: Upgrade this version number when Hertz provides new features while maintaining backward compatibility - Revision number: Upgrade this version number when Hertz's code provides minor features or backward-compatible optimizations and issue fixes + +## Release Notes + +See [GitHub Releases](https://github.com/cloudwego/hertz/releases). diff --git a/content/en/docs/hertz/tutorials/basic-feature/adaptor.md b/content/en/docs/hertz/tutorials/basic-feature/adaptor.md index 24165112c70..60b8378b8a2 100644 --- a/content/en/docs/hertz/tutorials/basic-feature/adaptor.md +++ b/content/en/docs/hertz/tutorials/basic-feature/adaptor.md @@ -61,14 +61,14 @@ func main() { | Function | Function Signature | Description | | ------------------ | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| GetCompatRequest | `func GetCompatRequest(req *protocol.Request) (*http.Request, error)` | Build and fetch Go standard library `http.Request` from Hertz `protocol.Request` | +| ~~GetCompatRequest~~ | `func GetCompatRequest(req *protocol.Request) (*http.Request, error)` | **Deprecated: Please use [`adaptor.HertzHandler`](./http-adaptor.md) instead.** Build and fetch Go standard library `http.Request` from Hertz `protocol.Request` | | CopyToHertzRequest | `func CopyToHertzRequest(req *http.Request, hreq *protocol.Request)` | Copy the `URI`, `Host`, `Method`, `Protocol`, `Header` of Go standard library `http.Request` to Hertz `protocol.Request`, The `Body` field will be adapted by sharing `Reader` | ## http.ResponseWriter | Function / Struct | Function Signature | Description | | ----------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | -| GetCompatResponseWriter | `func GetCompatResponseWriter(resp *protocol.Response) http.ResponseWriter` | Build and fetch Go standard library `http.ResponseWriter` from Hertz `protocol.Response` | +| ~~GetCompatResponseWriter~~ | `func GetCompatResponseWriter(resp *protocol.Response) http.ResponseWriter` | **Deprecated: Please use [`adaptor.HertzHandler`](./http-adaptor.md) instead.** Build and fetch Go standard library `http.ResponseWriter` from Hertz `protocol.Response` | | compatResponse | / | `compatResponse` implements the `http.ResponseWriter` interface and has adaptations to `Header`, `Write` and `WriteHeader` functions | ## Handler diff --git a/content/en/docs/hertz/tutorials/basic-feature/client.md b/content/en/docs/hertz/tutorials/basic-feature/client.md index e5fa9239f9f..166c0dc0f5f 100644 --- a/content/en/docs/hertz/tutorials/basic-feature/client.md +++ b/content/en/docs/hertz/tutorials/basic-feature/client.md @@ -55,21 +55,21 @@ func main() { | **Option** | **Default** | **Description** | | --------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | WithDialTimeout | 1s | dial timeout. | -| WithMaxConnsPerHost | 512 | maximum number of connections per host which may be established. | +| WithMaxConnsPerHost | 0 | maximum number of connections per host which may be established. Default 0 means unlimited. | | WithMaxIdleConnDuration | 10s | max idle connection duration, idle keep-alive connections are closed after this duration. | | WithMaxConnDuration | 0s | max connection duration, keep-alive connections are closed after this duration. | | WithMaxConnWaitTimeout | 0s | maximum duration for waiting for a free connection. | | WithKeepAlive | true | determines whether use keep-alive connection, default use. | -| WithClientReadTimeout | 0s | maximum duration for full response reading (including body). | +| WithClientReadTimeout | 0s | maximum duration for full response reading (including body). Default 0 means unlimited | | WithTLSConfig | nil | tlsConfig to create a tls connection, for specific configuration information, please refer to [tls](/docs/hertz/tutorials/basic-feature/tls/). | -| WithDialer | network.Dialer | specific dialer. | +| WithDialer | network.Dialer | specific dialer. The default depends on platform: netpoll on linux/darwin with amd64/arm64 when `HERTZ_NO_NETPOLL=true` is not set; falls back to standard for TLS; standard otherwise. | | WithResponseBodyStream | false | determine whether read body in stream or not, default not read in stream. | | WithDisableHeaderNamesNormalizing | false | whether disable header names normalizing, default not disabled, for example, cONTENT-lenGTH -> Content-Length. | | WithName | "" | set client name which used in User-Agent Header. | | WithNoDefaultUserAgentHeader | false | whether default no User-Agent header, default with User-Agent header. | | WithDisablePathNormalizing | false | whether disable path normalizing, default specification path, for example, http://localhost:8080/hello/../ hello -> http://localhost:8080/hello. | -| WithRetryConfig | nil | retry configuration, for specific configuration information, please refer to [retry](/docs/hertz/tutorials/basic-feature/retry/). | -| WithWriteTimeout | 0s | write timeout. | +| WithRetryConfig | nil | retry configuration. Not enabled by default; calling it sets `MaxAttemptTimes=1` (no retry). To enable retry, set explicitly. For details see [retry](/docs/hertz/tutorials/basic-feature/retry/). | +| WithWriteTimeout | 0s | write timeout. Default 0 means unlimited. | | WithConnStateObserve | nil, 5s | set function to observe and record the connection status of HTTP client, as well as observe execution intervals. | | WithDialFunc | network.Dialer | set dialer function. | | WithHostClientConfigHook | nil | Set the hook function for re-configure the host client. | diff --git a/content/en/docs/hertz/tutorials/basic-feature/engine.md b/content/en/docs/hertz/tutorials/basic-feature/engine.md index e2a04e9e2ed..c06ddbd31e4 100644 --- a/content/en/docs/hertz/tutorials/basic-feature/engine.md +++ b/content/en/docs/hertz/tutorials/basic-feature/engine.md @@ -21,12 +21,12 @@ type Hertz struct { | **Option** | **Default** | **Description** | | :-------------------------------- | :------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| WithTransport | network.NewTransporter | Replace the transport | +| WithTransport | platform-dependent | Replace the transport. The default depends on platform and environment variables (see [Network Lib](/docs/hertz/tutorials/basic-feature/network-lib/)). | | WithHostPorts | `:8888` | Specify the listening address and port | | WithKeepAliveTimeout | 1min | Set the keep-alive time of tcp persistent connection, generally no need to modify it, you should more pay attention to idleTimeout rather than modifying it | | WithReadTimeout | 3min | The timeout of data reading | | WithIdleTimeout | 3min | The free timeout of the request link for persistent connection | -| WithMaxRequestBodySize | 4 _ 1024 _ 1024 | Max body size of a request | +| WithMaxRequestBodySize | `4 * 1024 * 1024` (4MB) | Max body size of a request | | WithRedirectTrailingSlash | true | Whether to redirect with the / which is at the end of the router automatically. For example： If there is only /foo/ in the router, /foo will be redirected to /foo/. And if there is only /foo in the router, /foo/ will be redirected to /foo | | WithRemoveExtraSlash | false | RemoveExtraSlash makes the parameter still valid when it contains an extra /. For example, if WithRemoveExtraSlash is true user//xiaoming can match the user/:name router | | WithUnescapePathValues | true | If true, the request path will be escaped automatically (eg. '%2F' -> '/'). If UseRawPath is false (the default), UnescapePathValues is true, because URI().Path() will be used and it is already escaped. To set WithUnescapePathValues to false, you need to set WithUseRawPath to true | @@ -36,20 +36,21 @@ type Hertz struct { | WithStreamBody | false | If true, the body will be handled by stream processing | | WithNetwork | "tcp" | Set the network protocol, optional: tcp，udp，unix(unix domain socket) | | WithExitWaitTime | 5s | Set the graceful exit time. the Server will stop connection establishment for new requests and set the Connection: Close header for each request after closing. When the set time is reached, Server will to be closed. the Server can be closed early when all connections have been closed | -| WithTLS | nil | Configuring server tls capabilities, For detailed information, please refer to [TLS](/zh/docs/hertz/tutorials/basic-feature/tls/) | +| WithTLS | nil | Configuring server tls capabilities. For detailed information, please refer to [TLS](/docs/hertz/tutorials/basic-feature/tls/) | | WithListenConfig | nil | Set the listener configuration. Can be used to set whether to allow reuse ports, etc. | | WithALPN | false | Whether to enable ALPN | | WithTracer | []interface{}{} | Inject tracer implementation, if not inject Tracer, default: close. | | WithTraceLevel | LevelDetailed | Set trace level | -| WithWriteTimeout | infinite | The timeout of data writing | +| WithWriteTimeout | 0 (unlimited) | The timeout of data writing. Only enabled in netpoll transport when value > 0. | | WithRedirectFixedPath | false | If enabled, if the current request path does not match, the server will try to repair the request path and re-match, if the match is successful and the request is a GET request, it will return status code 301 for redirect, other requests will return 308 for redirect | | WithBasePath | `/` | Set the base path, which must be prefixed and suffixed with `/` | -| WithMaxKeepBodySize | 4 _ 1024 _ 1024 | Sets the maximum size of the request body and response body to be retained during reclaim. Unit: Byte | +| WithMaxKeepBodySize | `4 * 1024 * 1024` (4MB) | Sets the maximum size of the request body and response body to be retained during reclaim. Unit: Byte | | WithGetOnly | false | If enabled, only GET requests are accepted | | WithKeepAlive | true | If enabled, use HTTP keepalive | -| WithAltTransport | network.NewTransporter | Set up the alternate transport | +| WithAltTransport | nil | Set up the alternate transport. Extension point only, set it explicitly if needed. | | WithH2C | false | Sets whether H2C is enabled | | WithReadBufferSize | 4 \* 1024 | Set the read buffer size | +| WithMaxHeaderBytes | 1MB (1 << 20) | Set the maximum bytes of HTTP request header. Returns 431 Request Header Fields Too Large if exceeded | | WithRegistry | registry.NoopRegistry, nil | Setup registry configuration, service registration information | | WithAutoReloadRender | false, 0 | Set up the automatic reload rendering configuration | | WithDisablePrintRoute | false | Sets whether debugPrintRoute is disabled | @@ -57,14 +58,6 @@ type Hertz struct { | WithOnConnect | nil | Set the onConnect function. It can received data from connection in netpoll. In go net, it will be called after converting tls connection | | WithDisableHeaderNamesNormalizing | false | Sets whether or not to disable Request and Response Header name normalization (capitalization of the first letter and the first letter after a dash) | -Server Connection limitation: - -- If you are using the standard network library, there is no such restriction. -- If netpoll is used, the maximum number of connections is 10000 (this is - the [gopool](https://github.com/bytedance/gopkg/blob/b9c1c36b51a6837cef4c2223e11522e3a647460c/util/gopool/gopool.go#L46)) - used at the bottom of netpoll. Yes, the modification method is also very simple, just call the function provided by - gopool: `gopool.SetCap(xxx)` (you can call it once in main.go). - The configuration items on the server side are initialized using the `server.WithXXX` method, such as: ```go diff --git a/content/en/docs/hertz/tutorials/basic-feature/network-lib.md b/content/en/docs/hertz/tutorials/basic-feature/network-lib.md index 5ddeb6255a9..e0e6ce281db 100644 --- a/content/en/docs/hertz/tutorials/basic-feature/network-lib.md +++ b/content/en/docs/hertz/tutorials/basic-feature/network-lib.md @@ -8,16 +8,16 @@ description: "Hertz integrated Netpoll and Golang network lib by default. Users ## Usage -While creating a server, Hertz uses netpoll by default, but this behavior can be modified by configuration: +While creating a server, Hertz uses netpoll by default. This behavior can be modified by configuration, and can also be disabled by setting `HERTZ_NO_NETPOLL=true`. -> Note: Netpoll currently does not support Windows. Windows will automatically switch the network library to go net through conditional compilation. +> Note: Netpoll currently only support linux/darwin && amd64/arm64 platforms, and does not support Windows. Windows will automatically switch the network library to go net through conditional compilation. Also, TLS scenarios will fall back to the standard network library. ```go server.New(server.WithTransport(standard.NewTransporter)) server.New(server.WithTransport(netpoll.NewTransporter)) ``` -While creating a Client, it can also be modified by configuration: +While creating a Client, it can also be modified by configuration (and can be disabled by setting `HERTZ_NO_NETPOLL=true`): ```go client.NewClient(client.WithDialer(standard.NewDialer())) diff --git a/content/en/docs/hertz/tutorials/toolkit/command.md b/content/en/docs/hertz/tutorials/toolkit/command.md index fcf0b7d9335..860ab122370 100644 --- a/content/en/docs/hertz/tutorials/toolkit/command.md +++ b/content/en/docs/hertz/tutorials/toolkit/command.md @@ -72,14 +72,16 @@ OPTIONS: --thriftgo value, -t value [ --thriftgo value, -t value ] Specify arguments for the thriftgo. ({flag}={value}) --protoc value, -p value [ --protoc value, -p value ] Specify arguments for the protoc. ({flag}={value}) --option_package value, -P value [ --option_package value, -P value ] Specify the package path. ({include_path}={import_path}) + --trim_gopackage value, --trim_pkg value Trim the prefix of go_package for protobuf. --no_recurse Generate master model only. (default: false) --force, -f Force new a project, which will overwrite the generated files (default: false) --enable_extends Parse 'extends' for thrift IDL (default: false) + --sort_router Sort router register code, to avoid code difference (default: false) --json_enumstr Use string instead of num for json enums when idl is thrift. (default: false) --unset_omitempty Remove 'omitempty' tag for generated struct. (default: false) --pb_camel_json_tag Convert Name style for json tag to camel(Only works protobuf). (default: false) --snake_tag Use snake_case style naming for tags. (Only works for 'form', 'query', 'json') (default: false) - --rm_tag value [ --rm_tag value ] Remove the specified tag + --rm_tag value [ --rm_tag value ] Remove the default tag(json/query/form). If the annotation tag is set explicitly, it will not be removed. --exclude_file value, -E value [ --exclude_file value, -E value ] Specify the files that do not need to be updated. --customize_layout value Specify the path for layout template. --customize_layout_data_path value Specify the path for layout template render data. @@ -142,6 +144,10 @@ OPTIONS: +- trim_gopackage/trim_pkg: Trim the prefix of go_package for protobuf + + + - no_recurse: Generate only model code for the master idl, default to false @@ -154,6 +160,10 @@ OPTIONS: +- sort_router: Sort router register code, to avoid code difference + + + - json_enumstr: When idl is thrift, json enums uses string instead of num (the option passed through to thriftgo) @@ -170,7 +180,7 @@ OPTIONS: -- rm_tag value: Remove the specified tag +- rm_tag value: Remove the default tag(json/query/form). If the annotation tag is set explicitly, it will not be removed. @@ -226,13 +236,15 @@ OPTIONS: --thriftgo value, -t value [ --thriftgo value, -t value ] Specify arguments for the thriftgo. ({flag}={value}) --protoc value, -p value [ --protoc value, -p value ] Specify arguments for the protoc. ({flag}={value}) --option_package value, -P value [ --option_package value, -P value ] Specify the package path. ({include_path}={import_path}) + --trim_gopackage value, --trim_pkg value Trim the prefix of go_package for protobuf. --no_recurse Generate master model only. (default: false) --enable_extends Parse 'extends' for thrift IDL (default: false) + --sort_router Sort router register code, to avoid code difference (default: false) --json_enumstr Use string instead of num for json enums when idl is thrift. (default: false) --unset_omitempty Remove 'omitempty' tag for generated struct. (default: false) --pb_camel_json_tag Convert Name style for json tag to camel(Only works protobuf). (default: false) --snake_tag Use snake_case style naming for tags. (Only works for 'form', 'query', 'json') (default: false) - --rm_tag value [ --rm_tag value ] Remove the specified tag + --rm_tag value [ --rm_tag value ] Remove the default tag(json/query/form). If the annotation tag is set explicitly, it will not be removed. --exclude_file value, -E value [ --exclude_file value, -E value ] Specify the files that do not need to be updated. --customize_package value Specify the path for package template. --handler_by_method Generate a separate handler file for each method. (default: false) @@ -285,6 +297,10 @@ OPTIONS: +- trim_gopackage/trim_pkg: Trim the prefix of go_package for protobuf + + + - no_recurse: Generate only model code for the master idl, default to false @@ -293,6 +309,10 @@ OPTIONS: +- sort_router: Sort router register code, to avoid code difference + + + - json_enumstr: When idl is thrift, json enums uses string instead of num (the option passed through to thriftgo) @@ -309,7 +329,7 @@ OPTIONS: -- rm_tag value: Remove the specified tag +- rm_tag value: Remove the default tag(json/query/form). If the annotation tag is set explicitly, it will not be removed. @@ -354,11 +374,12 @@ OPTIONS: --thriftgo value, -t value [ --thriftgo value, -t value ] Specify arguments for the thriftgo. ({flag}={value}) --protoc value, -p value [ --protoc value, -p value ] Specify arguments for the protoc. ({flag}={value}) --no_recurse Generate master model only. (default: false) + --trim_gopackage value, --trim_pkg value Trim the prefix of go_package for protobuf. --json_enumstr Use string instead of num for json enums when idl is thrift. (default: false) --unset_omitempty Remove 'omitempty' tag for generated struct. (default: false) --pb_camel_json_tag Convert Name style for json tag to camel(Only works protobuf). (default: false) --snake_tag Use snake_case style naming for tags. (Only works for 'form', 'query', 'json') (default: false) - --rm_tag value [ --rm_tag value ] Remove the specified tag + --rm_tag value [ --rm_tag value ] Remove the default tag(json/query/form). If the annotation tag is set explicitly, it will not be removed. --exclude_file value, -E value [ --exclude_file value, -E value ] Specify the files that do not need to be updated. --help, -h show help (default: false) ``` @@ -395,6 +416,10 @@ OPTIONS: +- trim_gopackage/trim_pkg: Trim the prefix of go_package for protobuf + + + - json_enumstr: When idl is thrift, json enums uses string instead of num (the option passed through to thriftgo) @@ -411,7 +436,7 @@ OPTIONS: -- rm_tag value: Remove the specified tag +- rm_tag value: Remove the default tag(json/query/form). If the annotation tag is set explicitly, it will not be removed. @@ -441,16 +466,20 @@ OPTIONS: --client_dir value Specify the client path. If not specified, IDL generated path is used for 'client' command; no client code is generated for 'new' command --use value Specify the model package to import for handler. --force_client_dir value Specify the client path, and won't use namespaces as subpaths + --force_client Force update 'hertz_client.go' (default: false) --proto_path value, -I value [ --proto_path value, -I value ] Add an IDL search path for includes. (Valid only if idl is protobuf) --thriftgo value, -t value [ --thriftgo value, -t value ] Specify arguments for the thriftgo. ({flag}={value}) --protoc value, -p value [ --protoc value, -p value ] Specify arguments for the protoc. ({flag}={value}) --no_recurse Generate master model only. (default: false) --enable_extends Parse 'extends' for thrift IDL (default: false) + --trim_gopackage value, --trim_pkg value Trim the prefix of go_package for protobuf. --json_enumstr Use string instead of num for json enums when idl is thrift. (default: false) + --enable_optional Optional field do not transfer for thrift if not set.(Only works for query tag) (default: false) + --query_enumint Use num instead of string for query enum parameter. (default: false) --unset_omitempty Remove 'omitempty' tag for generated struct. (default: false) --pb_camel_json_tag Convert Name style for json tag to camel(Only works protobuf). (default: false) --snake_tag Use snake_case style naming for tags. (Only works for 'form', 'query', 'json') (default: false) - --rm_tag value [ --rm_tag value ] Remove the specified tag + --rm_tag value [ --rm_tag value ] Remove the default tag(json/query/form). If the annotation tag is set explicitly, it will not be removed. --exclude_file value, -E value [ --exclude_file value, -E value ] Specify the files that do not need to be updated. --customize_package value Specify the path for package template. --protoc-plugins value [ --protoc-plugins value ] Specify plugins for the protoc. ({plugin_name}:{options}:{out_dir}) @@ -486,6 +515,10 @@ OPTIONS: +- force_client: Force update 'hertz_client.go' + + + - proto_path/I: When idl is protobuf, specify the search path for idl, the same as the - I instruction for protoc @@ -506,10 +539,22 @@ OPTIONS: +- trim_gopackage/trim_pkg: Trim the prefix of go_package for protobuf + + + - json_enumstr: When idl is thrift, json enums uses string instead of num (the option passed through to thriftgo) +- enable_optional: Optional field do not transfer for thrift if not set.(Only works for query tag) + + + +- query_enumint: Use num instead of string for query enum parameter. + + + - unset_omitempty: When idl is protobuf, generate a model field and remove the omitempty tag; When idl is thrift, whether to add omitempty depends on whether the field is "optional" or "required" @@ -522,7 +567,7 @@ OPTIONS: -- rm_tag value: Remove the specified tag +- rm_tag value: Remove the default tag(json/query/form). If the annotation tag is set explicitly, it will not be removed. diff --git a/content/zh/docs/hertz/faq/_index.md b/content/zh/docs/hertz/faq/_index.md index 322fdb51eb5..e350d300671 100644 --- a/content/zh/docs/hertz/faq/_index.md +++ b/content/zh/docs/hertz/faq/_index.md @@ -29,6 +29,10 @@ description: "Hertz 常见问题解答。" 如果框架报以下的错误码，可以按照可能原因进行排查。如果出现非以下错误码，则不是框架打出来的，需要由使用方定位一下是否自行设置或者由某些中间件设置了错误码。 +### 403 + +仅在启用fs功能，访问无权限的目录索引时才会出现403错误码，其他场景下不会出现403错误码。 + ### 404 1. 访问到了错误的端口上了，常见访问到了 debug 端口 @@ -37,10 +41,18 @@ description: "Hertz 常见问题解答。" 1. 根据启动日志查看是否所有预期路由都正常注册 2. 查看访问方法是否正确 +### 413 + +client 发送的请求体（request body）大小超出服务端配置 [`WithMaxRequestBodySize`](../reference/config.md) 的最大值（默认为 4MB）。 + ### 417 server 在执行完自定义的 `ContinueHandler` 之后返回 `false`（server 主动拒绝掉 100 Continue 后续的 body）。 +### 431 + +client 发送的请求头（request header）大小超出服务端配置 [`WithMaxHeaderBytes`](../reference/config.md) 的最大值（默认为 1MB）。 + ### 500 1. 中间件或者 `handlerFunc` 中抛 panic diff --git a/content/zh/docs/hertz/getting-started/_index.md b/content/zh/docs/hertz/getting-started/_index.md index 64abfa9afef..c34c91a64cc 100644 --- a/content/zh/docs/hertz/getting-started/_index.md +++ b/content/zh/docs/hertz/getting-started/_index.md @@ -9,7 +9,7 @@ description: "Hertz 开发环境准备、快速上手与代码生成工具 hz ## 准备 Golang 开发环境 1. 如果您之前未搭建 Golang 开发环境，可以参考 [Golang 安装](https://go.dev/doc/install)。 -2. 推荐使用最新版本的 Golang，或保证现有 Golang 版本 >= 1.16。小于 1.16 版本，可以自行尝试使用但不保障兼容性和稳定性。 +2. 推荐使用最新版本的 Golang，或保证现有 Golang 版本 >= 1.19。小于 1.19 版本，可以自行尝试使用但不保障兼容性和稳定性。 3. 确保打开 go mod 支持 (Golang >= 1.15 时，默认开启)。 4. 完成安装后，你可能需要设置一下国内代理：`go env -w GOPROXY=https://goproxy.cn`。 diff --git a/content/zh/docs/hertz/reference/config.md b/content/zh/docs/hertz/reference/config.md index eacb1f5c5db..802659dd524 100644 --- a/content/zh/docs/hertz/reference/config.md +++ b/content/zh/docs/hertz/reference/config.md @@ -23,8 +23,8 @@ func main() { | 配置名称 | 类型 | 说明 | | :-------------------------------- | :----------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| WithTransport | network.NewTransporter | 更换底层 transport，默认值：netpoll.NewTransporter | -| WithHostPorts | string | 指定监听的地址和端口 | +| WithTransport | network.NewTransporter | 更换底层 transport。默认值受平台与环境变量影响：在 linux/darwin && amd64/arm64 平台且未设置 `HERTZ_NO_NETPOLL=true` 时默认为 netpoll；TLS 场景会回退至 standard；其他情况为 standard。 | +| WithHostPorts | string | 指定监听的地址和端口。默认值：:8888 | | WithKeepAliveTimeout | time.Duration | tcp 长连接保活时间，一般情况下不用修改，更应该关注 idleTimeout。默认值：1min | | WithReadTimeout | time.Duration | 底层读取数据超时时间。默认值：3min | | WithIdleTimeout | time.Duration | 长连接请求链接空闲超时时间。默认值：3min | @@ -46,15 +46,16 @@ func main() { | WithALPN | bool | 是否开启 ALPN。默认关闭 | | WithTracer | tracer.Tracer | 注入 tracer 实现，如不注入 Tracer 实现，默认关闭 | | WithTraceLevel | stats.Level | 设置 trace level，默认 LevelDetailed | -| WithWriteTimeout | time.Duration | 写入数据超时时间，默认值：无限长 | +| WithWriteTimeout | time.Duration | 写入数据超时时间，默认 0（不限制）。仅当值 >0 时才会在 netpoll transport 中启用超时机制 | | WithRedirectFixedPath | bool | 如果开启，当当前请求路径不能匹配上时，server 会尝试修复请求路径并重新进行匹配，如果成功匹配并且为 GET 请求则会返回状态码 301 进行重定向，其他请求方式返回 308 进行重定向。默认关闭 | | WithBasePath | string | 设置基本路径，前缀和后缀必须为 `/`。默认为 `/` | -| WithMaxKeepBodySize | int | 设置回收时保留的请求体和响应体的最大大小。单位：字节。默认值：4 _ 1024 _ 1024 | +| WithMaxKeepBodySize | int | 设置回收时保留的请求体和响应体的最大大小。单位：字节。默认值：`4 * 1024 * 1024` (4MB) | | WithGetOnly | bool | 如果开启则只接受 GET 请求。默认关闭 | | WithKeepAlive | bool | 如果开启则使用 HTTP 长连接。默认开启 | -| WithAltTransport | network.NewTransporter | 设置备用 transport。默认值：netpoll.NewTransporter | +| WithAltTransport | network.NewTransporter | 设置备用 transport。默认值：nil。该配置仅作为扩展点，如需使用请显式设置。 | | WithH2C | bool | 设置是否开启 H2C。默认关闭 | -| WithReadBufferSize | int | 设置读缓冲区大小，同时限制 HTTP header 大小。默认值：4 \* 1024 | +| WithReadBufferSize | int | 设置读缓冲区大小。默认值：4 \* 1024 | +| WithMaxHeaderBytes | int | 设置 HTTP 请求 header 的最大字节数，默认 1MB（1 << 20），超限返回 431 Request Header Fields Too Large | | WithRegistry | registry.Registry, \*registry.Info | 设置注册中心配置，服务注册信息。默认值：registry.NoopRegistry, nil | | WithAutoReloadRender | bool, time.Duration | 设置自动重载渲染配置。默认值：false, 0 | | WithDisablePrintRoute | bool | 设置是否禁用 debugPrintRoute。默认不禁用 | @@ -62,13 +63,6 @@ func main() { | WithOnConnect | func(ctx context.Context, conn network.Conn) context.Context | 设置 onConnect 函数。它可以接收来自 netpoll 连接的数据。在 go net 中，它将在转换 TLS 连接后被调用。默认值：nil | | WithDisableHeaderNamesNormalizing | bool | 设置是否禁用 Request 和 Response Header 名字的规范化 (首字母和破折号后第一个字母大写) | -Server Connection 数量限制: - -- 如果是使用标准网络库，无此限制 -- 如果是使用 netpoll，最大连接数为 10000 - （这个是 netpoll 底层使用的 [gopool](https://github.com/bytedance/gopkg/blob/b9c1c36b51a6837cef4c2223e11522e3a647460c/util/gopool/gopool.go#L46) - ）控制的，修改方式也很简单，调用 gopool 提供的函数即可：`gopool.SetCap(xxx)`(main.go 中调用一次即可)。 - ## Client Client 侧的配置项均在初始化 Client 时采用 `client.xxx` 的方式 @@ -87,17 +81,17 @@ func main() { | 配置名称 | 类型 | 说明 | | :-------------------------------- | :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------ | | WithDialTimeout | time.Duration | 连接建立超时时间，默认 1s | -| WithMaxConnsPerHost | int | 设置为每个 host 建立的最大连接数，默认 512 | +| WithMaxConnsPerHost | int | 设置为每个 host 建立的最大连接数，默认 0（<=0 表示不限制）。 | | WithMaxIdleConnDuration | time.Duration | 设置空闲连接超时时间，当超时后会关闭该连接，默认 10s | -| WithMaxConnDuration | time.Duration | 设置连接存活的最大时长，超过这个时间的连接在完成当前请求后会被关闭，默认无限长 | +| WithMaxConnDuration | time.Duration | 设置连接存活的最大时长，超过这个时间的连接在完成当前请求后会被关闭，默认 0（不限制） | | WithMaxConnWaitTimeout | time.Duration | 设置等待空闲连接的最大时间，默认不等待 | | WithKeepAlive | bool | 是否使用长连接，默认开启 | -| WithRetryConfig | ...retry.Option | 设置 client 的 retry config。Hertz 版本需 >= v0.4.0 | +| WithRetryConfig | ...retry.Option | 设置 client 的 retry config。Hertz 版本需 >= v0.4.0。默认不启用 retry；调用 `WithRetryConfig()` 后默认 `MaxAttemptTimes=1`（即不重试），如需重试请显式设置，如：`client.WithRetryConfig(retry.WithMaxAttemptTimes(3))` | | ~~WithMaxIdempotentCallAttempts~~ | int | 设置最大调用次数，调用失败则会重试。默认 1 次即不重试。v0.4.0 版本废止，该版本之前可用，建议升级 Hertz 版本 >= v0.4.0 并使用 WithRetryConfig 替代 | -| WithClientReadTimeout | time.Duration | 设置读取 response 的最长时间，默认无限长 | +| WithClientReadTimeout | time.Duration | 设置读取 response 的最长时间，默认 0（不限制）。生产环境建议显式设置合理的超时时间 | | WithTLSConfig | \*tls.Config | 双向 TLS 认证时，设置 client 的 TLS config | -| WithDialer | network.Dialer | 设置 client 使用的网络库，默认 netpoll | +| WithDialer | network.Dialer | 设置 client 使用的网络库。默认值受平台与环境变量影响：在 linux/darwin && amd64/arm64 平台且未设置 `HERTZ_NO_NETPOLL=true` 时默认为 netpoll；TLS 场景会回退至 standard；其他情况为 standard。 | | WithResponseBodyStream | bool | 设置是否使用流式处理，默认关闭 | | WithDialFunc | client.DialFunc | 设置 Dial Function | -| WithWriteTimeout | time.Duration | 写入数据超时时间，默认值：无限长 | +| WithWriteTimeout | time.Duration | 写入数据超时时间，默认 0（不限制）。 | | WithHostClientConfigHook | func(hc interface{}) error | 设置 hook 函数来重新配置 host client，传入的 func 需要将参数 hc 断言为需要的结构体，比如 http1.HostClient，再进行具体处理 | diff --git a/content/zh/docs/hertz/reference/version.md b/content/zh/docs/hertz/reference/version.md index fd66ca9737d..cb85d5fd175 100644 --- a/content/zh/docs/hertz/reference/version.md +++ b/content/zh/docs/hertz/reference/version.md @@ -8,6 +8,12 @@ description: "Hertz 版本说明。" Hertz 遵从 [语义化版本 2.0.0](https://semver.org/lang/zh-CN/) 发布版本。 +**当前版本：[![Release](https://img.shields.io/github/v/release/cloudwego/hertz)](https://github.com/cloudwego/hertz/releases)** + - 主版本号：Hertz 提供的 API 出现不兼容的情况时，升级该版本号 - 次版本号：Hertz 提供新的功能特性同时保持向下兼容时，升级该版本号 - 修订号：Hertz 的代码提供小的特性或向下兼容的优化和问题修复时，升级该版本号 + +## Release Notes + +请参见 [GitHub Releases](https://github.com/cloudwego/hertz/releases)。 diff --git a/content/zh/docs/hertz/tutorials/basic-feature/adaptor.md b/content/zh/docs/hertz/tutorials/basic-feature/adaptor.md index d5307f41e14..430c80f45f7 100644 --- a/content/zh/docs/hertz/tutorials/basic-feature/adaptor.md +++ b/content/zh/docs/hertz/tutorials/basic-feature/adaptor.md @@ -61,14 +61,14 @@ func main() { | 函数 | 函数签名 | 介绍 | | ------------------ | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| GetCompatRequest | `func GetCompatRequest(req *protocol.Request) (*http.Request, error)` | 通过 Hertz `protocol.Request` 构建并获取 Go 标准库 `http.Request` | +| ~~GetCompatRequest~~ | `func GetCompatRequest(req *protocol.Request) (*http.Request, error)` | **已弃用：请使用 [`adaptor.HertzHandler`](./http-adaptor.md) 代替**。通过 Hertz `protocol.Request` 构建并获取 Go 标准库 `http.Request` | | CopyToHertzRequest | `func CopyToHertzRequest(req *http.Request, hreq *protocol.Request)` | 拷贝 Go 标准库 `http.Request` 的 `URI`，`Host`，`Method`，`Protocol`，`Header` 到 Hertz `protocol.Request`，对于 `Body` 属性会以共享 `Reader` 的方式进行适配 | ## http.ResponseWriter | 函数 / 结构体 | 函数签名 | 介绍 | | ----------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | -| GetCompatResponseWriter | `func GetCompatResponseWriter(resp *protocol.Response) http.ResponseWriter` | 通过 Hertz `protocol.Response` 构建并获取 Go 标准库 `http.ResponseWriter` | +| ~~GetCompatResponseWriter~~ | `func GetCompatResponseWriter(resp *protocol.Response) http.ResponseWriter` | **已弃用：请使用 [`adaptor.HertzHandler`](./http-adaptor.md) 代替**。通过 Hertz `protocol.Response` 构建并获取 Go 标准库 `http.ResponseWriter` | | compatResponse | / | `compatResponse` 结构体实现了 `http.ResponseWriter` 接口并对 `Header`，`Write`，`WriteHeader` 函数进行了适配 | ## Handler diff --git a/content/zh/docs/hertz/tutorials/basic-feature/client.md b/content/zh/docs/hertz/tutorials/basic-feature/client.md index 75bfc0a7532..826439ada9e 100644 --- a/content/zh/docs/hertz/tutorials/basic-feature/client.md +++ b/content/zh/docs/hertz/tutorials/basic-feature/client.md @@ -48,21 +48,21 @@ func main() { | 配置项 | 默认值 | 描述 | | --------------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------- | | WithDialTimeout | 1s | 拨号超时时间 | -| WithMaxConnsPerHost | 512 | 每个主机可能建立的最大连接数 | +| WithMaxConnsPerHost | 0 | 每个主机可能建立的最大连接数，默认 0 表示不限制 | | WithMaxIdleConnDuration | 10s | 最大的空闲连接持续时间，空闲的连接在此持续时间后被关闭 | | WithMaxConnDuration | 0s | 最大的连接持续时间，keep-alive 连接在此持续时间后被关闭 | | WithMaxConnWaitTimeout | 0s | 等待空闲连接的最大时间 | | WithKeepAlive | true | 是否使用 keep-alive 连接，默认使用 | -| WithClientReadTimeout | 0s | 完整读取响应（包括 body）的最大持续时间 | +| WithClientReadTimeout | 0s | 完整读取响应（包括 body）的最大持续时间，默认 0 表示不限制 | | WithTLSConfig | nil | 设置用于创建 tls 连接的 tlsConfig，具体配置信息请看 [tls](/zh/docs/hertz/tutorials/basic-feature/tls/) | -| WithDialer | network.Dialer | 设置指定的拨号器 | +| WithDialer | network.Dialer | 设置指定的拨号器，默认值受平台影响：linux/darwin && amd64/arm64 且未设置 `HERTZ_NO_NETPOLL=true` 时默认为 netpoll；TLS 场景回退至 standard；其他情况为 standard | | WithResponseBodyStream | false | 是否在流中读取 body，默认不在流中读取 | | WithDisableHeaderNamesNormalizing | false | 是否禁用头名称规范化，默认不禁用，如 cONTENT-lenGTH -> Content-Length | | WithName | "" | 设置用户代理头中使用的客户端名称 | | WithNoDefaultUserAgentHeader | false | 设置是否应该在请求中包含默认的 User-Agent 头，默认包含 User-Agent 头 | | WithDisablePathNormalizing | false | 是否禁用路径规范化，默认规范路径，如 http://localhost:8080/hello/../ hello -> http://localhost:8080/hello | -| WithRetryConfig | nil | HTTP 客户端的重试配置，重试配置详细说明请看 [重试](/zh/docs/hertz/tutorials/basic-feature/retry/) | -| WithWriteTimeout | 0s | HTTP 客户端的写入超时时间 | +| WithRetryConfig | nil | HTTP 客户端的重试配置，默认不启用重试；调用后默认 `MaxAttemptTimes=1`（即不重试），如需重试请显式设置。详细说明请看 [重试](/zh/docs/hertz/tutorials/basic-feature/retry/) | +| WithWriteTimeout | 0s | HTTP 客户端的写入超时时间，默认 0 表示不限制。仅当值 >0 时才会在 netpoll transport 中启用超时机制 | | WithConnStateObserve | nil, 5s | 设置观察和记录 HTTP 客户端的连接状态的函数以及观察执行间隔 | | WithDialFunc | network.Dialer | 设置 HTTP 客户端拨号器函数，会覆盖自定义拨号器 | | WithHostClientConfigHook | nil | 设置 hook 函数来重新配置 host client | diff --git a/content/zh/docs/hertz/tutorials/basic-feature/engine.md b/content/zh/docs/hertz/tutorials/basic-feature/engine.md index ba42d392c96..d621fd15653 100644 --- a/content/zh/docs/hertz/tutorials/basic-feature/engine.md +++ b/content/zh/docs/hertz/tutorials/basic-feature/engine.md @@ -21,12 +21,12 @@ type Hertz struct { | 配置项 | 默认值 | 说明 | | :-------------------------------- | :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| WithTransport | network.NewTransporter | 更换底层 transport | +| WithTransport | 受平台影响 | 更换底层 transport。默认值受平台与环境变量影响（可参见 [网络库](/zh/docs/hertz/tutorials/basic-feature/network-lib/)） | | WithHostPorts | `:8888` | 指定监听的地址和端口 | | WithKeepAliveTimeout | 1min | tcp 长连接保活时间，一般情况下不用修改，更应该关注 idleTimeout | | WithReadTimeout | 3min | 底层读取数据超时时间 | | WithIdleTimeout | 3min | 长连接请求链接空闲超时时间 | -| WithMaxRequestBodySize | 4 _ 1024 _ 1024 | 配置最大的请求体大小 | +| WithMaxRequestBodySize | `4 * 1024 * 1024` (4MB) | 配置最大的请求体大小 | | WithRedirectTrailingSlash | true | 自动根据末尾的 / 转发，例如：如果 router 只有 /foo/，那么 /foo 会重定向到 /foo/ ；如果只有 /foo，那么 /foo/ 会重定向到 /foo | | WithRemoveExtraSlash | false | RemoveExtraSlash 当有额外的 / 时也可以当作参数。如：user/:name，如果开启该选项 user//xiaoming 也可匹配上参数 | | WithUnescapePathValues | true | 如果开启，请求路径会被自动转义（eg. '%2F' -> '/'）。如果 UseRawPath 为 false（默认情况），则 UnescapePathValues 实际上为 true，因为 .URI().Path() 将被使用，它已经是转义后的。设置该参数为 false，需要配合 WithUseRawPath(true) | @@ -41,15 +41,16 @@ type Hertz struct { | WithALPN | false | 是否开启 ALPN | | WithTracer | []interface{}{} | 注入 tracer 实现，如不注入 Tracer 实现，默认关闭 | | WithTraceLevel | LevelDetailed | 设置 trace level | -| WithWriteTimeout | 无限长 | 写入数据超时时间 | +| WithWriteTimeout | 0（不限制） | 写入数据超时时间。仅当值 >0 时才会在 netpoll transport 中启用超时机制 | | WithRedirectFixedPath | false | 如果开启，当当前请求路径不能匹配上时，server 会尝试修复请求路径并重新进行匹配，如果成功匹配并且为 GET 请求则会返回状态码 301 进行重定向，其他请求方式返回 308 进行重定向 | | WithBasePath | `/` | 设置基本路径，前缀和后缀必须为 `/` | -| WithMaxKeepBodySize | 4 _ 1024 _ 1024 | 设置回收时保留的请求体和响应体的最大大小。单位：字节 | +| WithMaxKeepBodySize | `4 * 1024 * 1024` (4MB) | 设置回收时保留的请求体和响应体的最大大小。单位：字节 | | WithGetOnly | false | 如果开启则只接受 GET 请求 | | WithKeepAlive | true | 如果开启则使用 HTTP 长连接 | -| WithAltTransport | network.NewTransporter | 设置备用 transport | +| WithAltTransport | nil | 设置备用 transport。该配置仅作为扩展点，如需使用请显式设置。 | | WithH2C | false | 设置是否开启 H2C | | WithReadBufferSize | 4 \* 1024 | 设置读缓冲区大小 | +| WithMaxHeaderBytes | 1MB（1 << 20） | 设置 HTTP 请求 header 的最大字节数，超限返回 431 Request Header Fields Too Large | | WithRegistry | registry.NoopRegistry, nil | 设置注册中心配置，服务注册信息 | | WithAutoReloadRender | false, 0 | 设置自动重载渲染配置 | | WithDisablePrintRoute | false | 设置是否禁用 debugPrintRoute | @@ -57,13 +58,6 @@ type Hertz struct { | WithOnConnect | nil | 设置 onConnect 函数。它可以接收来自 netpoll 连接的数据。在 go net 中，它将在转换 TLS 连接后被调用 | | WithDisableHeaderNamesNormalizing | false | 设置是否禁用 Request 和 Response Header 名字的规范化 (首字母和破折号后第一个字母大写) | -Server Connection 数量限制: - -- 如果是使用标准网络库，无此限制 -- 如果是使用 netpoll，最大连接数为 10000 - （这个是 netpoll 底层使用的 [gopool](https://github.com/bytedance/gopkg/blob/b9c1c36b51a6837cef4c2223e11522e3a647460c/util/gopool/gopool.go#L46) - ）控制的，修改方式也很简单，调用 gopool 提供的函数即可：`gopool.SetCap(xxx)`(main.go 中调用一次即可)。 - Server 侧的配置项均在初始化 Server 时采用 `server.WithXXX` 的方式，如： ```go diff --git a/content/zh/docs/hertz/tutorials/basic-feature/network-lib.md b/content/zh/docs/hertz/tutorials/basic-feature/network-lib.md index 0d74a5a23b4..0199d3eec91 100644 --- a/content/zh/docs/hertz/tutorials/basic-feature/network-lib.md +++ b/content/zh/docs/hertz/tutorials/basic-feature/network-lib.md @@ -8,16 +8,16 @@ description: "Hertz 默认集成了 Netpoll 和 Golang 原生网络库两个网 ## 使用方式 -对于 Server 来说，默认使用 netpoll，可以通过配置项进行更改： +对于 Server 来说，默认使用 netpoll，可以通过配置项进行更改，也可以通过设置 `HERTZ_NO_NETPOLL=true` 来禁用 netpoll： -> 注意：netpoll 目前不支持 Windows，Windows 会通过条件编译将网络库自动切换为 go net。 +> 注意：netpoll 仅支持 linux/darwin && amd64/arm64 平台，目前不支持 Windows，Windows 会通过条件编译将网络库自动切换为 go net。此外，TLS 场景会回退到标准网络库。 ```go server.New(server.WithTransport(standard.NewTransporter)) server.New(server.WithTransport(netpoll.NewTransporter)) ``` -对于 Client 来说，可以通过配置项进行更改： +对于 Client 来说，可以通过配置项进行更改（也可以通过设置 `HERTZ_NO_NETPOLL=true` 来禁用 netpoll）： ```go client.NewClient(client.WithDialer(standard.NewDialer())) diff --git a/content/zh/docs/hertz/tutorials/toolkit/command.md b/content/zh/docs/hertz/tutorials/toolkit/command.md index cfe5000ab0e..b3d4de9aeb4 100644 --- a/content/zh/docs/hertz/tutorials/toolkit/command.md +++ b/content/zh/docs/hertz/tutorials/toolkit/command.md @@ -72,14 +72,16 @@ OPTIONS: --thriftgo value, -t value [ --thriftgo value, -t value ] Specify arguments for the thriftgo. ({flag}={value}) --protoc value, -p value [ --protoc value, -p value ] Specify arguments for the protoc. ({flag}={value}) --option_package value, -P value [ --option_package value, -P value ] Specify the package path. ({include_path}={import_path}) + --trim_gopackage value, --trim_pkg value Trim the prefix of go_package for protobuf. --no_recurse Generate master model only. (default: false) --force, -f Force new a project, which will overwrite the generated files (default: false) --enable_extends Parse 'extends' for thrift IDL (default: false) + --sort_router Sort router register code, to avoid code difference (default: false) --json_enumstr Use string instead of num for json enums when idl is thrift. (default: false) --unset_omitempty Remove 'omitempty' tag for generated struct. (default: false) --pb_camel_json_tag Convert Name style for json tag to camel(Only works protobuf). (default: false) --snake_tag Use snake_case style naming for tags. (Only works for 'form', 'query', 'json') (default: false) - --rm_tag value [ --rm_tag value ] Remove the specified tag + --rm_tag value [ --rm_tag value ] Remove the default tag(json/query/form). If the annotation tag is set explicitly, it will not be removed. --exclude_file value, -E value [ --exclude_file value, -E value ] Specify the files that do not need to be updated. --customize_layout value Specify the path for layout template. --customize_layout_data_path value Specify the path for layout template render data. @@ -142,6 +144,10 @@ OPTIONS: +- trim_gopackage/trim_pkg: 修剪 protobuf 的 go_package 前缀 + + + - no_recurse: 只生成主 idl 的 model 代码，默认为 false @@ -154,6 +160,10 @@ OPTIONS: +- sort_router: 对路由注册代码进行排序，避免代码差异 + + + - json_enumstr: 当 idl 为 thrift 时，json enums 使用 string 代替 num (透传给 thriftgo 的选项) @@ -170,7 +180,7 @@ OPTIONS: -- rm_tag value: 移除指定的 tag +- rm_tag value: 移除默认 tag(json/query/form)。如果显式设置了注解 tag，则不会被移除 @@ -226,13 +236,15 @@ OPTIONS: --thriftgo value, -t value [ --thriftgo value, -t value ] Specify arguments for the thriftgo. ({flag}={value}) --protoc value, -p value [ --protoc value, -p value ] Specify arguments for the protoc. ({flag}={value}) --option_package value, -P value [ --option_package value, -P value ] Specify the package path. ({include_path}={import_path}) + --trim_gopackage value, --trim_pkg value Trim the prefix of go_package for protobuf. --no_recurse Generate master model only. (default: false) --enable_extends Parse 'extends' for thrift IDL (default: false) + --sort_router Sort router register code, to avoid code difference (default: false) --json_enumstr Use string instead of num for json enums when idl is thrift. (default: false) --unset_omitempty Remove 'omitempty' tag for generated struct. (default: false) --pb_camel_json_tag Convert Name style for json tag to camel(Only works protobuf). (default: false) --snake_tag Use snake_case style naming for tags. (Only works for 'form', 'query', 'json') (default: false) - --rm_tag value [ --rm_tag value ] Remove the specified tag + --rm_tag value [ --rm_tag value ] Remove the default tag(json/query/form). If the annotation tag is set explicitly, it will not be removed. --exclude_file value, -E value [ --exclude_file value, -E value ] Specify the files that do not need to be updated. --customize_package value Specify the path for package template. --handler_by_method Generate a separate handler file for each method. (default: false) @@ -285,6 +297,10 @@ OPTIONS: +- trim_gopackage/trim_pkg: 修剪 protobuf 的 go_package 前缀 + + + - no_recurse: 只生成主 idl 的 model 代码，默认为 false @@ -293,11 +309,15 @@ OPTIONS: +- sort_router: 对路由注册代码进行排序，避免代码差异 + + + - json_enumstr: 当 idl 为 thrift 时，json enums 使用 string 代替 num (透传给 thriftgo 的选项) -- unset_omitempty: 当 idl 为 protobuf 时，生成 model field，去掉 mitempty tag；当 idl 为 thrift 时，是否添加 omitempty 根据 field 是 "optional" 还是 "required" 决定 +- unset_omitempty: 当 idl 为 protobuf 时，生成 model field，去掉 omitempty tag；当 idl 为 thrift 时，是否添加 omitempty 根据 field 是 "optional" 还是 "required" 决定 @@ -309,7 +329,7 @@ OPTIONS: -- rm_tag value: 移除指定的 tag +- rm_tag value: 移除默认 tag(json/query/form)。如果显式设置了注解 tag，则不会被移除 @@ -354,11 +374,12 @@ OPTIONS: --thriftgo value, -t value [ --thriftgo value, -t value ] Specify arguments for the thriftgo. ({flag}={value}) --protoc value, -p value [ --protoc value, -p value ] Specify arguments for the protoc. ({flag}={value}) --no_recurse Generate master model only. (default: false) + --trim_gopackage value, --trim_pkg value Trim the prefix of go_package for protobuf. --json_enumstr Use string instead of num for json enums when idl is thrift. (default: false) --unset_omitempty Remove 'omitempty' tag for generated struct. (default: false) --pb_camel_json_tag Convert Name style for json tag to camel(Only works protobuf). (default: false) --snake_tag Use snake_case style naming for tags. (Only works for 'form', 'query', 'json') (default: false) - --rm_tag value [ --rm_tag value ] Remove the specified tag + --rm_tag value [ --rm_tag value ] Remove the default tag(json/query/form). If the annotation tag is set explicitly, it will not be removed. --exclude_file value, -E value [ --exclude_file value, -E value ] Specify the files that do not need to be updated. --help, -h show help (default: false) ``` @@ -395,11 +416,15 @@ OPTIONS: +- trim_gopackage/trim_pkg: 修剪 protobuf 的 go_package 前缀 + + + - json_enumstr: 当 idl 为 thrift 时，json enums 使用 string 代替 num (透传给 thriftgo 的选项) -- unset_omitempty: 当 idl 为 protobuf 时，生成 model field，去掉 mitempty tag；当 idl 为 thrift 时，是否添加 omitempty 根据 field 是 "optional" 还是 "required" 决定 +- unset_omitempty: 当 idl 为 protobuf 时，生成 model field，去掉 omitempty tag；当 idl 为 thrift 时，是否添加 omitempty 根据 field 是 "optional" 还是 "required" 决定 @@ -411,7 +436,7 @@ OPTIONS: -- rm_tag value: 移除指定的 tag +- rm_tag value: 移除默认 tag(json/query/form)。如果显式设置了注解 tag，则不会被移除 @@ -441,16 +466,20 @@ OPTIONS: --client_dir value Specify the client path. If not specified, IDL generated path is used for 'client' command; no client code is generated for 'new' command --use value Specify the model package to import for handler. --force_client_dir value Specify the client path, and won't use namespaces as subpaths + --force_client Force update 'hertz_client.go' (default: false) --proto_path value, -I value [ --proto_path value, -I value ] Add an IDL search path for includes. (Valid only if idl is protobuf) --thriftgo value, -t value [ --thriftgo value, -t value ] Specify arguments for the thriftgo. ({flag}={value}) --protoc value, -p value [ --protoc value, -p value ] Specify arguments for the protoc. ({flag}={value}) --no_recurse Generate master model only. (default: false) --enable_extends Parse 'extends' for thrift IDL (default: false) + --trim_gopackage value, --trim_pkg value Trim the prefix of go_package for protobuf. --json_enumstr Use string instead of num for json enums when idl is thrift. (default: false) + --enable_optional Optional field do not transfer for thrift if not set.(Only works for query tag) (default: false) + --query_enumint Use num instead of string for query enum parameter. (default: false) --unset_omitempty Remove 'omitempty' tag for generated struct. (default: false) --pb_camel_json_tag Convert Name style for json tag to camel(Only works protobuf). (default: false) --snake_tag Use snake_case style naming for tags. (Only works for 'form', 'query', 'json') (default: false) - --rm_tag value [ --rm_tag value ] Remove the specified tag + --rm_tag value [ --rm_tag value ] Remove the default tag(json/query/form). If the annotation tag is set explicitly, it will not be removed. --exclude_file value, -E value [ --exclude_file value, -E value ] Specify the files that do not need to be updated. --customize_package value Specify the path for package template. --protoc-plugins value [ --protoc-plugins value ] Specify plugins for the protoc. ({plugin_name}:{options}:{out_dir}) @@ -486,6 +515,10 @@ OPTIONS: +- force_client: 强制更新 'hertz_client.go' + + + - proto_path/I: 当 idl 为 protobuf 时，指定 idl 的搜索路径，同 protoc 的 -I 指令 @@ -506,10 +539,22 @@ OPTIONS: +- trim_gopackage/trim_pkg: 修剪 protobuf 的 go_package 前缀 + + + - json_enumstr: 当 idl 为 thrift 时，json enums 使用 string 代替 num (透传给 thriftgo 的选项) +- enable_optional: 当 thrift 字段未设置时，可选字段不传输（仅对 query tag 生效） + + + +- query_enumint: query 枚举参数使用数字而不是字符串 + + + - unset_omitempty: 当 idl 为 protobuf 时，生成 model field，去掉 omitempty tag；当 idl 为 thrift 时，是否添加 omitempty 根据 field 是 "optional" 还是 "required" 决定 @@ -522,7 +567,7 @@ OPTIONS: -- rm_tag value: 移除指定的 tag +- rm_tag value: 移除默认 tag(json/query/form)。如果显式设置了注解 tag，则不会被移除