docs(constitution): 新增数据库设计原则(v2.4.0)

在项目宪章中新增第九条原则"数据库设计原则"，明确禁止使用数据库外键约束和ORM关联标签。主要变更： - 新增原则IX：数据库设计原则（Database Design Principles） - 强制要求：数据库表不得使用外键约束 - 强制要求：GORM模型不得使用ORM关联标签（foreignKey、hasMany等） - 强制要求：表关系必须通过ID字段手动维护 - 强制要求：关联数据查询必须显式编写，避免ORM魔法 - 强制要求：时间字段由GORM处理，不使用数据库触发器设计理念： - 提升业务逻辑灵活性（无数据库约束限制） - 优化高并发性能（无外键检查开销） - 增强代码可读性（显式查询，无隐式预加载） - 简化数据库架构和迁移流程 - 支持分布式和微服务场景版本升级：2.3.0 → 2.4.0（MINOR）
2025-11-13 13:40:19 +08:00
parent ea0c6a8b16
commit 984ccccc63
63 changed files with 12099 additions and 83 deletions
--- a/internal/handler/user.go
+++ b/internal/handler/user.go
@@ -1,33 +1,250 @@
 package handler

 import (
-	"github.com/gofiber/fiber/v2"
+	"strconv"

-	"github.com/break/junhong_cmp_fiber/pkg/constants"
+	"github.com/break/junhong_cmp_fiber/internal/model"
+	"github.com/break/junhong_cmp_fiber/internal/service/user"
+	"github.com/break/junhong_cmp_fiber/pkg/errors"
 	"github.com/break/junhong_cmp_fiber/pkg/response"
+	"github.com/go-playground/validator/v10"
+	"github.com/gofiber/fiber/v2"
+	"go.uber.org/zap"
 )

-// GetUsers 获取用户列表（示例受保护端点）
-func GetUsers(c *fiber.Ctx) error {
-	// 从上下文获取用户 ID（由 auth 中间件设置）
-	userID := c.Locals(constants.ContextKeyUserID)
+var validate = validator.New()

-	// 示例数据
-	users := []fiber.Map{
-		{
-			"id":    "user-123",
-			"name":  "张三",
-			"email": "zhangsan@example.com",
-		},
-		{
-			"id":    "user-456",
-			"name":  "李四",
-			"email": "lisi@example.com",
-		},
+// UserHandler 用户处理器
+type UserHandler struct {
+	userService *user.Service
+	logger      *zap.Logger
+}
+
+// NewUserHandler 创建用户处理器实例
+func NewUserHandler(userService *user.Service, logger *zap.Logger) *UserHandler {
+	return &UserHandler{
+		userService: userService,
+		logger:      logger,
+	}
+}
+
+// CreateUser 创建用户
+// POST /api/v1/users
+func (h *UserHandler) CreateUser(c *fiber.Ctx) error {
+	var req model.CreateUserRequest
+
+	// 解析请求体
+	if err := c.BodyParser(&req); err != nil {
+		h.logger.Warn("解析请求体失败",
+			zap.String("path", c.Path()),
+			zap.Error(err))
+		return response.Error(c, fiber.StatusBadRequest, errors.CodeBadRequest, "请求参数格式错误")
 	}

-	return response.SuccessWithMessage(c, fiber.Map{
-		"users":            users,
-		"authenticated_as": userID,
-	}, "success")
+	// 验证请求参数
+	if err := validate.Struct(&req); err != nil {
+		h.logger.Warn("参数验证失败",
+			zap.String("path", c.Path()),
+			zap.Any("request", req),
+			zap.Error(err))
+		return response.Error(c, fiber.StatusBadRequest, errors.CodeBadRequest, err.Error())
+	}
+
+	// 调用服务层创建用户
+	userResp, err := h.userService.CreateUser(c.Context(), &req)
+	if err != nil {
+		if e, ok := err.(*errors.AppError); ok {
+			return response.Error(c, fiber.StatusInternalServerError, e.Code, e.Message)
+		}
+		h.logger.Error("创建用户失败",
+			zap.String("username", req.Username),
+			zap.Error(err))
+		return response.Error(c, fiber.StatusInternalServerError, errors.CodeInternalError, "创建用户失败")
+	}
+
+	h.logger.Info("用户创建成功",
+		zap.Uint("user_id", userResp.ID),
+		zap.String("username", userResp.Username))
+
+	return response.Success(c, userResp)
+}
+
+// GetUser 获取用户详情
+// GET /api/v1/users/:id
+func (h *UserHandler) GetUser(c *fiber.Ctx) error {
+	// 获取路径参数
+	idStr := c.Params("id")
+	id, err := strconv.ParseUint(idStr, 10, 32)
+	if err != nil {
+		h.logger.Warn("用户ID格式错误",
+			zap.String("id", idStr),
+			zap.Error(err))
+		return response.Error(c, fiber.StatusBadRequest, errors.CodeBadRequest, "用户ID格式错误")
+	}
+
+	// 调用服务层获取用户
+	userResp, err := h.userService.GetUserByID(c.Context(), uint(id))
+	if err != nil {
+		if e, ok := err.(*errors.AppError); ok {
+			httpStatus := fiber.StatusInternalServerError
+			if e.Code == errors.CodeNotFound {
+				httpStatus = fiber.StatusNotFound
+			}
+			return response.Error(c, httpStatus, e.Code, e.Message)
+		}
+		h.logger.Error("获取用户失败",
+			zap.Uint("user_id", uint(id)),
+			zap.Error(err))
+		return response.Error(c, fiber.StatusInternalServerError, errors.CodeInternalError, "获取用户失败")
+	}
+
+	return response.Success(c, userResp)
+}
+
+// UpdateUser 更新用户信息
+// PUT /api/v1/users/:id
+func (h *UserHandler) UpdateUser(c *fiber.Ctx) error {
+	// 获取路径参数
+	idStr := c.Params("id")
+	id, err := strconv.ParseUint(idStr, 10, 32)
+	if err != nil {
+		h.logger.Warn("用户ID格式错误",
+			zap.String("id", idStr),
+			zap.Error(err))
+		return response.Error(c, fiber.StatusBadRequest, errors.CodeBadRequest, "用户ID格式错误")
+	}
+
+	var req model.UpdateUserRequest
+
+	// 解析请求体
+	if err := c.BodyParser(&req); err != nil {
+		h.logger.Warn("解析请求体失败",
+			zap.String("path", c.Path()),
+			zap.Error(err))
+		return response.Error(c, fiber.StatusBadRequest, errors.CodeBadRequest, "请求参数格式错误")
+	}
+
+	// 验证请求参数
+	if err := validate.Struct(&req); err != nil {
+		h.logger.Warn("参数验证失败",
+			zap.String("path", c.Path()),
+			zap.Any("request", req),
+			zap.Error(err))
+		return response.Error(c, fiber.StatusBadRequest, errors.CodeBadRequest, err.Error())
+	}
+
+	// 调用服务层更新用户
+	userResp, err := h.userService.UpdateUser(c.Context(), uint(id), &req)
+	if err != nil {
+		if e, ok := err.(*errors.AppError); ok {
+			httpStatus := fiber.StatusInternalServerError
+			if e.Code == errors.CodeNotFound {
+				httpStatus = fiber.StatusNotFound
+			}
+			return response.Error(c, httpStatus, e.Code, e.Message)
+		}
+		h.logger.Error("更新用户失败",
+			zap.Uint("user_id", uint(id)),
+			zap.Error(err))
+		return response.Error(c, fiber.StatusInternalServerError, errors.CodeInternalError, "更新用户失败")
+	}
+
+	h.logger.Info("用户更新成功",
+		zap.Uint("user_id", uint(id)))
+
+	return response.Success(c, userResp)
+}
+
+// DeleteUser 删除用户（软删除）
+// DELETE /api/v1/users/:id
+func (h *UserHandler) DeleteUser(c *fiber.Ctx) error {
+	// 获取路径参数
+	idStr := c.Params("id")
+	id, err := strconv.ParseUint(idStr, 10, 32)
+	if err != nil {
+		h.logger.Warn("用户ID格式错误",
+			zap.String("id", idStr),
+			zap.Error(err))
+		return response.Error(c, fiber.StatusBadRequest, errors.CodeBadRequest, "用户ID格式错误")
+	}
+
+	// 调用服务层删除用户
+	if err := h.userService.DeleteUser(c.Context(), uint(id)); err != nil {
+		if e, ok := err.(*errors.AppError); ok {
+			httpStatus := fiber.StatusInternalServerError
+			if e.Code == errors.CodeNotFound {
+				httpStatus = fiber.StatusNotFound
+			}
+			return response.Error(c, httpStatus, e.Code, e.Message)
+		}
+		h.logger.Error("删除用户失败",
+			zap.Uint("user_id", uint(id)),
+			zap.Error(err))
+		return response.Error(c, fiber.StatusInternalServerError, errors.CodeInternalError, "删除用户失败")
+	}
+
+	h.logger.Info("用户删除成功",
+		zap.Uint("user_id", uint(id)))
+
+	return response.Success(c, nil)
+}
+
+// ListUsers 获取用户列表（分页）
+// GET /api/v1/users
+func (h *UserHandler) ListUsers(c *fiber.Ctx) error {
+	// 获取查询参数
+	page, err := strconv.Atoi(c.Query("page", "1"))
+	if err != nil || page < 1 {
+		page = 1
+	}
+
+	pageSize, err := strconv.Atoi(c.Query("page_size", "20"))
+	if err != nil || pageSize < 1 {
+		pageSize = 20
+	}
+	if pageSize > 100 {
+		pageSize = 100 // 限制最大页大小
+	}
+
+	// 调用服务层获取用户列表
+	users, total, err := h.userService.ListUsers(c.Context(), page, pageSize)
+	if err != nil {
+		if e, ok := err.(*errors.AppError); ok {
+			return response.Error(c, fiber.StatusInternalServerError, e.Code, e.Message)
+		}
+		h.logger.Error("获取用户列表失败",
+			zap.Int("page", page),
+			zap.Int("page_size", pageSize),
+			zap.Error(err))
+		return response.Error(c, fiber.StatusInternalServerError, errors.CodeInternalError, "获取用户列表失败")
+	}
+
+	// 构造响应
+	totalPages := int(total) / pageSize
+	if int(total)%pageSize > 0 {
+		totalPages++
+	}
+
+	listResp := model.ListUsersResponse{
+		Users:      make([]model.UserResponse, 0, len(users)),
+		Page:       page,
+		PageSize:   pageSize,
+		Total:      total,
+		TotalPages: totalPages,
+	}
+
+	// 转换为响应格式
+	for _, u := range users {
+		listResp.Users = append(listResp.Users, model.UserResponse{
+			ID:          u.ID,
+			Username:    u.Username,
+			Email:       u.Email,
+			Status:      u.Status,
+			CreatedAt:   u.CreatedAt,
+			UpdatedAt:   u.UpdatedAt,
+			LastLoginAt: u.LastLoginAt,
+		})
+	}
+
+	return response.Success(c, listResp)
 }