contrib

func AutoTlsNewServerWithCustomManager ¶

func AutoTlsNewServerWithCustomManager(m *autocert.Manager, tlsc *tls.Config, opts ...config.Option) *server.Hertz

AutoTlsNewServerWithCustomManager 给业务完全控制权(自定义 autocert.Manager 用自己的证书缓存目录 / DNS-01 校验)。ekit 业务 99% 用 NewTlsConfig 即可, 这个函数给 ekit 业务做"复杂 TLS 编排"留口子(类似 ekit P4 大依赖模式)。

用法:

m := &autocert.Manager{
    Prompt:     autocert.AcceptTOS,
    HostPolicy: autocert.HostWhitelist("example.com"),
    Cache:      autocert.DirCache("/var/www/.cache"),
}
h := contrib.AutoTlsNewServerWithCustomManager(m, nil)
hlog.Fatal(contrib.AutoTlsRun(h))

func AutoTlsNewTlsConfig ¶

func AutoTlsNewTlsConfig(domains ...string) *tls.Config

AutoTlsNewTlsConfig 透传 hertz-contrib/autotls.NewTlsConfig,构造 Let's Encrypt 托管的 TLS 配置(domains 是白名单,如 "example.com")。

官方依据:https://github.com/hertz-contrib/autotls (v0.0.1) + hertz 官方 TLS 教程。

用法:

h := server.New(
    server.WithTLS(contrib.AutoTlsNewTlsConfig("example.com", "www.example.com")),
    server.WithHostPorts(":https"),
)
hlog.Fatal(contrib.AutoTlsRun(h))

func AutoTlsRun ¶

func AutoTlsRun(h *server.Hertz) error

AutoTlsRun 透传 hertz-contrib/autotls.Run,启动 HTTPS server(阻塞)。 业务应该用 WithShutdown 替代:支持 ctx 取消触发 graceful shutdown。

func AutoTlsRunWithShutdown ¶

func AutoTlsRunWithShutdown(ctx context.Context, h *server.Hertz) error

AutoTlsRunWithShutdown 是 AutoTlsRun 的 ctx 包装:ctx 取消时自动 关闭 server,适合配合 ekit bootstrap 生命周期管理。

官方依据:hertz-contrib/autotls.RunWithContext 文档 (https://github.com/hertz-contrib/autotls README)

用法:

ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
defer stop()
hlog.Fatal(contrib.AutoTlsRunWithShutdown(ctx, h))

func BasicAuth ¶

func BasicAuth(accounts Accounts) app.HandlerFunc

BasicAuth 透传 hertz 框架内置 HTTP Basic Auth 中间件,ekit 业务 1 行挂载,无需记 hertz 长 import 路径。

官方依据:https://github.com/cloudwego/hertz README [Extensions] 段 (hertz-contrib 23 个三方中间件中 basicauth 列在 hertz 框架内置, github.com/cloudwego/hertz/tree/main/pkg/app/middlewares/server/basic_auth)。

用法:

h.Use(contrib.BasicAuth(mw.Accounts{
    "alice": "secret",
    "admin": "stronger",
}))

注意:HTTP Basic Auth 每次请求都带 Authorization 头,密码是 base64 编码(不是 hash),**仅适用于 HTTPS 部署**,公网 HTTP 会泄露明文。 生产推荐:用 HTTPS + TLS termination at gateway,或改用 JWT(BearerAuth)。

func BasicAuthForRealm ¶

func BasicAuthForRealm(accounts Accounts, realm, userKey string) app.HandlerFunc

BasicAuthForRealm 透传 hertz 框架内置 BasicAuthForRealm,支持自定义 realm(浏览器弹窗显示)和 userKey(从 Authorization 头提取用户名的 方式,默认 "Authorization")。

用法:

h.Use(contrib.BasicAuthForRealm(accounts, "MyService", "X-API-User"))

func CSRFMiddleware ¶

func CSRFMiddleware(opts ...CSRFOption) app.HandlerFunc

CSRFMiddleware 返回 CSRF 防护中间件。

基于 hertz-contrib/csrf。校验请求携带的 CSRF token 是否与服务端签发的匹配， 不匹配则拒绝。用于防御跨站请求伪造，保护状态变更类接口（POST/PUT/DELETE）。

客户端流程:

1. GET 一个受保护页面/接口，响应会种下 CSRF cookie + 可通过 csrf.GetToken 读取 token
2. 后续 POST 请求在指定位置（默认 header X-CSRF-Token）携带 token

前置条件: 必须先注册 sessions 中间件（hertz-contrib/sessions）， 否则每个请求都会 panic（底层 csrf 依赖 sessions.Default(c)）。 Secret 不能为空。

用法:

h.Use(contrib.CSRFMiddleware(mw.WithCSRFSecret("your-32-byte-random-secret")))

在 handler 中读取 token 透传给前端:

token := csrf.GetToken(c)

func Cache ¶

func Cache(opts ...CacheOption) app.HandlerFunc

Cache 返回 hertz HTTP 缓存中间件,默认按 RequestURI 作 key、60s 过期、 内存存储(进程级,重启失效)。Redis 等分布式场景用 WithCacheStore 注入。

⚠️ 默认只缓存 GET(2026-09-05 复审修复):上游 hertz-contrib/cache 的 NewCacheByRequestURI strategy 恒返回 true 不分方法,全局挂载时 POST/ PUT/DELETE 的 2xx 响应也会被缓存重放。ekit 包装层默认对非 GET 请求直接 放行不缓存,对齐本注释一贯宣称的"GET 缓存"语义;业务通过 WithCacheStrategyByRequest 显式接管缓存判定时,方法过滤由业务负责。

业务使用:

// 简单 GET 缓存 1 分钟
h.Use(contrib.Cache())

// 自定义 5 分钟 + key 前缀
h.Use(contrib.Cache(
    mw.WithCacheExpiration(5*time.Minute),
    mw.WithCachePrefix("my-svc"),
))

// Redis 分布式缓存
h.Use(contrib.Cache(
    mw.WithCacheStore(persist.NewRedisStore(redisClient)),
    mw.WithCacheExpiration(10*time.Minute),
))

官方依据:https://www.cloudwego.io/zh/docs/hertz/tutorials/third-party/middleware/cache/ (上游 strategy 返回 false 时 c.Next(ctx) 直接放行 — 非 GET 走同一通道)

func DefaultCSP ¶

func DefaultCSP() string

DefaultCSP 返回 ekit 推荐的严格 Content-Security-Policy 策略。

安全响应头中间件已迁移到 hertz-contrib/secure，调用方按需启用：

import "github.com/hertz-contrib/secure"

h.Use(secure.New(
    secure.WithContentSecurityPolicy(contrib.DefaultCSP()),
    secure.WithFrameDeny(true),
    secure.WithContentTypeNosniff(true),
    secure.WithReferrerPolicy("no-referrer"),
    secure.WithSTSSeconds(31536000), // 可选 HSTS
))

策略说明:

• default-src/script-src/style-src: 仅限同源
• img-src: 同源 + data/blob（允许内联图片）
• connect-src: 同源 + ws/wss（WebSocket 调试与实时推送）
• frame-ancestors: 禁止任何嵌入（防点击劫持）

func ETagMiddleware ¶

func ETagMiddleware(opts ...etag.Option) app.HandlerFunc

ETagMiddleware 返回 ETag 条件请求中间件。

基于 hertz-contrib/etag。客户端首次请求获得响应体 + ETag 头； 后续请求携带 If-None-Match，若 ETag 未变则返回 304 Not Empty（不传响应体，节省带宽）。

透传 contrib 的 Option，常用项：

• etag.WithWeak() 使用弱 ETag（W/"..."），适用于可接受语义等价的场景

用法:

h.Use(contrib.ETagMiddleware())
// 或弱 ETag
h.Use(contrib.ETagMiddleware(etag.WithWeak()))

func GzipMiddleware ¶

func GzipMiddleware(level int, opts ...gzip.Option) app.HandlerFunc

GzipMiddleware 返回 gzip 响应压缩中间件。

基于 hertz-contrib/gzip，压缩等级通过 level 指定（gzip.DefaultCompression 使用默认）。 透传 contrib 的 Option，常用项：

• gzip.WithExcludedExtensions([]string{".pdf", ".mp4"}) 跳过二进制扩展名
• gzip.WithExcludedPaths([]string{"/metrics"}) 跳过指定路径
• gzip.WithDecompressFn(gzip.DefaultDecompressHandle) 同时解压请求体

注意: gzip 会劫持响应写入器，建议仅在确有压缩需求的路由组上注册，而非全局。

用法:

h.Use(contrib.GzipMiddleware(gzip.DefaultCompression))
// 或排除二进制文件
h.Use(contrib.GzipMiddleware(gzip.DefaultCompression,
    gzip.WithExcludedExtensions([]string{".pdf", ".mp4", ".png"}))

func JWTAuth ¶

func JWTAuth(opts ...JWTOption) app.HandlerFunc

JWTAuth 返回 hertz middleware 函数,验证请求 Authorization: Bearer {token}。 失败返回 401;成功把 claims 写入 ctx,hertz-contrib/jwt 内部用 c.Set("userID", ...)。

业务使用:

h.Use(contrib.JWTAuth(
    mw.WithJWTSecret([]byte("my-secret-key-at-least-32-bytes-long-for-HS256")),
    mw.WithJWTSkipPaths("/healthz", "/login"),
))

⚠️ fail-closed:构造失败(典型:漏传 WithJWTSecret)时返回的中间件会把 所有请求 500,而不是静默放行 — 认证中间件缺省方向必须是拒绝。补传 secret 后再次调用 JWTAuth 即恢复正常(构造可重试,无 once 毒化)。

⚠️ 与 BearerTokenAuth(静态 token)互补:JWT 用于签名 token 验证, BearerToken 用于简单预共享。两者可同时存在但通常只用一个。

官方依据:https://www.cloudwego.io/zh/docs/hertz/tutorials/third-party/middleware/jwt/ (Timeout "用于设置 token 过期时间,默认为一小时")

func JWTGenerateToken ¶

func JWTGenerateToken(claims jwt.MapClaims) (string, error)

JWTGenerateToken 用当前配置签发 token(HS256/384/512 共享密钥模式)。 业务在登录 handler 调:cli.POST("/login", JWTGenerateToken(MapClaims{"user_id": uid}))

exp/iat 自动注入:claims 未显式带 exp 时注入 exp=now+WithJWTTimeout(默认 1h), 未带 iat 时注入 now。hertz-contrib/jwt 中间件要求 token 必须带 exp (缺失返回 400 ErrMissingExpField),官方登录签发的 payload 默认包含 "token 的过期时间和创建时间"(2026-09-05 复审修复:原实现不注入 exp, 签发的 token 被自家中间件 400 拒绝)。

RSA 模式需自行实现(本 helper 不覆盖 — 业务可用 HertzJWTMiddleware.TokenGenerator)。

⚠️ **签发配置取自当前 runtime(即验签用的那个 instance)**,不是取自可变 opts。

两者若不同源,轮换 secret 后就会出现「自家签的 token 被自家中间件 401」。
⇒ 签发与验签读同一个对象 ⇒ 结构上不可能分裂。

func JWTParse ¶

func JWTParse(tokenString string) (jwt.MapClaims, error)

JWTParse 验证 token 字符串并返回 claims(业务手动验证用,如 WebSocket upgrade 前的预校验)。

func KeyAuth ¶

func KeyAuth(opts ...keyauth.Option) app.HandlerFunc

KeyAuth 返回 hertz API Key 认证中间件,桥接 hertz-contrib/keyauth。

业务必须提供 validator(无默认实现,因为 API key 验证逻辑业务特定)。

典型用法(简单 API key 验证):

keys := map[string]bool{
    "client-a-key-abc123": true,
    "client-b-key-xyz789": true,
}
h.Use(contrib.KeyAuth(
    keyauth.WithKeyLookUp("header:X-API-Key", ""),
    keyauth.WithValidator(func(_ context.Context, _ *app.RequestContext, key string) (bool, error) {
        return keys[key], nil
    }),
    keyauth.WithFilter(func(_ context.Context, c *app.RequestContext) bool {
        return string(c.Path()) == "/healthz"
    }),
))

⚠️ 内置安全默认 errorHandler:上游默认实现在 validator 返回 (false, nil) 时直接 err.Error() → nil 指针 panic(keyauth v0.0.0-20221011 option.go:101, 已实测复现:无效 key 的拒绝路径必崩,只能靠 recovery 兜成 500)。ekit 前置 的默认 handler 按官方状态码语义映射(ErrMissingOrMalformedAPIKey → 400, 其余 → 401)并对 nil err 硬化为 401。⚠️ 与上游的 body 分歧:上游对非 nil 校验错误回传 err.Error() 原文,ekit 统一返回固定文案 "invalid API key" (避免泄漏校验器内部错误文本);业务可用 keyauth.WithErrorHandler 覆盖 (option 按序 Apply,后传生效)。

官方依据:https://www.cloudwego.io/zh/docs/hertz/tutorials/third-party/middleware/keyauth/ (默认 errorHandler:ErrMissingOrMalformedAPIKey → 400,其他校验失败 → 401, 均走 AbortWithMsg;WithErrorHandler 用于"设置校验 token 失败的自定义处理逻辑")

⚠️ KeyAuth 直接接受 keyauth.Option(不重新包装类型),业务需要 import hertz-contrib/keyauth(已在 ekit go.mod);ekit 提供 17 个 hertz-contrib 中间件的统一入口 KeyAuth,具体 option 用法以 hertz-contrib/keyauth 为准。

func LarkCardAction ¶

func LarkCardAction(h *server.Hertz, handler *LarkCardHandler, opts ...LarkEventOption)

LarkCardAction 注册飞书卡片交互回调到 hertz 路由,默认路径 "/lark/card",业务可用 hertz 自带 h.Handle 修改路径。

官方依据:https://github.com/hertz-contrib/lark-hertz + 飞书开放平台 卡片回调文档 https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/card-callback

用法:

cardHandler := larkcard.NewCardActionHandler("verification_token", func(ctx context.Context, c *larkcard.CardAction) (interface{}, error) {
    // 业务处理用户点卡片按钮
    return nil, nil
})
contrib.LarkCardAction(h, cardHandler)

func LarkCardActionHandlerFunc ¶

func LarkCardActionHandlerFunc(handler *LarkCardHandler, opts ...LarkEventOption) func(c context.Context, ctx *app.RequestContext)

LarkCardActionHandlerFunc 透传 hertzlark.NewCardActionHandlerFunc 返 回的 app.HandlerFunc(给业务自己挂到自定义路径用)。

func LarkEvent ¶

func LarkEvent(h *server.Hertz, ed *LarkEventDispatcher, opts ...LarkEventOption)

LarkEvent 注册飞书事件回调到 hertz 路由,默认路径 "/lark/event"。 业务需先构造 EventDispatcher 注册各类事件 handler。

官方依据:https://github.com/hertz-contrib/lark-hertz + 飞书事件订阅 文档 https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/event-subscription

用法:

ed := dispatcher.NewEventDispatcher("verification_token", "encrypt_key")
ed.OnP2MessageReceivedV1(func(ctx context.Context, event *larkevent.EventV2) {
    // 处理消息事件
})
contrib.LarkEvent(h, ed)

func LarkEventHandlerFunc ¶

func LarkEventHandlerFunc(ed *LarkEventDispatcher, opts ...LarkEventOption) func(c context.Context, ctx *app.RequestContext)

LarkEventHandlerFunc 透传 hertzlark.NewEventHandlerFunc 返回的 app.HandlerFunc(给业务自己挂到自定义路径用)。

func MountReverseProxy ¶

func MountReverseProxy(h *server.Hertz, rp *ReverseProxy)

MountReverseProxy 把 rp 挂到 h 的 NoRoute 上(catch-all 反向代理)。 业务也可自己 h.GET/POST/Handle 单独挂。 ⚠️ h.NoRoute 是赋值语义(hertz 未透出当前 handler,无法检测冲突): 多次调用或与业务自设 NoRoute 混用时后者静默失效——一个 engine 只挂一个。

func RegisterDebug ¶

func RegisterDebug(h *server.Hertz, opts ...DebugOption)

RegisterDebug 在 h *server.Hertz 上注册带鉴权 + fgprof 选项的 pprof 端点。

与 RegisterPprof 区别:支持鉴权(防止公网被扫到)和 fgprof(非阻塞 CPU profiling)。默认无鉴权、无 fgprof,业务按需 WithDebugAuth/WithDebugFgprof。

用法:

h := server.New()
RegisterDebug(h,
    WithDebugPrefix("/internal/pprof"),
    WithDebugAuth(os.Getenv("PPROF_TOKEN")),
    WithDebugFgprof(),
)

官方依据:https://github.com/hertz-contrib/pprof + hertz 官方扩展列表 https://github.com/cloudwego/hertz#extensions。

func RegisterDebugGroup ¶

func RegisterDebugGroup(g *route.RouterGroup, prefix string, token ...string)

RegisterDebugGroup 在已有 router group 上注册 debug 端点,可选 token 鉴权。

用法:

admin := h.Group("/admin")
RegisterDebugGroup(admin, "/debug", "secret-token")

token 可省略,省略时不启用鉴权(等同于 RegisterPprofWithGroup)。

func RegisterSentinelServer ¶

func RegisterSentinelServer(h *server.Hertz, opts ...SentinelServerOption)

RegisterSentinelServer 业务用 server 直接挂载的便捷 helper(等同 SentinelServerMiddleware + h.Use)。

func RegisterSessions ¶

func RegisterSessions(h *server.Hertz, name string, store Store)

RegisterSessions 跟 Sessions 等价,只是用 h *server.Hertz 直接调, 跟 RegisterPprof/RegisterDebug 风格统一。

func RegisterSessionsMany ¶

func RegisterSessionsMany(h *server.Hertz, names []string, store Store)

RegisterSessionsMany 跟 SessionsMany 等价,Server 风格。

func RegisterSwaggerV2 ¶

func RegisterSwaggerV2(h *server.Hertz, opts ...func(*httpSwagger.Config))

RegisterSwaggerV2 在 h *server.Hertz 上挂载 swagger UI 路由,prefix 默认 /swagger/*any,specURL 默认 /swagger/doc.json。

完整示例:

contrib.RegisterSwaggerV2(h,
    mw.WithSwaggerURL("http://localhost:8888/swagger/doc.json"),
    httpSwagger.DeepLinking(true),
)

func RegisterSwaggerV2WithPrefix ¶

func RegisterSwaggerV2WithPrefix(h *server.Hertz, prefix string, opts ...func(*httpSwagger.Config))

RegisterSwaggerV2WithPrefix 在自定义前缀挂载 swagger UI(例如隐藏到 /internal/debug/swagger 避免公网被扫到),specURL 自动推导为 <prefix>/doc.json(上游 doc.json handler 跟随注册路径,无需业务手写)。

contrib.RegisterSwaggerV2WithPrefix(h, "/internal/debug/swagger",
    httpSwagger.DeepLinking(true))

func SentinelClientMiddleware ¶

func SentinelClientMiddleware(opts ...SentinelClientOption) client.Middleware

SentinelClientMiddleware 透传 opensergosentinel.SentinelClientMiddleware, 启用 hertz 客户端限流。

func SentinelServerMiddleware ¶

func SentinelServerMiddleware(opts ...SentinelServerOption) app.HandlerFunc

SentinelServerMiddleware 透传 hertz-contrib/opensergo/sentinel/adapter 的 SentinelServerMiddleware,启用 hertz 服务端 sentinel 限流/熔断。

官方依据:https://github.com/hertz-contrib/opensergo (sentinel adapter for hertz) + OpenSergo 微服务治理 spec。

用法:

h.Use(contrib.SentinelServerMiddleware(
    mw.WithSentinelServerResourceExtractor(func(ctx context.Context, c *app.RequestContext) string {
        return string(c.Path())  // 按 URL path 限流
    }),
    mw.WithSentinelServerBlockFallback(func(ctx context.Context, c *app.RequestContext) {
        c.AbortWithStatus(429)
    }),
))

业务需先调 sentinel.InitWithConfig 或 sentinel.InitDefault 初始化 sentinel 规则(流控/熔断/系统保护等),ekit 不替业务写规则。

func Sessions ¶

func Sessions(name string, store Store) app.HandlerFunc

Sessions 注册 session 中间件,把请求 cookie 解析为 hertz-contrib sessions.Session 注入到 handler context。

用法:

import "github.com/hertz-contrib/sessions/cookie"
import contrib "github.com/oekit/middleware/contrib"

store := cookie.NewStore([]byte("secret"))
h.Use(contrib.Sessions("mysession", store))
h.GET("/hello", func(ctx context.Context, c *app.RequestContext) {
    s := mw.DefaultSession(c)
    s.Set("hello", "world")
    s.Save()
    c.JSON(200, utils.H{"hello": s.Get("hello")})
})

官方依据:https://github.com/hertz-contrib/sessions + hertz 官方扩展 列表 https://github.com/cloudwego/hertz#extensions。

func SessionsMany ¶

func SessionsMany(names []string, store Store) app.HandlerFunc

SessionsMany 注册多个 session(同一个 store,不同 cookie 名),业务 通过 DefaultMany(c, "name") 取具体 session。

func SwaggerV2 ¶

func SwaggerV2(opts ...func(*httpSwagger.Config)) app.HandlerFunc

SwaggerV2 透传 httpSwagger.Handler(opts...),等价 SwaggerV2WithPrefix 但不强制传 specURL(specURL 可通过 opts 里的 httpSwagger.URL 注入)。

func SwaggerV2WithPrefix ¶

func SwaggerV2WithPrefix(prefix, specURL string, opts ...func(*httpSwagger.Config)) app.HandlerFunc

SwaggerV2WithPrefix 把 specURL 注入 httpSwagger.Handler 配置并返回 app.HandlerFunc;业务用 h.GET / h.Handle 挂载即可。

参数语义(2026-09-05 复审修复:原实现把 specURL 组装后丢弃,UI 打不开 指定的 spec):

• specURL:传给 httpSwagger.URL,swagger UI 以它加载 API 定义。上游 Handler(configFns...) 由 configFns 构造 Config(swaggo/http-swagger v1.3.4 swagger.go:151),默认 URL="doc.json"。
• prefix:只由业务 h.GET 的路由路径体现,http-swagger 本身没有 prefix 配置(上游 API 决定),传什么都不会改写 handler 行为。要挂到自定义 前缀用 RegisterSwaggerV2WithPrefix。

挂载示例:

h.GET("/swagger/*any", mw.SwaggerV2WithPrefix(
    "/swagger", "/swagger/doc.json", httpSwagger.DeepLinking(true)))