Go‑Wind HTTP 服务器从入门到精通

目录

• 简介
• 主要概念
• 快速开始的观点是，秒跑起一个服务器
• 路由注册
• 再看驱动程序，切换底层框架
• 中间件入门
• 内置中间件详解
  • recovery —— 异常恢复
  • requestid —— 请求追踪
  • logging —— 访问日志
  • cors —— 跨域资源共享
  • timeout —— 请求超时
  • codec —— 内容协商
  • ratelimit —— 限流
  • authn —— 身份认证
• 编写自定义中间件
• 中间件组合这方面。Chain
• HTTPS / TLS 配置
• 生产级完整示例
• 常见问题 & 使用者痛点汇总

. 简介

transport/http 是 Go‑Wind 插件库提供的HTTP 服务器抽象层。它的主要价值在于：

• 多驱动架构：底层可在标准库 net/http/gin/chi/fiber 之间无缝切换，上层代码无需改动。
• 统一中间件：func http.Handler标准，与具体驱动无关。
• 优雅关闭：context.Context的优雅停机支持。
• TLS 友好：/http/https/ scheme。
• If you’ve used Go’s standard library’s net/http,you’ll feel right at home—because route handlers are just native http.HandlerFunc).

  If you’ve used Go’s standard library’s `net/http` ``。you’ll feel right at home—because route handlers are just native <`http.HandlerFunc>`.

  . 主要概念

  The following three concepts form foundation of any Go‑Wind HTTP server.

  Server

  The Server  is entry point of abstraction layer;it is responsible for:

  • Creating and managing a  net.Listener
  • Handling TLS wrapping.
  • Maintaining a middleware chain.
  • Delegating request handling to an underlying Driver.

  The Server implements `transport.Server` interface and exposes methods such as `Start / Stop / Endpoint`.

  Driver

  A Driver  defines *who* actually processes routes and performs listening:

  go type Driver interface { Handle Start error Stop error }

  Currently re are several built‑in drivers:

  Driver	Package Path	Features
  std	transport/http/driver/std
  gin	transport/http/driver/gin
  chi	transport/http/driver/chi
  fiber	transport/http/driver/fiber	;note that fasthttp isn’t fully compatible with net/http)

  Middleware

  A middleware is simply a function that takes “next handler” and returns a “wrapped handler”:

  go type Middleware func http.Handler

  You can insert custom logic before or after your business handler—for example logging,auntication。 rate limiting or panic recovery.

  mermaid flowchart LR Request -->|recovery| R1 R1 -->|requestid| R2 R2 -->|logging| R3 R3 --> BusinessHandler BusinessHandler -->|logging| R4 R4 -->|requestid| R5 R5 -->|recovery| Response

  ---

  . 快速开始： 秒跑起一个服务器

  最小示例

  go package main

  import ( "context" "fmt" "net/http" "os" "os/signal" "syscall"

  httpServer "github.com/tx7do/go-wind-plugins/transport/http"
  "github.com/tx7do/go-wind-plugins/transport/http/driver/std"
  

  )

  func main { // . 创建服务器：监听 :8080，使用标准库驱动 srv := httpServer.NewServer))

  // . 注册一个 GET 路由
  srv.GET {
  fmt.Fprintln
  })
  // . 捕获退出信号，实现优雅关闭
  ctx,stop := signal.NotifyContext,syscall.SIGINT,syscall.SIGTERM,)
  defer stop
  fmt.Printf)
  if err := srv.Start;err，= nil {
  fmt.Fprintf
  os.Exit
  }
  fmt.Println
  

  }

  运行与测试

  bash

  go run .

  curl http://localhost:8080/hello

  Hello,GoWind!

  代码解读

  代码	作用
  `NewServer)`	Create server;“:” means “any available port”.
  `WithDriver)`	You *must* specify a driver;orwise `Handle/Start` will panic.
  `srv.GET`	Add a GET route;handler follows native `http.HandlerFunc` signature.
  `signal.NotifyContext`	Catches Ctrl+C / kill signals for graceful shutdown.
  `srv.Start`	Kicks off server and blocks until ctx is cancelled.
  `srv.Endpoint`

  ---

  . 路由注册

  快捷方法

  go srv.GET // 查询使用者列表 srv.POST // 创建使用者 srv.PUT // 完整替换 srv.PATCH // 部分修改 srv.DELETE // 删除使用者 srv.HEAD // 获取头部信息 srv.OPTIONS // CORS预检等

  通用 Handle 方法

  go srv.Handle

  从注意来看。路由能力取决于驱动

  If you need advanced routing features such as path parameters or nested groups,choose **chi** or **gin** drivers.

  ---

  . 驱动程序：切换底层框架

  为什么需要多驱动？