// New 初始化一個新的 web Handler（核心功能：初始化 Handler 結構體 + 注冊所有 web 路由）
func New(logger *slog.Logger, o *Options) *Handler {
	// 日志器容錯：若傳入 logger 為 nil，使用空日志器（避免空指針）
	if logger == nil {
		logger = promslog.NewNopLogger()
	}

	// 初始化監控指標：基于傳入的注冊器（Registerer）創建 metrics 實例，用于路由請求的指標統計
	m := newMetrics(o.Registerer)
	// 初始化路由管理器：
	// 1. 綁定指標監控中間件（m.instrumentHandler，統計路由請求耗時、成功/失敗數等）
	// 2. 綁定路徑前綴設置中間件（setPathWithPrefix("")，初始化路徑前綴為空）
	router := route.New().
		WithInstrumentation(m.instrumentHandler).
		WithInstrumentation(setPathWithPrefix(""))

	// 獲取當前工作目錄（CWD）：用于后續記錄服務運行路徑，失敗時記錄錯誤信息
	cwd, err := os.Getwd()
	if err != nil {
		cwd = "<error retrieving current working directory>"
	}

	// 初始化 Handler 核心結構體：聚合所有依賴（日志、監控、路由、配置、存儲等）
	h := &Handler{
		logger: logger,                  // 日志器
		gatherer: o.Gatherer,            // 指標采集器（用于暴露 /metrics）
		metrics:  m,                     // 自定義監控指標實例
		router:      router,             // 路由管理器
		quitCh:      make(chan struct{}),// 服務退出信號通道
		reloadCh:    make(chan chan error),// 配置重載信號通道（帶錯誤返回）
		options:     o,                  // 傳入的 web 配置選項
		versionInfo: o.Version,          // 服務版本信息
		birth:       time.Now().UTC(),   // 服務啟動時間（UTC 時區）
		cwd:         cwd,                // 服務運行目錄
		flagsMap:    o.Flags,            // 命令行參數映射

		// 核心業務依賴注入（Prometheus 核心功能模塊）
		context:         o.Context,         // 根上下文（用于服務生命周期管理）
		scrapeManager:   o.ScrapeManager,   // 采集管理器（管理目標采集任務）
		ruleManager:     o.RuleManager,     // 規則管理器（管理告警/記錄規則）
		queryEngine:     o.QueryEngine,     // 查詢引擎（處理 PromQL 查詢）
		lookbackDelta:   o.LookbackDelta,   // 查詢回溯時間窗口
		storage:         o.Storage,         // 主存儲（長期指標存儲）
		localStorage:    o.LocalStorage,    // 本地存儲（短期/臨時指標）
		exemplarStorage: o.ExemplarStorage, // 樣本存儲（關聯指標的原始樣本）
		notifier:        o.Notifier,        // 告警通知器（發送告警到 Alertmanager）

		now: model.Now, // 時間獲取函數（默認當前時間，便于測試 mock）
	}
	// 設置服務初始狀態為「未就緒」（NotReady），就緒后通過其他邏輯更新
	h.SetReady(NotReady)

	// 初始化 API v1 所需的「資源檢索器工廠函數」：
	// 作用是為 API 提供統一的資源訪問入口，解耦 API 與具體模塊的依賴
	factorySPr := func(_ context.Context) api_v1.ScrapePoolsRetriever { return h.scrapeManager } // 采集池檢索器（API 查采集池）
	factoryTr := func(_ context.Context) api_v1.TargetRetriever { return h.scrapeManager }     // 采集目標檢索器（API 查采集目標）
	factoryAr := func(_ context.Context) api_v1.AlertmanagerRetriever { return h.notifier }    // Alertmanager 檢索器（API 查告警接收器）
	FactoryRr := func(_ context.Context) api_v1.RulesRetriever { return h.ruleManager }        // 規則檢索器（API 查告警/記錄規則）

	// 初始化 Appendable 存儲：僅當啟用遠程寫入接收（RemoteWriteReceiver）或 OTLP 寫入接收時，使用主存儲
	var app storage.Appendable
	if o.EnableRemoteWriteReceiver || o.EnableOTLPWriteReceiver {
		app = h.storage
	}

	// 初始化 API v1 實例：綁定所有核心依賴，為后續路由提供 API 能力
	h.apiV1 = api_v1.NewAPI(
		h.queryEngine,          // 查詢引擎
		h.storage,              // 主存儲
		app,                    // 可追加存儲（遠程寫入用）
		h.exemplarStorage,      // 樣本存儲
		factorySPr,             // 采集池檢索器工廠
		factoryTr,              // 采集目標檢索器工廠
		factoryAr,              // Alertmanager 檢索器工廠
		// 配置獲取函數（帶讀鎖，保證配置讀取線程安全）
		func() config.Config {
			h.mtx.RLock()         // 加讀鎖（防止配置更新時并發讀取）
			defer h.mtx.RUnlock() // 釋放讀鎖
			return *h.config
		},
		o.Flags,                // 命令行參數
		// API 全局 URL 配置（用于生成正確的外部鏈接）
		api_v1.GlobalURLOptions{
			ListenAddress: o.ListenAddresses[0], // 監聽地址（第一個）
			Host:          o.ExternalURL.Host,   // 外部訪問 Host
			Scheme:        o.ExternalURL.Scheme, // 外部訪問協議（http/https）
		},
		h.testReady,            // 就緒狀態檢查函數（API 就緒性校驗）
		h.options.LocalStorage, // 本地存儲
		h.options.TSDBDir,      // TSDB 存儲目錄
		h.options.EnableAdminAPI, // 是否啟用 Admin API（如刪除指標）
		logger,                 // 日志器
		FactoryRr,              // 規則檢索器工廠
		h.options.RemoteReadSampleLimit,    // 遠程讀取樣本數限制
		h.options.RemoteReadConcurrencyLimit, // 遠程讀取并發數限制
		h.options.RemoteReadBytesInFrame,   // 遠程讀取單幀字節數限制
		h.options.IsAgent,       // 是否為 Agent 模式（區別于 Server 模式）
		h.options.CORSOrigin,    // CORS 跨域配置
		h.runtimeInfo,           // 運行時信息（如內存、CPU 占用）
		h.versionInfo,           // 版本信息
		h.options.NotificationsGetter, // 告警通知查詢器（API 查告警歷史）
		h.options.NotificationsSub,    // 告警通知訂閱器（API 訂閱告警）
		o.Gatherer,              // 指標采集器
		o.Registerer,            // 指標注冊器
		nil,                     // 預留參數（暫無使用）
		o.EnableRemoteWriteReceiver, // 是否啟用遠程寫入接收
		o.AcceptRemoteWriteProtoMsgs, // 是否接受 Protobuf 格式的遠程寫入
		o.EnableOTLPWriteReceiver,    // 是否啟用 OTLP 寫入接收
		o.ConvertOTLPDelta,           // 是否將 OTLP Delta 指標轉為 Cumulative
		o.NativeOTLPDeltaIngestion,   // 是否原生支持 OTLP Delta 指標攝入
		o.CTZeroIngestionEnabled,     // 是否啟用 CT Zero 指標攝入
	)

	// 路由前綴配置：若配置了非根路徑前綴（RoutePrefix != "/"）
	if o.RoutePrefix != "/" {
		// 根路徑重定向：訪問 "/" 時，重定向到配置的前綴路徑（避免 404）
		router.Get("/", func(w http.ResponseWriter, r *http.Request) {
			http.Redirect(w, r, o.RoutePrefix, http.StatusFound)
		})
		// 為所有后續注冊的路由添加前綴（批量生效）
		router = router.WithPrefix(o.RoutePrefix)
	}

	// 首頁路徑配置：根據模式選擇默認首頁
	homePage := "/query"          // 默認首頁：新 UI 的查詢頁面
	if o.UseOldUI {
		homePage = "/graph"       // 舊 UI 模式：首頁為 /graph
	}
	if o.IsAgent {
		homePage = "/agent"       // Agent 模式：首頁為 /agent
	}

	// 就緒狀態檢查函數：復用 Handler 的 testReady 方法（判斷服務是否就緒）
	readyf := h.testReady

	// 根路徑重定向：訪問路由前綴根路徑（如 /prometheus/）時，重定向到配置的首頁
	router.Get("/", func(w http.ResponseWriter, r *http.Request) {
		// 拼接外部 URL 路徑 + 首頁路徑（保證重定向地址正確）
		http.Redirect(w, r, path.Join(o.ExternalURL.Path, homePage), http.StatusFound)
	})

	// 舊 UI 兼容：非舊 UI 模式下，訪問 /graph 重定向到 /query（統一新 UI 入口）
	if !o.UseOldUI {
		router.Get("/graph", func(w http.ResponseWriter, r *http.Request) {
			// 保留原查詢參數（RawQuery），避免參數丟失
			http.Redirect(w, r, path.Join(o.ExternalURL.Path, "/query?"+r.URL.RawQuery), http.StatusFound)
		})
	}

	// React 前端資源根路徑配置：根據 UI 模式選擇資源目錄
	reactAssetsRoot := "/static/mantine-ui" // 新 UI：Mantine 組件庫資源目錄
	if h.options.UseOldUI {
		reactAssetsRoot = "/static/react-app" // 舊 UI：舊 React 應用資源目錄
	}

	// 舊控制臺兼容路由：為 /classic/static/*filepath 提供靜態資源服務
	// 用途：舊控制臺庫（如 console_libraries/prom.lib）依賴該路徑下的資源
	router.Get("/classic/static/*filepath", func(w http.ResponseWriter, r *http.Request) {
		// 路徑重寫：將 /classic/static/xxx 轉為 /static/xxx（匹配 ui.Assets 中的資源路徑）
		r.URL.Path = path.Join("/static", route.Param(r.Context(), "filepath"))
		// 使用靜態文件服務：從 ui.Assets（嵌入式資源）中讀取文件
		fs := server.StaticFileServer(ui.Assets)
		fs.ServeHTTP(w, r)
	})

	// 版本信息路由：GET /version，調用 h.version 處理器返回版本信息
	router.Get("/version", h.version)
	// 自身監控指標路由：GET /metrics，使用 promhttp 提供標準 Prometheus 指標暴露
	router.Get("/metrics", promhttp.Handler().ServeHTTP)

	// 聯邦查詢路由：GET /federate
	// 1. 就緒校驗：通過 readyf 中間件，未就緒時返回 503
	// 2. 壓縮處理：使用 httputil.CompressionHandler 壓縮響應（減少網絡傳輸）
	// 3. 處理器：調用 h.federation 處理聯邦查詢請求
	router.Get("/federate", readyf(httputil.CompressionHandler{
		Handler: http.HandlerFunc(h.federation),
	}.ServeHTTP))

	// 控制臺頁面路由：GET /consoles/*filepath
	// 1. 就緒校驗：未就緒時拒絕訪問
	// 2. 處理器：調用 h.consoles 加載控制臺頁面資源（支持自定義控制臺）
	router.Get("/consoles/*filepath", readyf(h.consoles))

	// React 應用服務函數：動態生成 React 首頁 HTML（替換占位符為實際配置）
	serveReactApp := func(w http.ResponseWriter, _ *http.Request) {
		// 拼接 React 首頁 HTML 路徑（從嵌入式資源中讀取）
		indexPath := reactAssetsRoot + "/index.html"
		f, err := ui.Assets.Open(indexPath)
		if err != nil {
			// 資源讀取失敗：返回 500 并提示錯誤
			w.WriteHeader(http.StatusInternalServerError)
			fmt.Fprintf(w, "Error opening React index.html: %v", err)
			return
		}
		// 延遲關閉文件句柄（避免資源泄漏）
		defer func() { _ = f.Close() }()
		// 讀取 HTML 文件內容
		idx, err := io.ReadAll(f)
		if err != nil {
			// 內容讀取失敗：返回 500 并提示錯誤
			w.WriteHeader(http.StatusInternalServerError)
			fmt.Fprintf(w, "Error reading React index.html: %v", err)
			return
		}
		// 替換 HTML 中的占位符為實際配置（讓前端獲取后端配置）
		replacedIdx := bytes.ReplaceAll(idx, []byte("CONSOLES_LINK_PLACEHOLDER"), []byte(h.consolesPath())) // 控制臺鏈接
		replacedIdx = bytes.ReplaceAll(replacedIdx, []byte("TITLE_PLACEHOLDER"), []byte(h.options.PageTitle)) // 頁面標題
		replacedIdx = bytes.ReplaceAll(replacedIdx, []byte("AGENT_MODE_PLACEHOLDER"), []byte(strconv.FormatBool(h.options.IsAgent))) // 是否為 Agent 模式
		replacedIdx = bytes.ReplaceAll(replacedIdx, []byte("READY_PLACEHOLDER"), []byte(strconv.FormatBool(h.isReady()))) // 服務就緒狀態
		replacedIdx = bytes.ReplaceAll(replacedIdx, []byte("LOOKBACKDELTA_PLACEHOLDER"), []byte(model.Duration(h.options.LookbackDelta).String())) // 查詢回溯窗口
		// 返回替換后的 HTML 內容（前端渲染入口）
		w.Write(replacedIdx)
	}

	// React 路由路徑配置：根據 UI 模式選擇前端路由列表
	reactRouterPaths := newUIReactRouterPaths       // 新 UI 前端路由（如 /query、/alerts）
	reactRouterServerPaths := newUIReactRouterServerPaths // 新 UI Server 模式路由
	if h.options.UseOldUI {
		reactRouterPaths = oldUIReactRouterPaths       // 舊 UI 前端路由
		reactRouterServerPaths = oldUIReactRouterServerPaths // 舊 UI Server 模式路由
	}

	// 注冊 React 前端路由：為所有前端路由綁定 serveReactApp 處理器（前端路由復用首頁 HTML）
	for _, p := range reactRouterPaths {
		router.Get(p, serveReactApp)
	}

	//  Agent 模式額外路由：注冊 Agent 模式專屬的前端路由
	if h.options.IsAgent {
		for _, p := range reactRouterAgentPaths {
			router.Get(p, serveReactApp)
		}
	} else {
		//  Server 模式額外路由：注冊 Server 模式專屬的前端路由
		for _, p := range reactRouterServerPaths {
			router.Get(p, serveReactApp)
		}
	}

	// 根路徑靜態資源路由：為瀏覽器圖標、應用清單提供服務（需根路徑訪問，如 /favicon.ico）
	for _, p := range []string{"/favicon.svg", "/favicon.ico", "/manifest.json"} {
		// 拼接資源在嵌入式資產中的實際路徑
		assetPath := reactAssetsRoot + p
		router.Get(p, func(w http.ResponseWriter, r *http.Request) {
			// 路徑重寫：將根路徑資源請求轉為嵌入式資產中的路徑
			r.URL.Path = assetPath
			fs := server.StaticFileServer(ui.Assets)
			fs.ServeHTTP(w, r)
		})
	}

	// React 靜態資源目錄配置：根據 UI 模式選擇資源目錄
	reactStaticAssetsDir := "/assets"  // 新 UI：靜態資源目錄（如 /assets/css、/assets/js）
	if h.options.UseOldUI {
		reactStaticAssetsDir = "/static" // 舊 UI：靜態資源目錄（如 /static/css）
	}
	// React 靜態資源路由：為 /assets/* 或 /static/* 提供靜態資源服務
	router.Get(reactStaticAssetsDir+"/*filepath", func(w http.ResponseWriter, r *http.Request) {
		// 路徑重寫：拼接資產根路徑 + 靜態資源目錄 + 文件路徑（匹配嵌入式資源）
		r.URL.Path = path.Join(reactAssetsRoot+reactStaticAssetsDir, route.Param(r.Context(), "filepath"))
		fs := server.StaticFileServer(ui.Assets)
		fs.ServeHTTP(w, r)
	})

	// 用戶自定義靜態資源路由：若配置了 UserAssetsPath（用戶本地資源目錄）
	if o.UserAssetsPath != "" {
		// 注冊 /user/*filepath 路由，從用戶指定目錄加載靜態資源
		router.Get("/user/*filepath", route.FileServe(o.UserAssetsPath))
	}

	// 生命周期 API 配置：若啟用生命周期管理（EnableLifecycle = true）
	if o.EnableLifecycle {
		// 服務退出路由：POST/PUT /-/quit，調用 h.quit 觸發服務退出
		router.Post("/-/quit", h.quit)
		router.Put("/-/quit", h.quit)
		// 配置重載路由：POST/PUT /-/reload，調用 h.reload 觸發配置重載
		router.Post("/-/reload", h.reload

h.apiV1 = api_v1.NewAPI(h.queryEngine, h.storage, app, h.exemplarStorage, factorySPr, factoryTr, factoryAr,
    func() config.Config { /* 配置獲取邏輯 */ },
    o.Flags,
    api_v1.GlobalURLOptions{ /* URL 配置 */ },
    // 其他依賴參數...
)

# https://github.com/prometheus/prometheus/blob/v3.4.0/web/web.go#L690
mux := http.NewServeMux()
mux.Handle("/", h.router)

apiPath := "/api"
if h.options.RoutePrefix != "/" {
	apiPath = h.options.RoutePrefix + apiPath
	h.logger.Info("Router prefix", "prefix", h.options.RoutePrefix)
}
av1 := route.New().
	WithInstrumentation(h.metrics.instrumentHandlerWithPrefix("/api/v1")).
	WithInstrumentation(setPathWithPrefix(apiPath + "/v1"))
h.apiV1.Register(av1)

mux.Handle(apiPath+"/v1/", http.StripPrefix(apiPath+"/v1", av1))