feat: add lifecycle hook support and documentation for server shutdown

- Add lifecycle hook support with WithBeforeShutdown and WithAfterShutdown options for registering custom logic before and after graceful server shutdown.
- Document lifecycle hooks usage, execution order, and sample code in all README files with examples in English, Simplified Chinese, and Traditional Chinese.
- Create a complete example under _examples/hooks demonstrating lifecycle hook usage, expected output, and use cases.
- Validate that lifecycle hook options reject nil functions and handle hook errors properly.
- Test lifecycle hook execution order, error handling, and context cancellation in the shutdown process.

Signed-off-by: appleboy <appleboy.tw@gmail.com>

Author: appleboy

README.md

@@ -19,6 +19,7 @@ English | [繁體中文](README.zh-tw.md) | [简体中文](README.zh-cn.md)
     - [Server Start Methods](#server-start-methods)
     - [Shutdown and Cleanup Methods](#shutdown-and-cleanup-methods)
     - [Options](#options)
+  - [Lifecycle Hooks Example](#lifecycle-hooks-example)
   - [License](#license)
 
 ## Features
@@ -154,6 +155,12 @@ Various options allow configuration of servers:
   - `WriteTimeout`: Response write timeout (default: 30 seconds)
   - `IdleTimeout`: Keep-alive idle connection timeout (default: 60 seconds)
 
+- **WithBeforeShutdown(hook Hook)**:
+  Register a hook to be called before server shutdown begins. Multiple hooks can be registered and will execute in registration order. Hooks receive the shutdown context and can return errors, which are collected but do not prevent shutdown from proceeding.
+
+- **WithAfterShutdown(hook Hook)**:
+  Register a hook to be called after all servers have shut down. Multiple hooks can be registered and will execute in registration order. Hooks receive the shutdown context and can return errors, which are collected and returned but do not affect server shutdown.
+
 Example with custom timeouts:
 
 ```go
@@ -163,6 +170,76 @@ router, err := graceful.Default(
 )
 ```
 
+## Lifecycle Hooks Example
+
+Lifecycle hooks allow you to execute custom logic during graceful shutdown. Use `WithBeforeShutdown` for cleanup that should happen before servers stop (like deregistering from service discovery), and `WithAfterShutdown` for cleanup after servers have stopped (like closing database connections).
+
+```go
+package main
+
+import (
+  "context"
+  "log"
+  "net/http"
+  "os/signal"
+  "syscall"
+
+  "github.com/gin-contrib/graceful"
+  "github.com/gin-gonic/gin"
+)
+
+func main() {
+  ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
+  defer stop()
+
+  router, err := graceful.Default(
+    // BeforeShutdown: called before server shutdown begins
+    graceful.WithBeforeShutdown(func(ctx context.Context) error {
+      log.Println("Notifying load balancer...")
+      // Deregister from load balancer
+      return nil
+    }),
+    graceful.WithBeforeShutdown(func(ctx context.Context) error {
+      log.Println("Stopping background workers...")
+      // Stop accepting new background jobs
+      return nil
+    }),
+
+    // AfterShutdown: called after all servers have shut down
+    graceful.WithAfterShutdown(func(ctx context.Context) error {
+      log.Println("Closing database connections...")
+      // Close database pool
+      return nil
+    }),
+    graceful.WithAfterShutdown(func(ctx context.Context) error {
+      log.Println("Flushing metrics...")
+      // Send final metrics
+      return nil
+    }),
+  )
+  if err != nil {
+    panic(err)
+  }
+  defer router.Close()
+
+  router.GET("/", func(c *gin.Context) {
+    c.String(http.StatusOK, "Welcome Gin Server")
+  })
+
+  if err := router.RunWithContext(ctx); err != nil && err != context.Canceled {
+    panic(err)
+  }
+}
+```
+
+When shutdown is triggered, hooks execute in this order:
+
+1. All `BeforeShutdown` hooks (in registration order)
+2. Server graceful shutdown
+3. All `AfterShutdown` hooks (in registration order)
+
+See the [hooks example](_examples/hooks) for a complete working example.
+
 ---
 
 ## License

README.zh-cn.md

@@ -19,6 +19,7 @@
     - [服务器启动方法](#服务器启动方法)
     - [关闭与清理方法](#关闭与清理方法)
     - [选项](#选项)
+  - [生命周期 Hooks 示例](#生命周期-hooks-示例)
   - [许可证](#许可证)
 
 ## 特性
@@ -154,6 +155,12 @@ type Graceful struct {
   - `WriteTimeout`：响应写入超时（默认：30 秒）
   - `IdleTimeout`：Keep-Alive 空闲连接超时（默认：60 秒）
 
+- **WithBeforeShutdown(hook Hook)**：
+  注册一个在服务器开始关闭前调用的 hook。可注册多个 hooks，将按注册顺序执行。Hooks 会接收到 shutdown context，可返回错误，这些错误会被收集但不会阻止关闭流程继续执行。
+
+- **WithAfterShutdown(hook Hook)**：
+  注册一个在所有服务器关闭后调用的 hook。可注册多个 hooks，将按注册顺序执行。Hooks 会接收到 shutdown context，可返回错误，这些错误会被收集并返回，但不影响服务器关闭流程。
+
 自定义超时设置示例：
 
 ```go
@@ -163,6 +170,76 @@ router, err := graceful.Default(
 )
 ```
 
+## 生命周期 Hooks 示例
+
+生命周期 hooks 允许你在优雅关闭过程中执行自定义逻辑。使用 `WithBeforeShutdown` 进行应在服务器停止前的清理工作（如从服务发现中注销），使用 `WithAfterShutdown` 进行服务器停止后的清理工作（如关闭数据库连接）。
+
+```go
+package main
+
+import (
+  "context"
+  "log"
+  "net/http"
+  "os/signal"
+  "syscall"
+
+  "github.com/gin-contrib/graceful"
+  "github.com/gin-gonic/gin"
+)
+
+func main() {
+  ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
+  defer stop()
+
+  router, err := graceful.Default(
+    // BeforeShutdown：在服务器开始关闭前调用
+    graceful.WithBeforeShutdown(func(ctx context.Context) error {
+      log.Println("通知负载均衡器...")
+      // 从负载均衡器注销
+      return nil
+    }),
+    graceful.WithBeforeShutdown(func(ctx context.Context) error {
+      log.Println("停止后台工作进程...")
+      // 停止接收新的后台任务
+      return nil
+    }),
+
+    // AfterShutdown：在所有服务器关闭后调用
+    graceful.WithAfterShutdown(func(ctx context.Context) error {
+      log.Println("关闭数据库连接...")
+      // 关闭数据库连接池
+      return nil
+    }),
+    graceful.WithAfterShutdown(func(ctx context.Context) error {
+      log.Println("推送指标数据...")
+      // 发送最终指标
+      return nil
+    }),
+  )
+  if err != nil {
+    panic(err)
+  }
+  defer router.Close()
+
+  router.GET("/", func(c *gin.Context) {
+    c.String(http.StatusOK, "Welcome Gin Server")
+  })
+
+  if err := router.RunWithContext(ctx); err != nil && err != context.Canceled {
+    panic(err)
+  }
+}
+```
+
+当触发关闭时，hooks 会按以下顺序执行：
+
+1. 所有 `BeforeShutdown` hooks（按注册顺序）
+2. 服务器优雅关闭
+3. 所有 `AfterShutdown` hooks（按注册顺序）
+
+完整可执行示例请参阅 [hooks 示例](_examples/hooks)。
+
 ---
 
 ## 许可证

README.zh-tw.md

@@ -19,6 +19,7 @@
     - [伺服器啟動方法](#伺服器啟動方法)
     - [關閉與清理方法](#關閉與清理方法)
     - [選項](#選項)
+  - [生命週期 Hooks 範例](#生命週期-hooks-範例)
   - [授權條款](#授權條款)
 
 ## 特色
@@ -154,6 +155,12 @@ type Graceful struct {
   - `WriteTimeout`：回應寫入逾時（預設：30 秒）
   - `IdleTimeout`：Keep-Alive 閒置連線逾時（預設：60 秒）
 
+- **WithBeforeShutdown(hook Hook)**：
+  註冊一個在伺服器開始關閉前呼叫的 hook。可註冊多個 hooks，將按註冊順序執行。Hooks 會接收到 shutdown context，可回傳錯誤，這些錯誤會被收集但不會阻止關閉流程繼續執行。
+
+- **WithAfterShutdown(hook Hook)**：
+  註冊一個在所有伺服器關閉後呼叫的 hook。可註冊多個 hooks，將按註冊順序執行。Hooks 會接收到 shutdown context，可回傳錯誤，這些錯誤會被收集並回傳，但不影響伺服器關閉流程。
+
 自訂逾時設定範例：
 
 ```go
@@ -163,6 +170,76 @@ router, err := graceful.Default(
 )
 ```
 
+## 生命週期 Hooks 範例
+
+生命週期 hooks 允許你在優雅關閉過程中執行自訂邏輯。使用 `WithBeforeShutdown` 進行應在伺服器停止前的清理工作（如從服務發現中註銷），使用 `WithAfterShutdown` 進行伺服器停止後的清理工作（如關閉資料庫連線）。
+
+```go
+package main
+
+import (
+  "context"
+  "log"
+  "net/http"
+  "os/signal"
+  "syscall"
+
+  "github.com/gin-contrib/graceful"
+  "github.com/gin-gonic/gin"
+)
+
+func main() {
+  ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
+  defer stop()
+
+  router, err := graceful.Default(
+    // BeforeShutdown：在伺服器開始關閉前呼叫
+    graceful.WithBeforeShutdown(func(ctx context.Context) error {
+      log.Println("通知負載平衡器...")
+      // 從負載平衡器註銷
+      return nil
+    }),
+    graceful.WithBeforeShutdown(func(ctx context.Context) error {
+      log.Println("停止背景工作程序...")
+      // 停止接收新的背景任務
+      return nil
+    }),
+
+    // AfterShutdown：在所有伺服器關閉後呼叫
+    graceful.WithAfterShutdown(func(ctx context.Context) error {
+      log.Println("關閉資料庫連線...")
+      // 關閉資料庫連線池
+      return nil
+    }),
+    graceful.WithAfterShutdown(func(ctx context.Context) error {
+      log.Println("推送指標資料...")
+      // 傳送最終指標
+      return nil
+    }),
+  )
+  if err != nil {
+    panic(err)
+  }
+  defer router.Close()
+
+  router.GET("/", func(c *gin.Context) {
+    c.String(http.StatusOK, "Welcome Gin Server")
+  })
+
+  if err := router.RunWithContext(ctx); err != nil && err != context.Canceled {
+    panic(err)
+  }
+}
+```
+
+當觸發關閉時，hooks 會按以下順序執行：
+
+1. 所有 `BeforeShutdown` hooks（按註冊順序）
+2. 伺服器優雅關閉
+3. 所有 `AfterShutdown` hooks（按註冊順序）
+
+完整可執行範例請參閱 [hooks 範例](_examples/hooks)。
+
 ---
 
 ## 授權條款

_examples/hooks/README.md

@@ -0,0 +1,51 @@
+# Lifecycle Hooks Example
+
+This example demonstrates how to use lifecycle hooks (`WithBeforeShutdown` and `WithAfterShutdown`) to execute custom logic during graceful shutdown.
+
+## Usage
+
+```bash
+go run main.go
+```
+
+Then send a request:
+
+```bash
+curl http://localhost:8080/
+```
+
+To see the hooks in action, stop the server with `Ctrl+C` (SIGTERM).
+
+## Expected Output
+
+When you stop the server, you should see output like:
+
+```txt
+Shutdown signal received, starting graceful shutdown...
+HOOK: Before shutdown - Notifying load balancer...
+HOOK: Load balancer notified
+HOOK: Before shutdown - Stopping background workers...
+HOOK: Background workers stopped
+HOOK: After shutdown - Closing database connections...
+HOOK: Database connections closed
+HOOK: After shutdown - Flushing metrics...
+HOOK: Metrics flushed
+Server stopped gracefully
+```
+
+## Hook Execution Order
+
+1. **BeforeShutdown hooks** - Execute in registration order before server shutdown begins
+   - Notify load balancer to stop sending traffic
+   - Stop background workers
+
+2. **Server Shutdown** - All HTTP servers shut down gracefully
+
+3. **AfterShutdown hooks** - Execute in registration order after servers have stopped
+   - Close database connections
+   - Flush metrics to external service
+
+## Use Cases
+
+- **BeforeShutdown**: Deregister from service discovery, notify load balancers, stop accepting new work
+- **AfterShutdown**: Close database connections, flush buffers, cleanup resources, send final metrics

_examples/hooks/go.mod

@@ -0,0 +1,42 @@
+module example
+
+go 1.25.1
+
+require (
+	github.com/gin-contrib/graceful v1.1.4
+	github.com/gin-gonic/gin v1.11.0
+)
+
+require (
+	github.com/bytedance/gopkg v0.1.3 // indirect
+	github.com/bytedance/sonic v1.14.2 // indirect
+	github.com/bytedance/sonic/loader v0.4.0 // indirect
+	github.com/cloudwego/base64x v0.1.6 // indirect
+	github.com/gabriel-vasile/mimetype v1.4.11 // indirect
+	github.com/gin-contrib/sse v1.1.0 // indirect
+	github.com/go-playground/locales v0.14.1 // indirect
+	github.com/go-playground/universal-translator v0.18.1 // indirect
+	github.com/go-playground/validator/v10 v10.28.0 // indirect
+	github.com/goccy/go-json v0.10.5 // indirect
+	github.com/goccy/go-yaml v1.19.0 // indirect
+	github.com/json-iterator/go v1.1.12 // indirect
+	github.com/klauspost/cpuid/v2 v2.3.0 // indirect
+	github.com/leodido/go-urn v1.4.0 // indirect
+	github.com/mattn/go-isatty v0.0.20 // indirect
+	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
+	github.com/modern-go/reflect2 v1.0.2 // indirect
+	github.com/pelletier/go-toml/v2 v2.2.4 // indirect
+	github.com/quic-go/qpack v0.6.0 // indirect
+	github.com/quic-go/quic-go v0.57.1 // indirect
+	github.com/twitchyliquid64/golang-asm v0.15.1 // indirect
+	github.com/ugorji/go/codec v1.3.1 // indirect
+	golang.org/x/arch v0.23.0 // indirect
+	golang.org/x/crypto v0.45.0 // indirect
+	golang.org/x/net v0.47.0 // indirect
+	golang.org/x/sync v0.18.0 // indirect
+	golang.org/x/sys v0.38.0 // indirect
+	golang.org/x/text v0.31.0 // indirect
+	google.golang.org/protobuf v1.36.10 // indirect
+)
+
+replace github.com/gin-contrib/graceful v1.1.4 => ../../