diff --git a/backend/country/src/logic/create.go b/backend/country/src/logic/create.go index 90fcaf2..a156519 100644 --- a/backend/country/src/logic/create.go +++ b/backend/country/src/logic/create.go @@ -2,41 +2,46 @@ package logic import ( "net/http" - "country/db" - "time" - "github.com/google/uuid" - "github.com/gin-gonic/gin" - "go.uber.org/zap" + "country/db" // 数据库操作相关包 + "time" // 时间处理包 + "github.com/google/uuid" // UUID生成工具 + "github.com/gin-gonic/gin" // Gin框架,用于处理HTTP请求 + "go.uber.org/zap" // 日志库 ) // CreateRequest 注册请求参数结构 +// 用于接收客户端发送的JSON数据,绑定并验证必填字段 type CreateRequest struct { - Name string `json:"name" binding:"required"` - Code string `json:"code" binding:"required"` + Name string `json:"name" binding:"required"` // 国家名称,必填 + Code string `json:"code" binding:"required"` // 国家代码,必填 } // CreateResponse 注册响应结构 +// 统一的API响应格式,包含成功状态、提示信息和数据 type CreateResponse struct { - Success bool `json:"success"` - Message string `json:"message"` - Data CreateData `json:"data"` + Success bool `json:"success"` // 操作是否成功 + Message string `json:"message"` // 提示信息 + Data CreateData `json:"data"` // 响应数据 } // CreateData 响应数据结构 +// 包含创建成功后的国家ID type CreateData struct { - CountryID string `json:"country_id"` + CountryID string `json:"country_id"` // 国家唯一标识ID } // CreateHandler 处理国家创建逻辑 +// 接收HTTP请求,完成参数验证、数据库事务处理并返回响应 func CreateHandler(c *gin.Context) { - startTime := time.Now() + startTime := time.Now() // 记录请求开始时间,用于统计耗时 + // 获取或生成请求ID,用于追踪整个请求链路 reqID := c.Request.Header.Get("X-RegisterRequest-ID") if reqID == "" { reqID = uuid.New().String() zap.L().Debug("✨ 生成新的请求ID", zap.String("req_id", reqID)) } - // 标准化日志字段,增加请求路径和方法 + // 记录请求接收日志,包含关键追踪信息 zap.L().Info("📥 收到国家创建请求", zap.String("req_id", reqID), zap.String("path", c.Request.URL.Path), @@ -44,13 +49,14 @@ func CreateHandler(c *gin.Context) { ) var req CreateRequest - // 绑定并验证请求参数 + // 绑定并验证请求参数(检查name和code是否存在) if err := c.ShouldBindJSON(&req); err != nil { zap.L().Warn("⚠️ 请求参数验证失败", zap.String("req_id", reqID), zap.Error(err), zap.Any("request_body", c.Request.Body), ) + // 返回参数错误响应 c.JSON(http.StatusBadRequest, CreateResponse{ Success: false, Message: "请求参数错误:name和code为必填项", @@ -58,14 +64,14 @@ func CreateHandler(c *gin.Context) { return } - // 记录有效请求参数(敏感信息需脱敏,此处假设name和code非敏感) + // 记录通过验证的请求参数 zap.L().Debug("✅ 请求参数验证通过", zap.String("req_id", reqID), zap.String("name", req.Name), zap.String("code", req.Code), ) - // 开启事务(将事务提前,确保country表插入也在事务中) + // 开启数据库事务,确保多表操作原子性(要么全成功,要么全失败) tx, err := db.DB.Begin() if err != nil { zap.L().Error("❌ 事务开启失败", @@ -78,9 +84,10 @@ func CreateHandler(c *gin.Context) { }) return } + // 延迟执行的恢复函数,处理panic情况 defer func() { - // 发生panic时回滚事务 - if r := recover(); r != nil { + if r := recover(); r != nil { // 捕获panic + // 回滚事务 if err := tx.Rollback(); err != nil { zap.L().Error("💥 panic后事务回滚失败", zap.String("req_id", reqID), @@ -91,6 +98,7 @@ func CreateHandler(c *gin.Context) { zap.String("req_id", reqID), zap.Any("recover", r), ) + // 返回系统错误响应 c.JSON(http.StatusInternalServerError, CreateResponse{ Success: false, Message: "系统错误,请稍后重试", @@ -98,11 +106,11 @@ func CreateHandler(c *gin.Context) { } }() - // 在country表中创建记录并获取ID(纳入事务管理) + // 1. 在country表中创建记录并获取自动生成的ID var countryID string - err = tx.QueryRow("INSERT INTO \"country\" DEFAULT VALUES RETURNING id").Scan(&countryID) + err = tx.QueryRow("INSERT INTO country DEFAULT VALUES RETURNING id").Scan(&countryID) if err != nil { - tx.Rollback() + tx.Rollback() // 操作失败,回滚事务 zap.L().Error("❌ country表插入失败", zap.String("req_id", reqID), zap.Error(err), @@ -119,10 +127,10 @@ func CreateHandler(c *gin.Context) { zap.String("country_id", countryID), ) - // 插入name表 + // 2. 插入国家名称到name表(与country_id关联) _, err = tx.Exec("INSERT INTO name (country_id, name) VALUES ($1, $2)", countryID, req.Name) if err != nil { - tx.Rollback() + tx.Rollback() // 操作失败,回滚事务 zap.L().Error("❌ name表插入失败", zap.String("req_id", reqID), zap.String("country_id", countryID), @@ -135,10 +143,10 @@ func CreateHandler(c *gin.Context) { return } - // 插入code表 + // 3. 插入国家代码到code表(与country_id关联) _, err = tx.Exec("INSERT INTO code (country_id, code) VALUES ($1, $2)", countryID, req.Code) if err != nil { - tx.Rollback() + tx.Rollback() // 操作失败,回滚事务 zap.L().Error("❌ code表插入失败", zap.String("req_id", reqID), zap.String("country_id", countryID), @@ -151,9 +159,9 @@ func CreateHandler(c *gin.Context) { return } - // 提交事务 + // 提交事务(所有操作成功后确认提交) if err := tx.Commit(); err != nil { - tx.Rollback() // 尝试回滚提交失败的事务 + tx.Rollback() // 提交失败时尝试回滚 zap.L().Error("❌ 事务提交失败", zap.String("req_id", reqID), zap.String("country_id", countryID), @@ -174,7 +182,7 @@ func CreateHandler(c *gin.Context) { zap.Duration("duration", duration), ) - // 返回成功响应 + // 返回成功响应,包含创建的国家ID c.JSON(http.StatusOK, CreateResponse{ Success: true, Message: "创建成功",