Initial commit: Basic project structure and dependencies

internal/shared/interfaces/http.go

@@ -0,0 +1,152 @@
+package interfaces
+
+import (
+	"context"
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+)
+
+// 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)
+
+	// 分页响应
+	Paginated(c *gin.Context, data interface{}, pagination PaginationMeta)
+}
+
+// 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
+}
+
+// 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
+}