配置说明

Hertz 配置说明。

Server

Server 侧的配置项均在初始化 Server 时采用 server.xxx 的方式,如

package main

import "github.com/cloudwego/hertz/pkg/app/server"

func main() {
	h := server.New(server.WithXXXX())
	...
}
配置名称类型说明
WithTransportnetwork.NewTransporter更换底层 transport,默认值:netpoll.NewTransporter
WithHostPortsstring指定监听的地址和端口
WithKeepAliveTimeouttime.Durationtcp 长连接保活时间,一般情况下不用修改,更应该关注 idleTimeout。默认值:1min
WithReadTimeouttime.Duration底层读取数据超时时间。默认值:3min
WithIdleTimeouttime.Duration长连接请求链接空闲超时时间。默认值:3min
WithMaxRequestBodySizeint配置最大的请求体大小,默认 4M(4M 对应的填的值是 4*1024*1024)
WithRedirectTrailingSlashbool自动根据末尾的 / 转发,例如:如果 router 只有 /foo/,那么 /foo 会重定向到 /foo/ ;如果只有 /foo,那么 /foo/ 会重定向到 /foo。默认开启
WithRemoveExtraSlashboolRemoveExtraSlash 当有额外的 / 时也可以当作参数。如:user/:name,如果开启该选项 user//xiaoming 也可匹配上参数。默认关闭
WithUnescapePathValuesbool如果开启,请求路径会被自动转义(eg. ‘%2F’ -> ‘/’)。如果 UseRawPath 为 false(默认情况),则 UnescapePathValues 实际上为 true,因为 .URI().Path() 将被使用,它已经是转义后的。设置该参数为 false,需要配合 WithUseRawPath(true)。默认开启 (true)
WithUseRawPathbool如果开启,会使用原始 path 进行路由匹配。默认关闭
WithHandleMethodNotAllowedbool如果开启,当当前路径不能被匹配上时,server 会去检查其他方法是否注册了当前路径的路由,如果存在则会响应"Method Not Allowed",并返回状态码 405; 如果没有,则会用 NotFound 的 handler 进行处理。默认关闭
WithDisablePreParseMultipartFormbool如果开启,则不会预处理 multipart form。可以通过 ctx.Request.Body() 获取到 body 后由用户处理。默认关闭
WithStreamBodybool如果开启,则会使用流式处理 body。默认关闭
WithNetworkstring设置网络协议,可选:tcp,udp,unix(unix domain socket),默认为 tcp
ContinueHandlerfunc(header *RequestHeader) bool在接收到 Expect 100 Continue 头之后调用 ContinueHandler。使用 ContinueHandler,服务器可以决定是否根据标头读取可能很大的请求正文
PanicHandlerHandlerFunc处理 panic,用来生成错误页面并返回 500
NotFoundHandlerFunc当路由匹配不上时被调用的 handler
WithExitWaitTimetime.Duration设置优雅退出时间。Server 会停止建立新的连接,并对关闭后的每一个请求设置 Connection: Close 的 header,当到达设定的时间关闭 Server。当所有连接已经关闭时,Server 可以提前关闭。默认 5s
WithTLStls.Config配置 server tls 能力
WithListenConfignet.ListenConfig设置监听器配置,可用于设置是否允许 reuse port 等
WithALPNbool是否开启 ALPN。默认关闭
WithTracertracer.Tracer注入 tracer 实现,如不注入 Tracer 实现,默认关闭
WithTraceLevelstats.Level设置 trace level,默认 LevelDetailed
WithWriteTimeouttime.Duration写入数据超时时间,默认值:无限长
WithRedirectFixedPathbool如果开启,当当前请求路径不能匹配上时,server 会尝试修复请求路径并重新进行匹配,如果成功匹配并且为 GET 请求则会返回状态码 301 进行重定向,其他请求方式返回 308 进行重定向。默认关闭
WithBasePathstring设置基本路径,前缀和后缀必须为 /。默认为 /
WithMaxKeepBodySizeint设置回收时保留的请求体和响应体的最大大小。单位:字节。默认值:4 _ 1024 _ 1024
WithGetOnlybool如果开启则只接受 GET 请求。默认关闭
WithKeepAlivebool如果开启则使用 HTTP 长连接。默认开启
WithAltTransportnetwork.NewTransporter设置备用 transport。默认值:netpoll.NewTransporter
WithH2Cbool设置是否开启 H2C。默认关闭
WithReadBufferSizeint设置读缓冲区大小,同时限制 HTTP header 大小。默认值:4 * 1024
WithRegistryregistry.Registry, *registry.Info设置注册中心配置,服务注册信息。默认值:registry.NoopRegistry, nil
WithAutoReloadRenderbool, time.Duration设置自动重载渲染配置。默认值:false, 0
WithDisablePrintRoutebool设置是否禁用 debugPrintRoute。默认不禁用
WithOnAcceptfunc(conn net.Conn) context.Context设置在 netpoll 中当一个连接被接受但不能接收数据时的回调函数,在 go net 中在转换 TLS 连接之前被调用。默认值:nil
WithOnConnectfunc(ctx context.Context, conn network.Conn) context.Context设置 onConnect 函数。它可以接收来自 netpoll 连接的数据。在 go net 中,它将在转换 TLS 连接后被调用。默认值:nil
WithDisableHeaderNamesNormalizingbool设置是否禁用 Request 和 Response Header 名字的规范化 (首字母和破折号后第一个字母大写)

Server Connection 数量限制:

  • 如果是使用标准网络库,无此限制
  • 如果是使用 netpoll,最大连接数为 10000 (这个是 netpoll 底层使用的 gopool )控制的,修改方式也很简单,调用 gopool 提供的函数即可:gopool.SetCap(xxx)(main.go 中调用一次即可)。

Client

Client 侧的配置项均在初始化 Client 时采用 client.xxx 的方式

package main

import "github.com/cloudwego/hertz/pkg/app/client"

func main() {
	c, err := client.NewClient(client.WithXxx())
	...
}
配置名称类型说明
WithDialTimeouttime.Duration连接建立超时时间,默认 1s
WithMaxConnsPerHostint设置为每个 host 建立的最大连接数,默认 512
WithMaxIdleConnDurationtime.Duration设置空闲连接超时时间,当超时后会关闭该连接,默认 10s
WithMaxConnDurationtime.Duration设置连接存活的最大时长,超过这个时间的连接在完成当前请求后会被关闭,默认无限长
WithMaxConnWaitTimeouttime.Duration设置等待空闲连接的最大时间,默认不等待
WithKeepAlivebool是否使用长连接,默认开启
WithRetryConfig…retry.Option设置 client 的 retry config。Hertz 版本需 >= v0.4.0
WithMaxIdempotentCallAttemptsint设置最大调用次数,调用失败则会重试。默认 1 次即不重试。v0.4.0 版本废止,该版本之前可用,建议升级 Hertz 版本 >= v0.4.0 并使用 WithRetryConfig 替代
WithClientReadTimeouttime.Duration设置读取 response 的最长时间,默认无限长
WithTLSConfig*tls.Config双向 TLS 认证时,设置 client 的 TLS config
WithDialernetwork.Dialer设置 client 使用的网络库,默认 netpoll
WithResponseBodyStreambool设置是否使用流式处理,默认关闭
WithDialFuncclient.DialFunc设置 Dial Function
WithWriteTimeouttime.Duration写入数据超时时间,默认值:无限长
WithHostClientConfigHookfunc(hc interface{}) error设置 hook 函数来重新配置 host client,传入的 func 需要将参数 hc 断言为需要的结构体,比如 http1.HostClient,再进行具体处理

最后修改 December 9, 2024 : Update prerequisite.md (#1178) (b5e2299)