add

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: "创建成功",