feat: redesign server startup around Run options

Replace the old RunShutdown and RunTLS style entry points with a single Run(opts...) API for v1. Add focused startup semantics tests, keep TLS and graceful shutdown independent, ensure sibling servers are cleaned up on startup failure, and update docs to match the new option-based startup model.

docs/advanced.md

@@ -44,7 +44,9 @@ r.SetTLSServerConfigurator(func(server *http.Server) {
 Touka 支持配置 HTTP/1.1、HTTP/2 和 H2C（HTTP/2 Cleartext）：
 
 ```go
-// 使用默认协议配置（仅 HTTP/1.1）
+// 使用默认协议配置
+// 普通 HTTP 启动时默认为 HTTP/1.1；若使用 WithTLS(...) 且未手动覆盖协议集，
+// HTTPS 服务器会默认启用 HTTP/1.1 与 HTTP/2。
 r.SetDefaultProtocols()
 
 // 自定义协议配置
@@ -57,33 +59,49 @@ r.SetProtocols(&touka.ProtocolsConfig{
 
 ### 启动方式
 
-Touka 提供了多种服务器启动方式：
+Touka 统一通过 `Run(opts...)` 启动服务器：
 
 ```go
 // 1. 简单启动（无优雅停机）
-r.Run(":8080")
+r.Run(touka.WithAddr(":8080"))
 
 // 2. 带优雅停机的启动
-r.RunShutdown(":8080", 10*time.Second)
+r.Run(touka.WithAddr(":8080"), touka.WithGracefulShutdown(10*time.Second))
 
 // 3. 带上下文的优雅停机
 ctx, cancel := context.WithCancel(context.Background())
-r.RunShutdownWithContext(":8080", ctx, 10*time.Second)
+defer cancel()
+r.Run(
+    touka.WithAddr(":8080"),
+    touka.WithGracefulShutdown(10*time.Second),
+    touka.WithShutdownContext(ctx),
+)
 
 // 4. HTTPS 启动
 tlsConfig := &tls.Config{
     MinVersion: tls.VersionTLS12,
     // 其他 TLS 配置...
 }
-r.RunTLS(":443", tlsConfig, 10*time.Second)
+// WithTLS(...) 与优雅关闭相互独立；这里演示 HTTPS + 默认优雅关闭超时。
+r.Run(
+    touka.WithAddr(":443"),
+    touka.WithTLS(tlsConfig),
+    touka.WithGracefulShutdownDefault(),
+)
 
 // 5. HTTPS + HTTP 重定向
-r.RunTLSRedir(":80", ":443", tlsConfig, 10*time.Second)
+// WithHTTPRedirect(...) 需要与 WithTLS(...) 配合使用。
+r.Run(
+    touka.WithAddr(":443"),
+    touka.WithTLS(tlsConfig),
+    touka.WithHTTPRedirect(":80"),
+    touka.WithGracefulShutdown(10*time.Second),
+)
 ```
 
 ## 优雅停机 (Graceful Shutdown)
 
-在部署新版本时，我们希望服务器停止接收新请求，但能处理完当前正在进行的请求。
+在部署新版本时，我们希望服务器停止接收新请求，但能处理完当前正在进行的请求。启用优雅关闭后，Touka 会监听 `SIGINT`/`SIGTERM`，并在关闭时取消活动请求的上下文。
 
 ```go
 r := touka.Default()
@@ -91,7 +109,7 @@ r := touka.Default()
 
 // 监听 SIGINT 和 SIGTERM 信号
 // 如果在 10 秒内未处理完，则强制关闭
-if err := r.RunShutdown(":8080", 10*time.Second); err != nil {
+if err := r.Run(touka.WithAddr(":8080"), touka.WithGracefulShutdown(10*time.Second)); err != nil {
     log.Fatal("服务器退出异常:", err)
 }
 ```

docs/introduction.md

@@ -22,6 +22,6 @@ Touka 是一个基于 Go 语言构建的高性能、多层次 Web 框架。其
 
 1. **直接性**: 框架 API 设计直观，尽可能减少开发者需要记忆的概念。
 2. **可扩展性**: 每一个核心组件（如日志、错误处理器、渲染器）都是可插拔或可定制的。
-3. **健壮性**: 内置优雅停机支持，确保在服务器更新或关闭时请求能得到正确处理。
+3. **健壮性**: 通过 `Run(...)` 的启动选项提供优雅停机支持，使服务在更新或关闭时能更稳妥地处理进行中的请求。
 
 Touka 不仅仅是一个处理 HTTP 请求的工具，它还是构建现代化、可维护、高可用 Web 应用的坚实基础。

docs/quickstart.md

@@ -46,7 +46,7 @@ func main() {
 
     // 4. 启动服务器并监听 8080 端口
     log.Println("Touka server is running on :8080")
-    if err := r.Run(":8080"); err != nil {
+    if err := r.Run(touka.WithAddr(":8080")); err != nil {
         log.Fatalf("Server failed: %v", err)
     }
 }
@@ -66,11 +66,11 @@ go run main.go
 
 ## 优雅停机
 
-在生产环境中，我们推荐使用 `RunShutdown` 方法来启动服务器，它会监听系统信号并在关闭前等待正在处理的请求完成。
+在生产环境中，我们推荐为 `Run` 追加优雅关闭选项。启用后，Touka 会监听 `SIGINT`/`SIGTERM`，在关闭时取消活动请求的上下文，并在超时前等待正在处理的请求完成。如需由应用内部事件触发关闭，还可以额外配合 `touka.WithShutdownContext(ctx)`。
 
 ```go
 // 等待 10 秒以处理剩余请求
-if err := r.RunShutdown(":8080", 10*time.Second); err != nil {
+if err := r.Run(touka.WithAddr(":8080"), touka.WithGracefulShutdown(10*time.Second)); err != nil {
     log.Fatalf("Server forced to shutdown: %v", err)
 }
 ```

docs/reverse-proxy.md

@@ -28,7 +28,7 @@ func main() {
         Target: target,
     }))
 
-    _ = r.Run(":8080")
+    _ = r.Run(touka.WithAddr(":8080"))
 }
 ```
 
@@ -497,7 +497,7 @@ func main() {
         },
     }))
 
-    if err := r.RunShutdown(":8080", 10*time.Second); err != nil {
+    if err := r.Run(touka.WithAddr(":8080"), touka.WithGracefulShutdown(10*time.Second)); err != nil {
         log.Fatal(err)
     }
 }

docs/routing.md

@@ -142,7 +142,7 @@ func main() {
     r := touka.Default()
     fsroot, _ := fs.Sub(content, "dist")
     r.StaticFS("/", http.FS(fsroot))
-    r.Run(":8080")
+    r.Run(touka.WithAddr(":8080"))
 }
 ```
 

docs/sse.md

@@ -125,4 +125,4 @@ r.GET("/events-graceful", func(c *touka.Context) {
 2. 随后，所有活跃请求的 `c.Request.Context()` 也会收到取消信号。
 3. 您的 SSE 处理器中的 `case <-c.Request.Context().Done():` 会立即触发，从而优雅地结束连接。
 
-**注意：** 请务必使用 `RunShutdown`、`RunTLS` 或 `RunTLSRedir` 来启动服务器，以便框架能自动管理这些信号。
+**注意：** 请务必通过 `r.Run(...)` 并显式传入优雅关闭选项来启动服务器，例如 `touka.WithGracefulShutdown(...)` 或 `touka.WithGracefulShutdownDefault()`。只有启用了优雅关闭，框架才会在服务退出时取消这些请求上下文。

docs/static-files.md

@@ -39,7 +39,7 @@ func main() {
     // 您也可以使用 StaticFS 服务根路径
     // r.StaticFS("/", http.FS(fsroot))
 
-    r.Run(":8080")
+    r.Run(touka.WithAddr(":8080"))
 }
 ```