tyapi-server/internal/shared/interfaces/http.go

package interfaces

import (
	"context"
	"net/http"

	"github.com/gin-gonic/gin"
	"github.com/go-playground/validator/v10"
)

// HTTPHandler HTTP处理器接口
type HTTPHandler interface {
	// 处理器信息
	GetPath() string
	GetMethod() string
	GetMiddlewares() []gin.HandlerFunc

	// 处理函数
	Handle(c *gin.Context)

	// 权限验证
	RequiresAuth() bool
	GetPermissions() []string
}

// RESTHandler REST风格处理器接口
type RESTHandler interface {
	HTTPHandler

	// CRUD操作
	Create(c *gin.Context)
	GetByID(c *gin.Context)
	Update(c *gin.Context)
	Delete(c *gin.Context)
	List(c *gin.Context)
}

// Middleware 中间件接口
type Middleware interface {
	// 中间件名称
	GetName() string
	// 中间件优先级
	GetPriority() int
	// 中间件处理函数
	Handle() gin.HandlerFunc
	// 是否全局中间件
	IsGlobal() bool
}

// Router 路由器接口
type Router interface {
	// 路由注册
	RegisterHandler(handler HTTPHandler) error
	RegisterMiddleware(middleware Middleware) error
	RegisterGroup(prefix string, middlewares ...gin.HandlerFunc) gin.IRoutes

	// 路由管理
	GetRoutes() gin.RoutesInfo
	Start(addr string) error
	Stop(ctx context.Context) error

	// 引擎获取
	GetEngine() *gin.Engine
}

// ResponseBuilder 响应构建器接口
type ResponseBuilder interface {
	// 成功响应
	Success(c *gin.Context, data interface{}, message ...string)
	Created(c *gin.Context, data interface{}, message ...string)

	// 错误响应
	Error(c *gin.Context, err error)
	BadRequest(c *gin.Context, message string, errors ...interface{})
	Unauthorized(c *gin.Context, message ...string)
	Forbidden(c *gin.Context, message ...string)
	NotFound(c *gin.Context, message ...string)
	Conflict(c *gin.Context, message string)
	InternalError(c *gin.Context, message ...string)
	ValidationError(c *gin.Context, errors interface{})
	TooManyRequests(c *gin.Context, message ...string)

	// 分页响应
	Paginated(c *gin.Context, data interface{}, pagination PaginationMeta)

	// 自定义响应
	CustomResponse(c *gin.Context, statusCode int, data interface{})
}

// RequestValidator 请求验证器接口
type RequestValidator interface {
	// 验证请求
	Validate(c *gin.Context, dto interface{}) error
	ValidateQuery(c *gin.Context, dto interface{}) error
	ValidateParam(c *gin.Context, dto interface{}) error

	// 绑定和验证
	BindAndValidate(c *gin.Context, dto interface{}) error

	// 业务逻辑验证方法
	GetValidator() *validator.Validate
	ValidateValue(field interface{}, tag string) error
	ValidateStruct(s interface{}) error
}

// PaginationMeta 分页元数据
type PaginationMeta struct {
	Page       int   `json:"page"`
	PageSize   int   `json:"page_size"`
	Total      int64 `json:"total"`
	TotalPages int   `json:"total_pages"`
	HasNext    bool  `json:"has_next"`
	HasPrev    bool  `json:"has_prev"`
}

// APIResponse 标准API响应结构
type APIResponse struct {
	Success    bool                   `json:"success"`
	Message    string                 `json:"message"`
	Data       interface{}            `json:"data,omitempty"`
	Errors     interface{}            `json:"errors,omitempty"`
	Pagination *PaginationMeta        `json:"pagination,omitempty"`
	Meta       map[string]interface{} `json:"meta,omitempty"`
	RequestID  string                 `json:"request_id"`
	Timestamp  int64                  `json:"timestamp"`
}

// HealthChecker 健康检查器接口
type HealthChecker interface {
	// 健康检查
	CheckHealth(ctx context.Context) HealthStatus
	GetName() string
	GetDependencies() []string
}

// HealthStatus 健康状态
type HealthStatus struct {
	Status       string                 `json:"status"` // UP, DOWN, DEGRADED
	Message      string                 `json:"message"`
	Details      map[string]interface{} `json:"details"`
	CheckedAt    int64                  `json:"checked_at"`
	ResponseTime int64                  `json:"response_time_ms"`
}

// MetricsCollector 指标收集器接口
type MetricsCollector interface {
	// HTTP指标
	RecordHTTPRequest(method, path string, status int, duration float64)
	RecordHTTPDuration(method, path string, duration float64)

	// 业务指标
	IncrementCounter(name string, labels map[string]string)
	RecordGauge(name string, value float64, labels map[string]string)
	RecordHistogram(name string, value float64, labels map[string]string)

	// 自定义指标
	RegisterCounter(name, help string, labels []string) error
	RegisterGauge(name, help string, labels []string) error
	RegisterHistogram(name, help string, labels []string, buckets []float64) error

	// 指标导出
	GetHandler() http.Handler
}