design/provide-logger-with-mothed/task-api.md

@@ -1,9 +1,9 @@
 - **`internal/app/api/api.go` (`API`)**:
-    -   [ ] 修改 `NewAPI` 函数，移除 `logger` 参数，改为接收 `ctx context.Context`。
-    -   [ ] 移除 `API` 结构体中的 `logger` 成员，改为保存 `selfCtx context.Context`。
-    -   [ ] 为 `API` 组件本身创建 `selfCtx`：`selfCtx := logs.AddCompName(ctx, 'API')`，并传递给所有 `Controller`
+    -   [x] 修改 `NewAPI` 函数，移除 `logger` 参数，改为接收 `ctx context.Context`。
+    -   [x] 移除 `API` 结构体中的 `logger` 成员，改为保存 `Ctx context.Context`。
+    -   [x] 为 `API` 组件本身创建 `Ctx`：`Ctx := logs.AddCompName(ctx, 'API')`，并传递给所有 `Controller`
         的构造函数。
-    -   [ ] 改造 `Start` 方法，从 `a.selfCtx` 获取 `logger` 实例进行日志记录。
-    -   [ ] 改造 `Stop` 方法，从 `a.selfCtx` 获取 `logger` 实例进行日志记录。
+    -   [x] 改造 `Start` 方法，从 `a.Ctx` 获取 `logger` 实例进行日志记录。
+    -   [x] 改造 `Stop` 方法，从 `a.Ctx` 获取 `logger` 实例进行日志记录。
 - **`internal/app/api/router.go`
-    -   [ ] 改造 `setupRoutes` 方法，从 `a.selfCtx` 获取 `logger` 实例进行日志记录。
+    -   [x] 改造 `setupRoutes` 方法，从 `a.Ctx` 获取 `logger` 实例进行日志记录。

internal/app/api/api.go

@@ -32,7 +32,6 @@ import (
 	"git.huangwc.com/pig/pig-farm-controller/internal/infra/config"
 	"git.huangwc.com/pig/pig-farm-controller/internal/infra/logs"
 	"git.huangwc.com/pig/pig-farm-controller/internal/infra/repository"
-
 	"github.com/labstack/echo/v4"
 	"github.com/labstack/echo/v4/middleware"
 )
@@ -40,7 +39,7 @@ import (
 // API 结构体定义了 HTTP 服务器及其依赖
 type API struct {
 	echo                *echo.Echo                           // Echo 引擎实例，用于处理 HTTP 请求
-	logger              *logs.Logger                         // 日志记录器，用于输出日志信息
+	Ctx                 context.Context                      // API 组件的上下文，包含日志记录器
 	userRepo            repository.UserRepository            // 用户数据仓库接口，用于用户数据操作
 	tokenService        token.Service                        // Token 服务接口，用于 JWT token 的生成和解析
 	auditService        audit.Service                        // 审计服务，用于记录用户操作
@@ -59,7 +58,7 @@ type API struct {
 // NewAPI 创建并返回一个新的 API 实例
 // 负责初始化 Echo 引擎、设置全局中间件，并注入所有必要的依赖。
 func NewAPI(cfg config.ServerConfig,
-	logger *logs.Logger,
+	ctx context.Context,
 	userRepo repository.UserRepository,
 	pigFarmService service.PigFarmService,
 	pigBatchService service.PigBatchService,
@@ -82,26 +81,27 @@ func NewAPI(cfg config.ServerConfig,
 	e.Use(middleware.Recover())
 
 	// 初始化 API 结构体
+	baseCtx := context.Background()
 	api := &API{
 		echo:          e,
-		logger:        logger,
+		Ctx:           ctx,
 		userRepo:      userRepo,
 		tokenService:  tokenService,
 		auditService:  auditService,
 		config:        cfg,
 		listenHandler: listenHandler,
 		// 在 NewAPI 中初始化用户控制器，并将其作为 API 结构体的成员
-		userController: user.NewController(userService, logger),
+		userController: user.NewController(userService, baseCtx),
 		// 在 NewAPI 中初始化设备控制器，并将其作为 API 结构体的成员
-		deviceController: device.NewController(deviceService, logger),
+		deviceController: device.NewController(deviceService, baseCtx),
 		// 在 NewAPI 中初始化计划控制器，并将其作为 API 结构体的成员
-		planController: plan.NewController(logger, planService),
+		planController: plan.NewController(baseCtx, planService),
 		// 在 NewAPI 中初始化猪场管理控制器
-		pigFarmController: management.NewPigFarmController(logger, pigFarmService),
+		pigFarmController: management.NewPigFarmController(baseCtx, pigFarmService),
 		// 在 NewAPI 中初始化猪群控制器
-		pigBatchController: management.NewPigBatchController(logger, pigBatchService),
+		pigBatchController: management.NewPigBatchController(baseCtx, pigBatchService),
 		// 在 NewAPI 中初始化数据监控控制器
-		monitorController: monitor.NewController(monitorService, logger),
+		monitorController: monitor.NewController(monitorService, baseCtx),
 	}
 
 	api.setupRoutes() // 设置所有路由
@@ -112,6 +112,7 @@ func NewAPI(cfg config.ServerConfig,
 // 接收一个地址字符串 (例如 ":8080")，并在一个新的 goroutine 中启动服务器，
 // 以便主线程可以继续执行其他任务（例如监听操作系统信号）。
 func (a *API) Start() {
+	logger := logs.TraceLogger(a.Ctx, a.Ctx, "Start")
 	// 构建监听地址字符串
 	addr := fmt.Sprintf(":%d", a.config.Port)
 
@@ -126,18 +127,19 @@ func (a *API) Start() {
 	go func() {
 		// 启动服务器，并检查错误。http.ErrServerClosed 是正常关闭时的错误，无需处理。
 		if err := a.httpServer.ListenAndServe(); err != nil && err != http.ErrServerClosed {
-			a.logger.Fatalf("HTTP 服务器监听失败: %s", err)
+			logger.Fatalf("HTTP 服务器监听失败: %s", err)
 		}
 	}()
 	// 记录服务器已启动的信息
-	a.logger.Infof("HTTP 服务器正在监听 %s", addr)
+	logger.Infof("HTTP 服务器正在监听 %s", addr)
 }
 
 // Stop 优雅地停止 HTTP 服务器
 // 在停止服务器时，会给一个超时时间，确保正在处理的请求能够完成。
 func (a *API) Stop() {
+	logger := logs.TraceLogger(a.Ctx, a.Ctx, "Stop")
 	// 记录服务器正在关闭的信息
-	a.logger.Info("正在关闭 HTTP 服务器...")
+	logger.Info("正在关闭 HTTP 服务器...")
 
 	// 创建一个带有 5 秒超时时间的上下文
 	// 在此时间内，服务器会尝试完成所有活跃的连接。
@@ -148,8 +150,8 @@ func (a *API) Stop() {
 	// 如果在超时时间内未能关闭，Shutdown 会返回错误。
 	if err := a.httpServer.Shutdown(ctx); err != nil {
 		// 如果关闭失败，记录致命错误并退出
-		a.logger.Fatalf("HTTP 服务器关闭失败: %s", err)
+		logger.Fatalf("HTTP 服务器关闭失败: %s", err)
 	}
 	// 记录服务器已停止的信息
-	a.logger.Info("HTTP 服务器已停止。")
+	logger.Info("HTTP 服务器已停止。")
 }

internal/app/api/router.go

@@ -5,6 +5,7 @@ import (
 	"net/http/pprof"
 
 	"git.huangwc.com/pig/pig-farm-controller/internal/app/middleware"
+	"git.huangwc.com/pig/pig-farm-controller/internal/infra/logs"
 	"github.com/labstack/echo/v4"
 	echoSwagger "github.com/swaggo/echo-swagger"
 )
@@ -12,7 +13,7 @@ import (
 // setupRoutes 设置所有 API 路由
 // 在此方法中，使用已初始化的控制器实例将其路由注册到 Echo 引擎中。
 func (a *API) setupRoutes() {
-	a.logger.Info("开始初始化所有 API 路由")
+	logger := logs.TraceLogger(a.Ctx, a.Ctx, "SetupRoutes")
 
 	// --- Public Routes ---
 	// 这些路由不需要身份验证
@@ -20,7 +21,7 @@ func (a *API) setupRoutes() {
 	// 用户注册和登录
 	a.echo.POST("/api/v1/users", a.userController.CreateUser)  // 注册新用户
 	a.echo.POST("/api/v1/users/login", a.userController.Login) // 用户登录
-	a.logger.Debug("公开接口注册成功：用户注册、登录")
+	logger.Debug("公开接口注册成功：用户注册、登录")
 
 	// 注册 pprof 路由
 	pprofGroup := a.echo.Group("/debug/pprof")
@@ -38,15 +39,15 @@ func (a *API) setupRoutes() {
 		pprofGroup.GET("/mutex", echo.WrapHandler(pprof.Handler("mutex"))) // pprof 互斥锁
 		pprofGroup.GET("/threadcreate", echo.WrapHandler(pprof.Handler("threadcreate")))
 	}
-	a.logger.Debug("pprof 接口注册成功")
+	logger.Debug("pprof 接口注册成功")
 
 	// 上行事件监听路由
 	a.echo.POST("/upstream", echo.WrapHandler(a.listenHandler.Handler())) // 处理设备上行事件
-	a.logger.Debug("上行事件监听接口注册成功")
+	logger.Debug("上行事件监听接口注册成功")
 
 	// 添加 Swagger UI 路由, Swagger UI可在 /swagger/index.html 上找到
 	a.echo.GET("/swagger/*any", echoSwagger.WrapHandler) // Swagger UI 接口
-	a.logger.Debug("Swagger UI 接口注册成功")
+	logger.Debug("Swagger UI 接口注册成功")
 
 	// --- Authenticated Routes ---
 	// 所有在此注册的路由都需要通过 JWT 身份验证
@@ -59,7 +60,7 @@ func (a *API) setupRoutes() {
 		{
 			userGroup.POST("/:id/notifications/test", a.userController.SendTestNotification)
 		}
-		a.logger.Debug("用户相关接口注册成功 (需要认证和审计)")
+		logger.Debug("用户相关接口注册成功 (需要认证和审计)")
 
 		// 设备相关路由组
 		deviceGroup := authGroup.Group("/devices")
@@ -71,7 +72,7 @@ func (a *API) setupRoutes() {
 			deviceGroup.DELETE("/:id", a.deviceController.DeleteDevice)               // 删除设备
 			deviceGroup.POST("/manual-control/:id", a.deviceController.ManualControl) // 手动控制设备
 		}
-		a.logger.Debug("设备相关接口注册成功 (需要认证和审计)")
+		logger.Debug("设备相关接口注册成功 (需要认证和审计)")
 
 		// 区域主控相关路由组
 		areaControllerGroup := authGroup.Group("/area-controllers")
@@ -82,7 +83,7 @@ func (a *API) setupRoutes() {
 			areaControllerGroup.PUT("/:id", a.deviceController.UpdateAreaController)    // 更新区域主控
 			areaControllerGroup.DELETE("/:id", a.deviceController.DeleteAreaController) // 删除区域主控
 		}
-		a.logger.Debug("区域主控相关接口注册成功 (需要认证和审计)")
+		logger.Debug("区域主控相关接口注册成功 (需要认证和审计)")
 
 		// 设备模板相关路由组
 		deviceTemplateGroup := authGroup.Group("/device-templates")
@@ -93,7 +94,7 @@ func (a *API) setupRoutes() {
 			deviceTemplateGroup.PUT("/:id", a.deviceController.UpdateDeviceTemplate)    // 更新设备模板
 			deviceTemplateGroup.DELETE("/:id", a.deviceController.DeleteDeviceTemplate) // 删除设备模板
 		}
-		a.logger.Debug("设备模板相关接口注册成功 (需要认证和审计)")
+		logger.Debug("设备模板相关接口注册成功 (需要认证和审计)")
 
 		// 计划相关路由组
 		planGroup := authGroup.Group("/plans")
@@ -106,7 +107,7 @@ func (a *API) setupRoutes() {
 			planGroup.POST("/:id/start", a.planController.StartPlan) // 启动计划
 			planGroup.POST("/:id/stop", a.planController.StopPlan)   // 停止计划
 		}
-		a.logger.Debug("计划相关接口注册成功 (需要认证和审计)")
+		logger.Debug("计划相关接口注册成功 (需要认证和审计)")
 
 		// 猪舍相关路由组
 		pigHouseGroup := authGroup.Group("/pig-houses")
@@ -117,7 +118,7 @@ func (a *API) setupRoutes() {
 			pigHouseGroup.PUT("/:id", a.pigFarmController.UpdatePigHouse)    // 更新猪舍
 			pigHouseGroup.DELETE("/:id", a.pigFarmController.DeletePigHouse) // 删除猪舍
 		}
-		a.logger.Debug("猪舍相关接口注册成功 (需要认证和审计)")
+		logger.Debug("猪舍相关接口注册成功 (需要认证和审计)")
 
 		// 猪圈相关路由组
 		penGroup := authGroup.Group("/pens")
@@ -129,7 +130,7 @@ func (a *API) setupRoutes() {
 			penGroup.DELETE("/:id", a.pigFarmController.DeletePen)           // 删除猪圈
 			penGroup.PUT("/:id/status", a.pigFarmController.UpdatePenStatus) // 更新猪圈状态
 		}
-		a.logger.Debug("猪圈相关接口注册成功 (需要认证和审计)")
+		logger.Debug("猪圈相关接口注册成功 (需要认证和审计)")
 
 		// 猪群相关路由组
 		pigBatchGroup := authGroup.Group("/pig-batches")
@@ -154,7 +155,7 @@ func (a *API) setupRoutes() {
 			pigBatchGroup.POST("/record-death/:id", a.pigBatchController.RecordDeath)                                     // 记录正常猪只死亡事件
 			pigBatchGroup.POST("/record-cull/:id", a.pigBatchController.RecordCull)                                       // 记录正常猪只淘汰事件
 		}
-		a.logger.Debug("猪群相关接口注册成功 (需要认证和审计)")
+		logger.Debug("猪群相关接口注册成功 (需要认证和审计)")
 
 		// 数据监控相关路由组
 		monitorGroup := authGroup.Group("/monitor")
@@ -178,8 +179,8 @@ func (a *API) setupRoutes() {
 			monitorGroup.GET("/pig-sales", a.monitorController.ListPigSales)
 			monitorGroup.GET("/notifications", a.monitorController.ListNotifications)
 		}
-		a.logger.Debug("数据监控相关接口注册成功 (需要认证和审计)")
+		logger.Debug("数据监控相关接口注册成功 (需要认证和审计)")
 	}
 
-	a.logger.Debug("所有接口注册成功")
+	logger.Debug("所有接口注册成功")
 }

internal/core/application.go

@@ -49,6 +49,7 @@ func NewApplication(configPath string) (*Application, error) {
 	// 3. 初始化 API 入口点
 	apiServer := api.NewAPI(
 		cfg.Server,
+		logs.AddCompName(context.Background(), "API"),
 		infra.repos.userRepo,
 		appServices.pigFarmService,
 		appServices.pigBatchService,