Help us shape the future of Go! Take the 2026 Go Developer Survey

http

package
v1.20.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 16, 2026 License: Apache-2.0 Imports: 26 Imported by: 2

Documentation

Overview

按维度限流（v1.1 承诺回收，ROADMAP G3）：每 key 一个令牌桶， key 由调用方从请求提取（路由 / 客户端 IP / 用户标识，预置提取器 见 RateLimitKeyPath 等）。桶存储带惰性清扫，防止海量 key（如公网 IP 维度）无限增长。

Package http 提供 HTTP 服务器服务，内置健康检查端点、请求日志、 中间件与 OpenTelemetry 插装（显式注入 provider，无进程全局副作用）。

Index

Constants

View Source 
const (
	DefaultHTTPAddr        = ":8080"
	DefaultTimeout         = 60 * time.Second
	DefaultShutdownTimeout = 10 * time.Second
	// DefaultHealthCheckTimeout 是单个健康检查器的执行上限（SC-03）：
	// CheckHealth 接口无 ctx 参数，挂死的 checker 必须被限时打断，
	// 否则 readiness 探测请求被挂起、LB 反复超时。共享规则见
	// internal/serverkit（gRPC 侧同值）。
	DefaultHealthCheckTimeout = serverkit.DefaultHealthCheckTimeout
	// DefaultHealthCheckPrefix 是内置健康检查端点的路径前缀（SC-08）：
	// 端点为 <prefix>/liveness 与 <prefix>/readiness。
	DefaultHealthCheckPrefix = "/healthz"
)

Default values for HTTP server configuration.

View Source 
const RequestIDHeader = serverkit.RequestIDKey

RequestIDHeader 是 request_id 透传/回写的 HTTP 头部名：与 client/http 及 gRPC metadata 同源的共享键（internal/serverkit）。

View Source 
const UserIDHeader = serverkit.UserIDKey

UserIDHeader 是 user_id 透传/还原的 HTTP 头部名（与 gRPC metadata 同源）。

Variables

This section is empty.

Functions

func DefaultErrorHandler added in v1.1.0 

func DefaultErrorHandler(ctx context.Context, w http.ResponseWriter, r *http.Request, err error)

DefaultErrorHandler 是框架默认的 ErrorHandler：

  • 错误实现 StatusError 时以其 StatusCode() 为状态码，否则 500；
  • 响应体统一为 {"error":{"message":...}}（application/json）：4xx （业务声明的错误）原样透传 err.Error()；5xx 返回通用消息 （http.StatusText），err.Error() 可能携带 DSN/文件路径/内部状态等 细节，只进日志不回传客户端（SC-04 信息泄露）；
  • 仅 5xx 记一条 Error 日志（slog.ErrorContext，日志器为 slog.Default()，字段 method/path/status/error——需要注入自定义 日志器见 DefaultErrorHandlerWithLogger，SC-19）；非 5xx（业务 声明的 4xx 等）不记日志，由业务自行决定是否需要记录。

若响应已开始（w 已写过 header——NewErrorHandler 传入的包装器可标记）， 不再改写响应、仅记录一条 Error 日志（status 取已写入的状态码），避免 触发 superfluous WriteHeader 与损坏已发出的响应体。

func NewErrorHandler added in v1.1.0 

func NewErrorHandler(h ErrorHandler, fn HandleFunc) http.Handler

NewErrorHandler 将返回错误的业务 handler 包装为标准 http.Handler：

  • fn 返回 nil：表示业务已自行写好响应，不做任何处理；
  • fn 返回错误：调用 h 写错误响应，h 为 nil 时使用 DefaultErrorHandler；
  • fn 内 panic 不在此处恢复（panic 恢复由专门的 Recovery 中间件负责， 不在 v1.1 范围内）。

传给 fn 的 w 是轻量包装 writer：记录响应是否已开始（首次 WriteHeader/Write 即视为已开始），并保留 Flusher/Hijacker 能力 （Flush/Hijack 透传 + Unwrap 支持 http.ResponseController 穿透）。 若 fn 已写过响应头后又返回错误，h 仍会被调用，但 DefaultErrorHandler 检测到响应已开始后不再改写响应、仅记日志，不会触发 superfluous WriteHeader；自定义 h 需自行处理该情形。

服务器级默认 ErrorHandler（WithErrorHandler 选项）：经本方法接入， h 传 nil 时的兜底依次取服务器级默认 → 包级 DefaultErrorHandler。 包级 NewErrorHandler 无法访问服务器配置，其 nil 兜底始终是包级 DefaultErrorHandler（行为不变）。

func NewHandler added in v1.0.0 

func NewHandler(log Logger, h http.Handler) http.Handler

NewHandler 包装 h，为每个请求生成一条访问日志 （替代 gocloud.dev/server/requestlog.NewHandler）。

func RateLimitKeyClientIP added in v1.13.0 

func RateLimitKeyClientIP(r *http.Request) string

RateLimitKeyClientIP 按客户端 IP 分桶限流：取 RemoteAddr 的 host 部分。注意：经过反向代理/LB 时 RemoteAddr 是代理地址，需要按真实 客户端 IP 限流请基于受信代理写入的头自行编写提取器（信任代理头是 部署决策，框架不代为判定）。

func RateLimitKeyPath added in v1.13.0 

func RateLimitKeyPath(r *http.Request) string

RateLimitKeyPath 按路由路径分桶限流：同一路径的请求共享一个桶， 保护慢/贵的端点不被整体流量挤占。

func RateLimitKeyUserID added in v1.13.0 

func RateLimitKeyUserID(r *http.Request) string

RateLimitKeyUserID 按用户标识分桶限流：取请求 ctx 日志属性中的 user_id（与 client 侧传播、logging.WithAttrs 同一来源；未携带时为 空串，退化为共享桶）。

func RequestIDFrom added in v1.0.0 

func RequestIDFrom(ctx context.Context) string

RequestIDFrom 返回请求 ctx 中的 request_id，未设置时返回空字符串。

Types

type Endpoint added in v1.16.0 

type Endpoint struct {
	Path    string
	Handler http.Handler
}

Endpoint 是一个运维端点：路径 + 处理器（如 /metrics → promhttp、 /debug/pprof/... → pprof.Handler）。

type Entry added in v1.0.0 

type Entry struct {
	// Request 是已完成的请求。
	//
	// 此请求的 Body 恒为 nil，与实际请求体无关。
	Request *http.Request

	ReceivedTime    time.Time
	RequestBodySize int64

	Status             int
	ResponseHeaderSize int64
	ResponseBodySize   int64
	Latency            time.Duration
	TraceID            trace.TraceID
	SpanID             trace.SpanID

	// 以下字段为 Stackdriver 格式兼容保留，均可从 Request 派生。
	Referer           string
	RequestHeaderSize int64
	UserAgent         string
	RemoteIP          string
	// RequestID 是请求级关联 ID（WithRequestID 中间件生成/透传）。
	RequestID string
}

Entry 记录一次已完成的 HTTP 请求的信息 （替代 gocloud.dev/server/requestlog.Entry）。

type ErrorHandler added in v1.1.0 

type ErrorHandler func(ctx context.Context, w http.ResponseWriter, r *http.Request, err error)

ErrorHandler 处理业务 handler 返回的错误：向客户端写入状态码与错误响应体。 框架提供 DefaultErrorHandler 作为默认实现（StatusError 约定 + 统一 JSON 错误体）；自定义实现可自行决定状态码与响应体格式。ctx 由调用方传入， NewErrorHandler 传入 r.Context()——携带请求级日志属性（见 logging.WithAttrs）时，经 logging.NewAttrsHandler 装饰的日志器会自动 为错误日志附加 request_id 等字段。

func DefaultErrorHandlerWithLogger added in v1.6.0 

func DefaultErrorHandlerWithLogger(logger *slog.Logger) ErrorHandler

DefaultErrorHandlerWithLogger 返回携带注入日志实例的默认 ErrorHandler：行为与 DefaultErrorHandler 完全一致，仅错误日志改走 给定 logger（SC-19：包级 DefaultErrorHandler 只能回退全局 slog， 服务侧可经本变体接入 WithLogger 的实例，如 Recovery(WithRecoveryHandler(DefaultErrorHandlerWithLogger(srvLogger)))）。 logger 为 nil 时回退 slog.Default()。

type HandleFunc added in v1.1.0 

type HandleFunc func(ctx context.Context, w http.ResponseWriter, r *http.Request) error

HandleFunc 是带错误返回的业务 handler 签名：ctx 为请求上下文 （r.Context()），w 为响应 writer，r 为请求。返回 nil 表示业务已自行 写好响应；返回错误时由 NewErrorHandler 交给 ErrorHandler 处理。

type Logger added in v1.0.0 

type Logger interface {
	Log(*Entry)
}

Logger wraps the Log method. Log must be safe to call from multiple goroutines. Log must not hold onto an Entry after it returns.

type Middleware added in v1.0.0 

type Middleware func(http.Handler) http.Handler

Middleware wraps an http.Handler, typically to add cross-cutting behavior such as logging, authentication, or custom metrics.

func RateLimit added in v1.1.0 

func RateLimit(rps float64, opts ...RateLimitOption) Middleware

RateLimit 返回服务器级令牌桶限流中间件：rps 为每秒放行请求数，中间件 实例持有一个共享 limiter，超出限速的请求由限流 handler 处理（缺省 429 + JSON 错误体）。rps 必须 > 0，否则构造期直接 panic（配置错误应当 在启动阶段暴露，而非运行期静默放行/拒绝全部请求）。

建议与 Recovery 中间件搭配：Recovery 声明在最外层（WithMiddleware 的 第一个参数），RateLimit 随后——限流 handler 抛 panic 时同样能被恢复。 按路由 / IP / 用户维度限流见 RateLimitPerKey（可与本中间件叠放： 先服务器级总量、再维度级分桶）。

func RateLimitPerKey added in v1.13.0 

func RateLimitPerKey(rps float64, key func(*http.Request) string, opts ...RateLimitOption) Middleware

RateLimitPerKey 返回按维度限流的中间件：key 提取器从请求中取分桶 标识（路由路径 / 客户端 IP / 用户标识等，预置提取器见 RateLimitKeyPath / RateLimitKeyClientIP / RateLimitKeyUserID，也可 自定义组合——如 path+userID 拼接实现"单用户单路由"维度）。每个 key 独立令牌桶（rps/burst 语义同 RateLimit），互不挤占；桶按惰性清扫 回收（见 keySweepEvery 注释）。

rps 必须 > 0，否则构造期 panic（同 RateLimit 的配置错误前置暴露 约定）；key 提取器为 nil 时 panic（空指针属于编程错误）。 与服务器级 RateLimit 可叠放：先服务器级总量、再维度级分桶（中间件 顺序即包裹顺序）。

func Recovery added in v1.1.0 

func Recovery(opts ...RecoveryOption) Middleware

Recovery 返回 panic 恢复中间件：捕获下游 handler（及其余中间件）抛出的 panic，记一条 Error 日志（字段 panic 为 panic 值的字符串形式、stack 为 完整调用栈），并经 ErrorHandler 写响应——缺省 DefaultErrorHandler 写 500 + 通用 JSON 错误体（panic 值可能含连接串/路径等内部细节，不回传 客户端，SC-04）。恢复后连接保持可用，后续请求不受影响。

推荐声明在 WithMiddleware 的第一个参数（最外层）：链内任意一环（含其余 中间件与业务 handler）的 panic 都能被恢复，不会拖垮整个进程。

与内置 request_id 传播的顺序：默认装配把 RequestID 中间件包在整个用户 中间件链外侧，因此本中间件（用户声明）位于其内侧——Recovery 记录的 panic 日志带 request_id（可经 method/path 之外的 request_id 关联）。 若手动装配时把 RequestID 放在 Recovery 之后（内侧），panic 日志将拿不到 request_id，属该装配方式的取舍（SC-13 的原始表述适用于手动装配场景）。

注意：若 panic 发生在响应已开始之后（下游已写过响应头/体），ErrorHandler 只能尽力写错误体（可能追加进已发出的响应），无法改写已发送的部分—— 与 net/http 自身的 panic 兜底行为一致；业务应避免"先写响应再 panic"。

func WithRequestID added in v1.0.0 

func WithRequestID() Middleware

WithRequestID 返回一个中间件：为每个请求生成或透传 request_id—— 请求头携带合法的 x-request-id 时沿用（长度 ≤128 且字符集为 [A-Za-z0-9-_]，非法值重新生成），否则生成 UUID；回写响应头；user_id 合法时一并还原；两者经 logging.WithAttrs 写入请求 ctx，使请求链内所有 InfoContext 日志自动携带。服务端默认安装（WithDisableRequestID 关闭）。

注册顺序：默认装配中本中间件包在用户中间件（WithMiddleware）外侧—— 用户挂的 Recovery 位于其内侧，panic 日志能拿到 request_id；若手动装配 并希望 Recovery 拿到最外层保命位置，把本中间件放在 Recovery 内侧即可 （代价是 Recovery 的 panic 日志不再带 request_id，详见 Recovery 注释）。

type Option 

type Option func(*Options)

Option 用于配置 HTTP 服务 Options 的选项函数。

func WithAddr 

func WithAddr(addr string) Option

WithAddr 设置 HTTP 服务监听地址。

func WithAdvertiseAddr added in v1.4.0 

func WithAdvertiseAddr(hostPort string) Option

WithAdvertiseAddr 设置 HTTP 服务对外宣告的地址（host:port），仅保存该 字符串，供注册发现等场景经 AdvertiseAddr 读取；不影响实际监听地址， 也不参与协议推断。

func WithDisableHealthCheck added in v1.6.0 

func WithDisableHealthCheck() Option

WithDisableHealthCheck 完全关闭内置健康检查端点（SC-08）：健康探测 交给外部网关/独立探针进程时使用。

func WithDisableRequestID added in v1.15.0 

func WithDisableRequestID() Option

WithDisableRequestID 关闭内置 request_id/user_id 传播中间件（默认安装）： 需要自行接管传播或完全不要该行为的场景使用。

func WithEndpoint added in v1.16.0 

func WithEndpoint(path string, handler http.Handler) Option

WithEndpoint 挂载一个运维端点（如 WithEndpoint("/metrics", telemetry.PrometheusHandler())）： 处理器直接挂在该路径上，不经过业务中间件、request log 与 otel instrumentation——与内置健康端点同一取舍：指标抓取/探针流量不产生 自引用指标与日志噪声。路径须以 "/" 开头且不为 "/"；与业务 handler、 健康端点或彼此冲突（重复/模式重叠）时 Start 返回错误，不 panic。

func WithErrorHandler added in v1.13.0 

func WithErrorHandler(h ErrorHandler) Option

WithErrorHandler 设置服务器级默认错误处理器：Server.NewErrorHandler 的 h 传 nil 时的兜底改取它（未设置时保持包级 DefaultErrorHandler）。 典型用法是接入服务日志实例： 

WithErrorHandler(DefaultErrorHandlerWithLogger(srvLogger))

仅影响 Server.NewErrorHandler 包装的 handler；包级 NewErrorHandler 与显式传入非 nil h 的调用不受影响。

func WithHealthCheckPrefix added in v1.6.0 

func WithHealthCheckPrefix(prefix string) Option

WithHealthCheckPrefix 设置内置健康检查端点的路径前缀（缺省 /healthz， 端点为 <prefix>/liveness 与 <prefix>/readiness，SC-08）：用于网关路径 规划或与其他框架的端点对齐。

func WithHealthCheckTimeout added in v1.6.0 

func WithHealthCheckTimeout(timeout time.Duration) Option

WithHealthCheckTimeout 设置 readiness 检查中单个健康检查器的执行上限 （缺省 3s）：CheckHealth 接口无 ctx/超时（API 冻结），挂死的 checker 在超时后被视为不健康，而不是挂起探测请求（SC-03）。传 0 表示不限时。

func WithHealthCheckers added in v1.0.0 

func WithHealthCheckers(hc lynx.HealthCheckersFunc) Option

WithHealthCheckers 设置 HTTP 服务的健康检查器取值函数。 通常传方法值 app.HealthCheckers。

func WithIdleTimeout added in v1.0.0 

func WithIdleTimeout(timeout time.Duration) Option

WithIdleTimeout 设置 HTTP 连接的空闲超时时间。

func WithListener added in v1.12.0 

func WithListener(ln net.Listener) Option

WithListener 注入现成监听器：Start 跳过 net.Listen 直接在其上提供服务， Addr() 返回该监听器的实际地址（":0" 语义由注入监听器决定）。用于测试 注入 bufconn（免 TCP 端口、可并行）与宿主接管监听的场景。注意：Stop 会经由 Shutdown 关闭该监听器，注入方不应复用已停止的实例。

func WithLogger 

func WithLogger(l *slog.Logger) Option

WithLogger 设置 HTTP 服务的日志实例。

func WithMeterProvider added in v1.0.0 

func WithMeterProvider(mp metric.MeterProvider) Option

WithMeterProvider sets the OpenTelemetry MeterProvider used by the server's instrumentation. When nil, the global (noop by default) provider is used.

func WithMiddleware added in v1.0.0 

func WithMiddleware(middlewares ...Middleware) Option

WithMiddleware registers middlewares applied to the server's handler in declaration order: the first declared middleware is the outermost. The final chain is: otel instrumentation -> request log -> bus inject -> request_id/user_id propagation -> middlewares -> handler. The propagation middleware therefore wraps the whole user chain (a user-declared Recovery runs inside it and its panic logs carry request_id).

func WithPropagator added in v1.0.0 

func WithPropagator(p propagation.TextMapPropagator) Option

WithPropagator sets the propagator used to extract trace context from incoming requests. When nil, the global propagator is used.

func WithRequestLog 

func WithRequestLog(requestLog bool) Option

WithRequestLog 设置是否记录 HTTP 请求日志。

func WithServerOptions added in v1.0.0 

func WithServerOptions(fn func(*http.Server)) Option

WithServerOptions 透传配置底层 *http.Server，在内部超时之后应用。

func WithShutdownTimeout added in v1.0.0 

func WithShutdownTimeout(timeout time.Duration) Option

WithShutdownTimeout 设置 HTTP 服务优雅关停的超时时间，超过后强制关闭 活动连接。注意（SC-17）：传 0 表示显式禁用上界——Stop 仅受调用方 ctx 约束，活动连接不返回时 Stop 可无限等待；生产环境建议保留上界。 与调用方 ctx deadline 并存时取较小者（SC-05，与 gRPC 侧 Stop 一致）。

func WithTLSConfig added in v1.0.0 

func WithTLSConfig(cfg *tls.Config) Option

WithTLSConfig 以 TLS 提供服务，cfg 需包含 Certificates 或由 WithServerOptions 填充。

func WithTimeout 

func WithTimeout(timeout time.Duration) Option

WithTimeout 设置 HTTP 服务的读写超时时间（同时作用于 ReadHeaderTimeout/ReadTimeout/WriteTimeout）。

func WithTracerProvider added in v1.0.0 

func WithTracerProvider(tp trace.TracerProvider) Option

WithTracerProvider sets the OpenTelemetry TracerProvider used by the server's instrumentation. When nil, the global (noop by default) provider is used. The provider's lifecycle (init, shutdown) is the caller's responsibility. 显式注入，不修改进程全局 provider。

type Options 

type Options struct {
	Addr string
	// AdvertiseAddr 是服务对外宣告的地址（host:port），由
	// WithAdvertiseAddr 设置，仅原样保存该字符串；为空表示未显式指定。
	AdvertiseAddr string
	// Listener 非 nil 时 Start 直接在其上提供服务（WithListener 注入），
	// 跳过 net.Listen；Addr()/Ready() 反映该监听器。用于测试注入
	// bufconn 等非 TCP 监听器或宿主接管监听的场景。
	Listener    net.Listener
	Timeout     time.Duration
	IdleTimeout time.Duration
	// ShutdownTimeout 是优雅关停的上限；0 表示无上界（仅受调用方 Stop
	// ctx 约束，SC-17），与调用方 deadline 并存时取较小者（SC-05）。
	ShutdownTimeout time.Duration
	// HealthCheckTimeout 是 readiness 检查中单个 checker 的执行上限，
	// 超时视为不健康（SC-03）；0 表示不限时（慎用，挂死 checker 会挂起
	// 探测请求）。
	HealthCheckTimeout time.Duration
	// HealthCheckPrefix 是健康检查端点前缀（缺省 /healthz，SC-08）。
	HealthCheckPrefix string
	// DisableHealthCheck 为 true 时不挂载内置健康检查端点（SC-08）。
	DisableHealthCheck bool
	// DisableRequestID 为 true 时不安装内置 request_id/user_id 传播中间件
	//（WithDisableRequestID）：默认安装，收到合法的 x-request-id/x-user-id
	// 即还原进请求 ctx 并回写响应头。
	DisableRequestID bool
	HealthCheckers   lynx.HealthCheckersFunc
	Logger           *slog.Logger
	RequestLog       bool
	// ErrorHandler 是服务器级默认错误处理器（WithErrorHandler 设置）：
	// 经 Server.NewErrorHandler(h, fn) 使用，h 传 nil 时的兜底改取它
	//（未配置时回退包级 DefaultErrorHandler）——包级 NewErrorHandler
	// 无法访问服务器配置，服务器级注入走该方法。
	ErrorHandler   ErrorHandler
	TracerProvider trace.TracerProvider
	MeterProvider  metric.MeterProvider
	Propagator     propagation.TextMapPropagator
	Middlewares    []Middleware
	// TLSConfig 非 nil 时以 TLS 提供服务（需包含 Certificates 或由
	// ServerOptions 填充）。
	TLSConfig *tls.Config
	// ServerOptions 透传配置底层 *http.Server（如 MaxHeaderBytes、
	// BaseContext），在内部超时配置之后应用。
	ServerOptions func(*http.Server)
	// Endpoints 是运维端点（WithEndpoint）：挂载在业务 handler 之外，不经过
	// 业务中间件 / request log / otel instrumentation。
	Endpoints []Endpoint
}

Options 是 HTTP 服务服务的配置项。

type RateLimitOption added in v1.1.0 

type RateLimitOption func(*rateLimitOptions)

RateLimitOption 用于配置 RateLimit 中间件的选项函数。

func WithBurst added in v1.1.0 

func WithBurst(n int) RateLimitOption

WithBurst 设置令牌桶的突发容量，缺省为 max(1, rps)（rps 非整数时向上 取整）。突发容量决定瞬时允许的并发放行数：rps 相同时 burst 越大，短时 突发越宽松，但长期平均速率仍受 rps 约束。

func WithRateLimitHandler added in v1.1.0 

func WithRateLimitHandler(fn http.HandlerFunc) RateLimitOption

WithRateLimitHandler 设置超限请求的处理函数，缺省写 429 + {"error":{"message":"rate limit exceeded"}}（application/json）。

type RecoveryOption added in v1.1.0 

type RecoveryOption func(*recoveryOptions)

RecoveryOption 用于配置 Recovery 中间件的选项函数。

func WithRecoveryHandler added in v1.1.0 

func WithRecoveryHandler(h ErrorHandler) RecoveryOption

WithRecoveryHandler 设置 panic 恢复时使用的 ErrorHandler，缺省为 DefaultErrorHandler（panic 一律按 500 + 统一 JSON 错误体处理；错误消息 为 panic 值的字符串形式）。自定义实现可自行决定状态码与响应体格式。

type RequestLogger 

type RequestLogger struct {
	// contains filtered or unexported fields
}

RequestLogger writes log entries in the Stackdriver forward JSON format. The record's fields are suitable for consumption by Stackdriver Logging. slog.Logger is concurrency-safe, so no additional locking is required.

func NewRequestLogger 

func NewRequestLogger(logger *slog.Logger, onErr func(error)) *RequestLogger

NewRequestLogger returns a new logger. onErr 仅为保持既有签名兼容而保留（SC-09）：底层 slog 写入不返回 错误，历史上 log() 恒返 nil 使该回调成为死代码，其调用链已删除， 传入的函数恒不被调用。

func (*RequestLogger) Log 

func (l *RequestLogger) Log(ent *Entry)

Log writes a record to its writer. Multiple concurrent calls will produce sequential writes to its writer.

type Server 

type Server struct {
	// contains filtered or unexported fields
}

Server 是 HTTP 服务，实现 lynx.Service 接口。

func NewServer 

func NewServer(handler http.Handler, opts ...Option) *Server

NewServer 创建 HTTP 服务服务，使用给定的 handler 与配置项。

func (*Server) Addr added in v1.4.0 

func (s *Server) Addr() string

Addr 返回实际监听地址：Start 前（或 Listen 失败时）返回空字符串； 使用随机端口（如 ":0"）时返回 Listen 成功后的实际地址。 语义与 debug.Service.Addr 一致。

func (*Server) AdvertiseAddr added in v1.4.0 

func (s *Server) AdvertiseAddr() string

AdvertiseAddr 返回 WithAdvertiseAddr 设置的宣告地址；未设置时返回 空字符串。

func (*Server) Init 

func (s *Server) Init(ctx lynx.AppContext) error

Init 初始化服务：接管 Bus，并复位 Start 守卫标志（SC-15：lynx 框架 生命周期为 Init→Start→Stop，Init 复位使"重新 Init 后可再 Start"留有 语义口子；当前不支持同一实例不重 Init 的 restart）。

func (*Server) Name 

func (s *Server) Name() string

Name 返回服务名称 "http"。

func (*Server) NewErrorHandler added in v1.13.0 

func (s *Server) NewErrorHandler(h ErrorHandler, fn HandleFunc) http.Handler

NewErrorHandler 是 NewErrorHandler 的服务器版本（嵌入 Server 使用）： h 传 nil 时的兜底改取 WithErrorHandler 设置的服务器级默认（未设置时 回退包级 DefaultErrorHandler）。服务器级注入的典型用法： 

srv := NewServer(WithErrorHandler(DefaultErrorHandlerWithLogger(logger)))
mux.Handle("/api", srv.NewErrorHandler(nil, apiHandler))

func (*Server) Ready added in v1.6.0 

func (s *Server) Ready() <-chan struct{}

Ready 在 Listen 成功之后、Serve 之前关闭。Listen 失败不关闭。

func (*Server) Start 

func (s *Server) Start(ctx context.Context) error

Start 启动 HTTP 服务并开始监听，阻塞至服务退出。 显式注入 otel provider（WithPublicEndpoint 保持与旧实现一致的 traceparent-as-link 语义），不修改进程全局 otel provider。

正常关停（Stop/Shutdown）返回 nil：Serve 返回的 http.ErrServerClosed 归一化为 nil（SC-02），避免框架把正常关停发布为 lynx.service.failed 虚假事件。二次调用 Start 返回错误（SC-14）。

func (*Server) Stop 

func (s *Server) Stop(ctx context.Context) error

Stop 优雅关停 HTTP 服务；服务尚未启动时直接返回 nil。 有界规则（SC-05，与 gRPC/debug 共用 internal/serverkit）：调用方 ctx deadline 与 ShutdownTimeout 并存时取较小者；ShutdownTimeout=0 表示无 配置上界、仅以调用方 ctx 为准；超时后强制关闭活动连接（长轮询/流式 handler），并以错误返回。

type StatusError added in v1.1.0 

type StatusError interface {
	error
	StatusCode() int
}

StatusError 由业务错误类型实现，声明自身对应的 HTTP 状态码。 DefaultErrorHandler 优先取该接口的状态码，未实现该接口的错误一律 500。 支持错误包装（errors.As 查找），被包装的错误同样生效。

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.