package api // @title 猪场管理系统 API // @version 1.0 // @description 这是一个用于管理猪场设备的后端服务。 // @contact.name Divano // @contact.url http://www.example.com // @contact.email divano@example.com // @license.name Apache 2.0 // @license.url http://www.apache.org/licenses/LICENSE-2.0.html // @securityDefinitions.apikey BearerAuth // @in header // @name Authorization import ( "context" "fmt" "net/http" "net/http/pprof" "time" _ "git.huangwc.com/pig/pig-farm-controller/docs" // 引入 swag 生成的 docs "git.huangwc.com/pig/pig-farm-controller/internal/app/controller/device" "git.huangwc.com/pig/pig-farm-controller/internal/app/controller/management" "git.huangwc.com/pig/pig-farm-controller/internal/app/controller/plan" "git.huangwc.com/pig/pig-farm-controller/internal/app/controller/user" "git.huangwc.com/pig/pig-farm-controller/internal/app/middleware" "git.huangwc.com/pig/pig-farm-controller/internal/app/service" "git.huangwc.com/pig/pig-farm-controller/internal/app/webhook" "git.huangwc.com/pig/pig-farm-controller/internal/domain/audit" domain_device "git.huangwc.com/pig/pig-farm-controller/internal/domain/device" "git.huangwc.com/pig/pig-farm-controller/internal/domain/task" "git.huangwc.com/pig/pig-farm-controller/internal/domain/token" "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/gin-gonic/gin" swaggerFiles "github.com/swaggo/files" ginSwagger "github.com/swaggo/gin-swagger" ) // API 结构体定义了 HTTP 服务器及其依赖 type API struct { engine *gin.Engine // Gin 引擎实例，用于处理 HTTP 请求 logger *logs.Logger // 日志记录器，用于输出日志信息 userRepo repository.UserRepository // 用户数据仓库接口，用于用户数据操作 tokenService token.TokenService // Token 服务接口，用于 JWT token 的生成和解析 auditService audit.Service // 审计服务，用于记录用户操作 httpServer *http.Server // 标准库的 HTTP 服务器实例，用于启动和停止服务 config config.ServerConfig // API 服务器的配置，使用 infra/config 包中的 ServerConfig userController *user.Controller // 用户控制器实例 deviceController *device.Controller // 设备控制器实例 planController *plan.Controller // 计划控制器实例 pigFarmController *management.PigFarmController // 猪场管理控制器实例 pigBatchController *management.PigBatchController // 猪群控制器实例 listenHandler webhook.ListenHandler // 设备上行事件监听器 analysisTaskManager *task.AnalysisPlanTaskManager // 计划触发器管理器实例 } // NewAPI 创建并返回一个新的 API 实例 // 负责初始化 Gin 引擎、设置全局中间件，并注入所有必要的依赖。 func NewAPI(cfg config.ServerConfig, logger *logs.Logger, userRepo repository.UserRepository, deviceRepository repository.DeviceRepository, areaControllerRepository repository.AreaControllerRepository, deviceTemplateRepository repository.DeviceTemplateRepository, planRepository repository.PlanRepository, pigFarmService service.PigFarmService, pigBatchService service.PigBatchService, userActionLogRepository repository.UserActionLogRepository, tokenService token.TokenService, auditService audit.Service, deviceService domain_device.Service, listenHandler webhook.ListenHandler, analysisTaskManager *task.AnalysisPlanTaskManager) *API { // 设置 Gin 模式，例如 gin.ReleaseMode (生产模式) 或 gin.DebugMode (开发模式) // 从配置中获取 Gin 模式 gin.SetMode(cfg.Mode) // 使用 gin.New() 创建一个 Gin 引擎实例，而不是 gin.Default() // 这样可以手动添加所需的中间件，避免 gin.Default() 默认包含的 Logger 和 Recovery 中间件 engine := gin.New() // 添加 Gin Recovery 中间件，用于捕获 panic 并恢复，防止服务崩溃 // gin.Logger() 已移除，因为我们使用自定义的 logger engine.Use(gin.Recovery()) // 初始化 API 结构体 api := &API{ engine: engine, logger: logger, userRepo: userRepo, tokenService: tokenService, auditService: auditService, config: cfg, listenHandler: listenHandler, // 在 NewAPI 中初始化用户控制器，并将其作为 API 结构体的成员 userController: user.NewController(userRepo, userActionLogRepository, logger, tokenService), // 在 NewAPI 中初始化设备控制器，并将其作为 API 结构体的成员 deviceController: device.NewController(deviceRepository, areaControllerRepository, deviceTemplateRepository, deviceService, logger), // 在 NewAPI 中初始化计划控制器，并将其作为 API 结构体的成员 planController: plan.NewController(logger, planRepository, analysisTaskManager), // 在 NewAPI 中初始化猪场管理控制器 pigFarmController: management.NewPigFarmController(logger, pigFarmService), // 在 NewAPI 中初始化猪群控制器 pigBatchController: management.NewPigBatchController(logger, pigBatchService), } api.setupRoutes() // 设置所有路由 return api } // setupRoutes 设置所有 API 路由 // 在此方法中，使用已初始化的控制器实例将其路由注册到 Gin 引擎中。 func (a *API) setupRoutes() { // --- Public Routes --- // 这些路由不需要身份验证 // 用户注册和登录 a.engine.POST("/api/v1/users", a.userController.CreateUser) // 注册新用户 a.engine.POST("/api/v1/users/login", a.userController.Login) // 用户登录 a.logger.Info("公开接口注册成功：用户注册、登录") // 注册 pprof 路由 pprofGroup := a.engine.Group("/debug/pprof") { pprofGroup.GET("/", gin.WrapF(pprof.Index)) // pprof 索引页 pprofGroup.GET("/cmdline", gin.WrapF(pprof.Cmdline)) // pprof 命令行参数 pprofGroup.GET("/profile", gin.WrapF(pprof.Profile)) // pprof CPU profile pprofGroup.POST("/symbol", gin.WrapF(pprof.Symbol)) // pprof 符号查找 (POST) pprofGroup.GET("/symbol", gin.WrapF(pprof.Symbol)) // pprof 符号查找 (GET) pprofGroup.GET("/trace", gin.WrapF(pprof.Trace)) // pprof 跟踪 pprofGroup.GET("/allocs", gin.WrapH(pprof.Handler("allocs"))) // pprof 内存分配 pprofGroup.GET("/block", gin.WrapH(pprof.Handler("block"))) // pprof 阻塞 pprofGroup.GET("/goroutine", gin.WrapH(pprof.Handler("goroutine"))) pprofGroup.GET("/heap", gin.WrapH(pprof.Handler("heap"))) // pprof 堆内存 pprofGroup.GET("/mutex", gin.WrapH(pprof.Handler("mutex"))) // pprof 互斥锁 pprofGroup.GET("/threadcreate", gin.WrapH(pprof.Handler("threadcreate"))) } a.logger.Info("pprof 接口注册成功") // 上行事件监听路由 a.engine.POST("/upstream", gin.WrapH(a.listenHandler.Handler())) // 处理设备上行事件 a.logger.Info("上行事件监听接口注册成功") // 添加 Swagger UI 路由, Swagger UI可在 /swagger/index.html 上找到 a.engine.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler)) // Swagger UI 接口 a.logger.Info("Swagger UI 接口注册成功") // --- Authenticated Routes --- // 所有在此注册的路由都需要通过 JWT 身份验证 authGroup := a.engine.Group("/api/v1") authGroup.Use(middleware.AuthMiddleware(a.tokenService, a.userRepo)) // 1. 身份认证中间件 authGroup.Use(middleware.AuditLogMiddleware(a.auditService)) // 2. 审计日志中间件 { // 用户相关路由组 userGroup := authGroup.Group("/users") { userGroup.GET("/:id/history", a.userController.ListUserHistory) // 获取用户操作历史 } a.logger.Info("用户相关接口注册成功 (需要认证和审计)") // 设备相关路由组 deviceGroup := authGroup.Group("/devices") { deviceGroup.POST("", a.deviceController.CreateDevice) // 创建设备 deviceGroup.GET("", a.deviceController.ListDevices) // 获取设备列表 deviceGroup.GET("/:id", a.deviceController.GetDevice) // 获取单个设备 deviceGroup.PUT("/:id", a.deviceController.UpdateDevice) // 更新设备 deviceGroup.DELETE("/:id", a.deviceController.DeleteDevice) // 删除设备 deviceGroup.POST("/manual-control/:id", a.deviceController.ManualControl) // 手动控制设备 } a.logger.Info("设备相关接口注册成功 (需要认证和审计)") // 区域主控相关路由组 areaControllerGroup := authGroup.Group("/area-controllers") { areaControllerGroup.POST("", a.deviceController.CreateAreaController) // 创建区域主控 areaControllerGroup.GET("", a.deviceController.ListAreaControllers) // 获取区域主控列表 areaControllerGroup.GET("/:id", a.deviceController.GetAreaController) // 获取单个区域主控 areaControllerGroup.PUT("/:id", a.deviceController.UpdateAreaController) // 更新区域主控 areaControllerGroup.DELETE("/:id", a.deviceController.DeleteAreaController) // 删除区域主控 } a.logger.Info("区域主控相关接口注册成功 (需要认证和审计)") // 设备模板相关路由组 deviceTemplateGroup := authGroup.Group("/device-templates") { deviceTemplateGroup.POST("", a.deviceController.CreateDeviceTemplate) // 创建设备模板 deviceTemplateGroup.GET("", a.deviceController.ListDeviceTemplates) // 获取设备模板列表 deviceTemplateGroup.GET("/:id", a.deviceController.GetDeviceTemplate) // 获取单个设备模板 deviceTemplateGroup.PUT("/:id", a.deviceController.UpdateDeviceTemplate) // 更新设备模板 deviceTemplateGroup.DELETE("/:id", a.deviceController.DeleteDeviceTemplate) // 删除设备模板 } a.logger.Info("设备模板相关接口注册成功 (需要认证和审计)") // 计划相关路由组 planGroup := authGroup.Group("/plans") { planGroup.POST("", a.planController.CreatePlan) // 创建计划 planGroup.GET("", a.planController.ListPlans) // 获取计划列表 planGroup.GET("/:id", a.planController.GetPlan) // 获取单个计划 planGroup.PUT("/:id", a.planController.UpdatePlan) // 更新计划 planGroup.DELETE("/:id", a.planController.DeletePlan) // 删除计划 planGroup.POST("/:id/start", a.planController.StartPlan) // 启动计划 planGroup.POST("/:id/stop", a.planController.StopPlan) // 停止计划 } a.logger.Info("计划相关接口注册成功 (需要认证和审计)") // 猪舍相关路由组 pigHouseGroup := authGroup.Group("/pig-houses") { pigHouseGroup.POST("", a.pigFarmController.CreatePigHouse) // 创建猪舍 pigHouseGroup.GET("", a.pigFarmController.ListPigHouses) // 获取猪舍列表 pigHouseGroup.GET("/:id", a.pigFarmController.GetPigHouse) // 获取单个猪舍 pigHouseGroup.PUT("/:id", a.pigFarmController.UpdatePigHouse) // 更新猪舍 pigHouseGroup.DELETE("/:id", a.pigFarmController.DeletePigHouse) // 删除猪舍 } a.logger.Info("猪舍相关接口注册成功 (需要认证和审计)") // 猪圈相关路由组 penGroup := authGroup.Group("/pens") { penGroup.POST("", a.pigFarmController.CreatePen) // 创建猪圈 penGroup.GET("", a.pigFarmController.ListPens) // 获取猪圈列表 penGroup.GET("/:id", a.pigFarmController.GetPen) // 获取单个猪圈 penGroup.PUT("/:id", a.pigFarmController.UpdatePen) // 更新猪圈 penGroup.DELETE("/:id", a.pigFarmController.DeletePen) // 删除猪圈 penGroup.PUT("/:id/status", a.pigFarmController.UpdatePenStatus) // 更新猪圈状态 } a.logger.Info("猪圈相关接口注册成功 (需要认证和审计)") // 猪群相关路由组 pigBatchGroup := authGroup.Group("/pig-batches") { pigBatchGroup.POST("", a.pigBatchController.CreatePigBatch) // 创建猪群 pigBatchGroup.GET("", a.pigBatchController.ListPigBatches) // 获取猪群列表 pigBatchGroup.GET("/:id", a.pigBatchController.GetPigBatch) // 获取单个猪群 pigBatchGroup.PUT("/:id", a.pigBatchController.UpdatePigBatch) // 更新猪群 pigBatchGroup.DELETE("/:id", a.pigBatchController.DeletePigBatch) // 删除猪群 pigBatchGroup.POST("/assign-pens/:id", a.pigBatchController.AssignEmptyPensToBatch) // 为猪群分配空栏 pigBatchGroup.POST("/reclassify-pen/:fromBatchID", a.pigBatchController.ReclassifyPenToNewBatch) // 将猪栏划拨到新群 penGroup.DELETE("/remove-pen/:penID/:batchID", a.pigBatchController.RemoveEmptyPenFromBatch) // 从猪群移除空栏 pigBatchGroup.POST("/move-pigs-into-pen/:id", a.pigBatchController.MovePigsIntoPen) // 将猪只从“虚拟库存”移入指定猪栏 pigBatchGroup.POST("/sell-pigs/:id", a.pigBatchController.SellPigs) // 处理卖猪业务 pigBatchGroup.POST("/buy-pigs/:id", a.pigBatchController.BuyPigs) // 处理买猪业务 pigBatchGroup.POST("/transfer-across-batches/:sourceBatchID", a.pigBatchController.TransferPigsAcrossBatches) // 跨猪群调栏 pigBatchGroup.POST("/transfer-within-batch/:id", a.pigBatchController.TransferPigsWithinBatch) // 群内调栏 pigBatchGroup.POST("/record-sick-pigs/:id", a.pigBatchController.RecordSickPigs) // 记录新增病猪事件 pigBatchGroup.POST("/record-sick-pig-recovery/:id", a.pigBatchController.RecordSickPigRecovery) // 记录病猪康复事件 pigBatchGroup.POST("/record-sick-pig-death/:id", a.pigBatchController.RecordSickPigDeath) // 记录病猪死亡事件 pigBatchGroup.POST("/record-sick-pig-cull/:id", a.pigBatchController.RecordSickPigCull) // 记录病猪淘汰事件 pigBatchGroup.POST("/record-death/:id", a.pigBatchController.RecordDeath) // 记录正常猪只死亡事件 pigBatchGroup.POST("/record-cull/:id", a.pigBatchController.RecordCull) // 记录正常猪只淘汰事件 } a.logger.Info("猪群相关接口注册成功 (需要认证和审计)") } } // Start 启动 HTTP 服务器 // 接收一个地址字符串 (例如 ":8080")，并在一个新的 goroutine 中启动服务器， // 以便主线程可以继续执行其他任务（例如监听操作系统信号）。 func (a *API) Start() { // 构建监听地址字符串 addr := fmt.Sprintf(":%d", a.config.Port) // 初始化标准库的 http.Server 实例 a.httpServer = &http.Server{ Addr: addr, // 服务器监听的地址从配置中获取 Handler: a.engine, // 将 Gin 引擎作为 HTTP 请求的处理程序 } // 在独立的 goroutine 中启动服务器 // ListenAndServe 会阻塞，所以放在 goroutine 中可以避免阻塞主线程 go func() { // 启动服务器，并检查错误。http.ErrServerClosed 是正常关闭时的错误，无需处理。 if err := a.httpServer.ListenAndServe(); err != nil && err != http.ErrServerClosed { a.logger.Fatalf("HTTP 服务器监听失败: %s", err) } }() // 记录服务器已启动的信息 a.logger.Infof("HTTP 服务器正在监听 %s", addr) } // Stop 优雅地停止 HTTP 服务器 // 在停止服务器时，会给一个超时时间，确保正在处理的请求能够完成。 func (a *API) Stop() { // 记录服务器正在关闭的信息 a.logger.Info("正在关闭 HTTP 服务器...") // 创建一个带有 5 秒超时时间的上下文 // 在此时间内，服务器会尝试完成所有活跃的连接。 ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second) defer cancel() // 确保上下文在函数退出时被取消，释放资源 // 尝试优雅地关闭 HTTP 服务器 // 如果在超时时间内未能关闭，Shutdown 会返回错误。 if err := a.httpServer.Shutdown(ctx); err != nil { // 如果关闭失败，记录致命错误并退出 a.logger.Fatalf("HTTP 服务器关闭失败: %s", err) } // 记录服务器已停止的信息 a.logger.Info("HTTP 服务器已停止。") }