pig-farm-controller/internal/app/controller/response.go

package controller

import (
	"net/http"

	"git.huangwc.com/pig/pig-farm-controller/internal/infra/models"
	"github.com/labstack/echo/v4"
)

// --- 业务状态码 ---
type ResponseCode int

const (
	// 成功状态码 (2000-2999)
	CodeSuccess ResponseCode = 2000 // 操作成功
	CodeCreated ResponseCode = 2001 // 创建成功

	// 客户端错误状态码 (4000-4999)
	CodeBadRequest   ResponseCode = 4000 // 请求参数错误
	CodeUnauthorized ResponseCode = 4001 // 未授权
	CodeForbidden    ResponseCode = 4003 // 禁止访问
	CodeNotFound     ResponseCode = 4004 // 资源未找到
	CodeConflict     ResponseCode = 4009 // 资源冲突

	// 服务器错误状态码 (5000-5999)
	CodeInternalError      ResponseCode = 5000 // 服务器内部错误
	CodeServiceUnavailable ResponseCode = 5003 // 服务不可用
)

// --- 通用响应结构 ---

// Response 定义统一的API响应结构体
type Response struct {
	Code    ResponseCode `json:"code"`           // 业务状态码
	Message string       `json:"message"`        // 提示信息
	Data    interface{}  `json:"data,omitempty"` // 业务数据, omitempty表示如果为空则不序列化
}

// SendResponse 发送统一格式的JSON响应 (基础函数，不带审计)
// 所有的业务API都应该使用这个函数返回，以确保HTTP状态码始终为200 OK。
func SendResponse(c echo.Context, code ResponseCode, message string, data interface{}) error {
	return c.JSON(http.StatusOK, Response{
		Code:    code,
		Message: message,
		Data:    data,
	})
}

// SendErrorResponse 发送统一格式的错误响应 (基础函数，不带审计)
// HTTP状态码为200 OK，通过业务码表示错误。
func SendErrorResponse(c echo.Context, code ResponseCode, message string) error {
	return SendResponse(c, code, message, nil)
}

// SendErrorWithStatus 发送带有指定HTTP状态码的错误响应。
// 这个函数主要用于中间件或特殊场景（如认证失败），在这些场景下需要返回非200的HTTP状态码。
func SendErrorWithStatus(c echo.Context, httpStatus int, code ResponseCode, message string) error {
	return c.JSON(httpStatus, Response{
		Code:    code,
		Message: message,
	})
}

// --- 带审计功能的响应函数 ---

// setAuditDetails 是一个内部辅助函数，用于在 echo.Context 中统一设置所有业务相关的审计信息。
func setAuditDetails(c echo.Context, actionType, description string, targetResource interface{}, status models.AuditStatus, resultDetails string) {
	// 只有当 actionType 不为空时，才设置审计信息，这作为触发审计的标志
	if actionType != "" {
		c.Set(models.ContextAuditActionType.String(), actionType)
		c.Set(models.ContextAuditDescription.String(), description)
		c.Set(models.ContextAuditTargetResource.String(), targetResource)
		c.Set(models.ContextAuditStatus.String(), status)
		c.Set(models.ContextAuditResultDetails.String(), resultDetails)
	}
}

// SendSuccessWithAudit 发送成功的响应，并设置审计日志所需的信息。
// 这是控制器中用于记录成功操作并返回响应的首选函数。
func SendSuccessWithAudit(
	c echo.Context, // Echo上下文，用于处理HTTP请求和响应
	code ResponseCode, // 业务状态码，表示操作结果
	message string, // 提示信息，向用户展示操作结果的文本描述
	data interface{}, // 业务数据，操作成功后返回的具体数据
	actionType string, // 审计操作类型，例如"创建用户", "更新配置"
	description string, // 审计描述，对操作的详细说明
	targetResource interface{}, // 审计目标资源，被操作的资源对象或其标识
) error {
	// 1. 设置审计信息
	setAuditDetails(c, actionType, description, targetResource, models.AuditStatusSuccess, "")
	// 2. 发送响应
	return SendResponse(c, code, message, data)
}

// SendErrorWithAudit 发送失败的响应，并设置审计日志所需的信息。
// 这是控制器中用于记录失败操作并返回响应的首选函数。
func SendErrorWithAudit(
	c echo.Context, // Echo上下文，用于处理HTTP请求和响应
	code ResponseCode, // 业务状态码，表示操作结果
	message string, // 提示信息，向用户展示操作结果的文本描述
	actionType string, // 审计操作类型，例如"登录失败", "删除失败"
	description string, // 审计描述，对操作的详细说明
	targetResource interface{}, // 审计目标资源，被操作的资源对象或其标识
) error {
	// 1. 设置审计信息
	setAuditDetails(c, actionType, description, targetResource, models.AuditStatusFailed, message)
	// 2. 发送响应
	return SendErrorResponse(c, code, message)
}