iriver/photography

Fork 0

Files

xujiang 604b9e59ba fix

2025-07-10 18:09:11 +08:00

16 KiB

Raw Blame History

HTTP 接口层 - CLAUDE.md

本文件为 Claude Code 在 HTTP 接口层模块中工作时提供指导。

🎯 模块概览

HTTP 接口层负责处理所有 HTTP 请求，包括路由定义、请求处理、响应格式化、中间件管理等。

职责范围

🌐 HTTP 路由定义和管理
📝 请求处理和响应格式化
🛡️ 中间件管理和应用
✅ 请求参数验证
📊 HTTP 状态码管理

文件结构

internal/api/
├── CLAUDE.md           # 📋 当前文件 - API 接口指导
├── handlers/           # 🎯 HTTP 处理器
│   ├── user.go         # 用户相关处理器
│   ├── photo.go        # 照片相关处理器
│   ├── category.go     # 分类相关处理器
│   ├── tag.go          # 标签相关处理器
│   ├── auth.go         # 认证相关处理器
│   ├── upload.go       # 上传相关处理器
│   └── health.go       # 健康检查处理器
├── middleware/         # 🛡️ 中间件
│   ├── auth.go         # 认证中间件
│   ├── cors.go         # CORS 中间件
│   ├── logger.go       # 日志中间件
│   ├── rate_limit.go   # 限流中间件
│   ├── recovery.go     # 错误恢复中间件
│   └── validator.go    # 验证中间件
├── routes/             # 🗺️ 路由定义
│   ├── v1.go           # API v1 路由
│   ├── auth.go         # 认证路由
│   ├── public.go       # 公共路由
│   └── admin.go        # 管理员路由
└── validators/         # ✅ 请求验证器
    ├── user.go         # 用户验证器
    ├── photo.go        # 照片验证器
    ├── category.go     # 分类验证器
    └── common.go       # 通用验证器

🎯 处理器模式

标准处理器结构

type UserHandler struct {
    userService service.UserServiceInterface
    logger      *zap.Logger
}

func NewUserHandler(userService service.UserServiceInterface, logger *zap.Logger) *UserHandler {
    return &UserHandler{
        userService: userService,
        logger:      logger,
    }
}

// 创建用户
func (h *UserHandler) Create(c *gin.Context) {
    var req validators.CreateUserRequest
    if err := c.ShouldBindJSON(&req); err != nil {
        response.Error(c, http.StatusBadRequest, "INVALID_REQUEST", "请求参数无效", err)
        return
    }

    user, err := h.userService.Create(c.Request.Context(), req)
    if err != nil {
        h.logger.Error("创建用户失败", zap.Error(err))
        response.Error(c, http.StatusInternalServerError, "CREATE_USER_FAILED", "创建用户失败", err)
        return
    }

    response.Success(c, user, "用户创建成功")
}

处理器职责

请求绑定: 解析 HTTP 请求参数
参数验证: 验证请求参数的有效性
服务调用: 调用应用服务层处理业务逻辑
响应格式化: 格式化响应数据
错误处理: 处理和记录错误信息

🗺️ 路由设计

API 版本管理

// v1 路由组
v1 := router.Group("/api/v1")
{
    // 公共路由 (无需认证)
    v1.POST("/auth/login", authHandler.Login)
    v1.POST("/auth/register", authHandler.Register)
    v1.GET("/photos/public", photoHandler.GetPublicPhotos)
    
    // 需要认证的路由
    authenticated := v1.Group("")
    authenticated.Use(middleware.AuthRequired())
    {
        authenticated.GET("/users/profile", userHandler.GetProfile)
        authenticated.PUT("/users/profile", userHandler.UpdateProfile)
        authenticated.POST("/photos", photoHandler.Create)
        authenticated.GET("/photos", photoHandler.List)
    }
    
    // 管理员路由
    admin := v1.Group("/admin")
    admin.Use(middleware.AuthRequired(), middleware.AdminRequired())
    {
        admin.GET("/users", userHandler.ListUsers)
        admin.DELETE("/users/:id", userHandler.DeleteUser)
        admin.GET("/photos/all", photoHandler.ListAllPhotos)
    }
}

RESTful API 设计

// 用户资源
GET    /api/v1/users          # 获取用户列表
POST   /api/v1/users          # 创建用户
GET    /api/v1/users/:id      # 获取用户详情
PUT    /api/v1/users/:id      # 更新用户
DELETE /api/v1/users/:id      # 删除用户

// 照片资源
GET    /api/v1/photos         # 获取照片列表
POST   /api/v1/photos         # 创建照片
GET    /api/v1/photos/:id     # 获取照片详情
PUT    /api/v1/photos/:id     # 更新照片
DELETE /api/v1/photos/:id     # 删除照片

// 分类资源
GET    /api/v1/categories     # 获取分类列表
POST   /api/v1/categories     # 创建分类
GET    /api/v1/categories/:id # 获取分类详情
PUT    /api/v1/categories/:id # 更新分类
DELETE /api/v1/categories/:id # 删除分类

🛡️ 中间件管理

认证中间件

func AuthRequired() gin.HandlerFunc {
    return func(c *gin.Context) {
        token := c.GetHeader("Authorization")
        if token == "" {
            response.Error(c, http.StatusUnauthorized, "MISSING_TOKEN", "缺少认证令牌", nil)
            c.Abort()
            return
        }

        // 验证 JWT Token
        claims, err := jwt.VerifyToken(token)
        if err != nil {
            response.Error(c, http.StatusUnauthorized, "INVALID_TOKEN", "无效的认证令牌", err)
            c.Abort()
            return
        }

        // 设置用户信息到上下文
        c.Set("user_id", claims.UserID)
        c.Set("user_role", claims.Role)
        c.Next()
    }
}

日志中间件

func Logger(logger *zap.Logger) gin.HandlerFunc {
    return func(c *gin.Context) {
        start := time.Now()
        c.Next()
        duration := time.Since(start)

        logger.Info("HTTP Request",
            zap.String("method", c.Request.Method),
            zap.String("path", c.Request.URL.Path),
            zap.String("query", c.Request.URL.RawQuery),
            zap.Int("status", c.Writer.Status()),
            zap.Duration("duration", duration),
            zap.String("user_agent", c.Request.UserAgent()),
            zap.String("ip", c.ClientIP()),
        )
    }
}

CORS 中间件

func CORS() gin.HandlerFunc {
    return func(c *gin.Context) {
        c.Header("Access-Control-Allow-Origin", "*")
        c.Header("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS")
        c.Header("Access-Control-Allow-Headers", "Content-Type, Authorization")
        c.Header("Access-Control-Max-Age", "86400")

        if c.Request.Method == "OPTIONS" {
            c.AbortWithStatus(204)
            return
        }

        c.Next()
    }
}

限流中间件

func RateLimit(limit int, window time.Duration) gin.HandlerFunc {
    limiter := rate.NewLimiter(rate.Every(window), limit)
    
    return func(c *gin.Context) {
        if !limiter.Allow() {
            response.Error(c, http.StatusTooManyRequests, "RATE_LIMIT_EXCEEDED", "请求过于频繁", nil)
            c.Abort()
            return
        }
        c.Next()
    }
}

✅ 请求验证

验证器结构

type CreateUserRequest struct {
    Username string `json:"username" binding:"required,min=3,max=20"`
    Email    string `json:"email" binding:"required,email"`
    Password string `json:"password" binding:"required,min=6"`
    Role     string `json:"role" binding:"oneof=user editor admin"`
}

type UpdateUserRequest struct {
    Username string `json:"username,omitempty" binding:"omitempty,min=3,max=20"`
    Email    string `json:"email,omitempty" binding:"omitempty,email"`
    Role     string `json:"role,omitempty" binding:"omitempty,oneof=user editor admin"`
}

自定义验证器

func ValidateUsername(fl validator.FieldLevel) bool {
    username := fl.Field().String()
    // 用户名只能包含字母、数字和下划线
    matched, _ := regexp.MatchString(`^[a-zA-Z0-9_]+$`, username)
    return matched
}

func ValidatePhotoFormat(fl validator.FieldLevel) bool {
    format := fl.Field().String()
    allowedFormats := []string{"jpg", "jpeg", "png", "gif", "webp"}
    for _, allowed := range allowedFormats {
        if format == allowed {
            return true
        }
    }
    return false
}

验证错误处理

func FormatValidationErrors(err error) map[string]string {
    errors := make(map[string]string)
    
    if validationErrors, ok := err.(validator.ValidationErrors); ok {
        for _, e := range validationErrors {
            field := strings.ToLower(e.Field())
            switch e.Tag() {
            case "required":
                errors[field] = "此字段为必填项"
            case "email":
                errors[field] = "请输入有效的邮箱地址"
            case "min":
                errors[field] = fmt.Sprintf("最小长度为 %s", e.Param())
            case "max":
                errors[field] = fmt.Sprintf("最大长度为 %s", e.Param())
            default:
                errors[field] = "字段值无效"
            }
        }
    }
    
    return errors
}

📊 响应格式

统一响应结构

type Response struct {
    Success   bool        `json:"success"`
    Data      interface{} `json:"data,omitempty"`
    Message   string      `json:"message"`
    Error     *ErrorInfo  `json:"error,omitempty"`
    Timestamp time.Time   `json:"timestamp"`
}

type ErrorInfo struct {
    Code    string      `json:"code"`
    Message string      `json:"message"`
    Details interface{} `json:"details,omitempty"`
}

响应帮助函数

func Success(c *gin.Context, data interface{}, message string) {
    c.JSON(http.StatusOK, Response{
        Success:   true,
        Data:      data,
        Message:   message,
        Timestamp: time.Now(),
    })
}

func Error(c *gin.Context, statusCode int, errorCode, message string, details interface{}) {
    c.JSON(statusCode, Response{
        Success: false,
        Message: message,
        Error: &ErrorInfo{
            Code:    errorCode,
            Message: message,
            Details: details,
        },
        Timestamp: time.Now(),
    })
}

分页响应

type PaginatedResponse struct {
    Data       interface{} `json:"data"`
    Pagination Pagination  `json:"pagination"`
}

type Pagination struct {
    Page        int   `json:"page"`
    PageSize    int   `json:"page_size"`
    Total       int64 `json:"total"`
    TotalPages  int   `json:"total_pages"`
    HasNext     bool  `json:"has_next"`
    HasPrevious bool  `json:"has_previous"`
}

🔍 错误处理

错误分类

const (
    // 请求错误
    ErrInvalidRequest     = "INVALID_REQUEST"
    ErrMissingParameter   = "MISSING_PARAMETER"
    ErrInvalidParameter   = "INVALID_PARAMETER"
    
    // 认证错误
    ErrMissingToken       = "MISSING_TOKEN"
    ErrInvalidToken       = "INVALID_TOKEN"
    ErrTokenExpired       = "TOKEN_EXPIRED"
    ErrInsufficientPermission = "INSUFFICIENT_PERMISSION"
    
    // 业务错误
    ErrUserNotFound       = "USER_NOT_FOUND"
    ErrUserAlreadyExists  = "USER_ALREADY_EXISTS"
    ErrPhotoNotFound      = "PHOTO_NOT_FOUND"
    ErrCategoryNotFound   = "CATEGORY_NOT_FOUND"
    
    // 系统错误
    ErrInternalServer     = "INTERNAL_SERVER_ERROR"
    ErrDatabaseError      = "DATABASE_ERROR"
    ErrStorageError       = "STORAGE_ERROR"
)

错误恢复中间件

func Recovery(logger *zap.Logger) gin.HandlerFunc {
    return func(c *gin.Context) {
        defer func() {
            if err := recover(); err != nil {
                logger.Error("Panic recovered",
                    zap.Any("error", err),
                    zap.String("path", c.Request.URL.Path),
                    zap.String("method", c.Request.Method),
                )
                
                response.Error(c, http.StatusInternalServerError, "INTERNAL_SERVER_ERROR", "服务器内部错误", nil)
            }
        }()
        c.Next()
    }
}

📊 性能优化

响应压缩

func Compression() gin.HandlerFunc {
    return gzip.Gzip(gzip.DefaultCompression)
}

缓存控制

func CacheControl(maxAge int) gin.HandlerFunc {
    return func(c *gin.Context) {
        c.Header("Cache-Control", fmt.Sprintf("max-age=%d", maxAge))
        c.Next()
    }
}

请求大小限制

func LimitRequestSize(maxSize int64) gin.HandlerFunc {
    return func(c *gin.Context) {
        c.Request.Body = http.MaxBytesReader(c.Writer, c.Request.Body, maxSize)
        c.Next()
    }
}

🧪 测试策略

处理器测试

func TestUserHandler_Create(t *testing.T) {
    // 模拟服务
    mockService := &MockUserService{}
    handler := NewUserHandler(mockService, zap.NewNop())

    // 创建测试请求
    reqBody := `{"username":"test","email":"test@example.com","password":"123456"}`
    req, _ := http.NewRequest("POST", "/api/v1/users", strings.NewReader(reqBody))
    req.Header.Set("Content-Type", "application/json")

    // 执行请求
    w := httptest.NewRecorder()
    router := gin.New()
    router.POST("/api/v1/users", handler.Create)
    router.ServeHTTP(w, req)

    // 验证结果
    assert.Equal(t, http.StatusOK, w.Code)
    assert.Contains(t, w.Body.String(), "success")
}

中间件测试

func TestAuthMiddleware(t *testing.T) {
    middleware := AuthRequired()
    
    // 测试缺少 token
    req, _ := http.NewRequest("GET", "/api/v1/users", nil)
    w := httptest.NewRecorder()
    c, _ := gin.CreateTestContext(w)
    c.Request = req
    
    middleware(c)
    
    assert.Equal(t, http.StatusUnauthorized, w.Code)
    assert.Contains(t, w.Body.String(), "MISSING_TOKEN")
}

📚 API 文档

Swagger 注释

// CreateUser 创建用户
// @Summary 创建用户
// @Description 创建新用户账户
// @Tags 用户管理
// @Accept json
// @Produce json
// @Param user body validators.CreateUserRequest true "用户信息"
// @Success 200 {object} response.Response{data=models.User} "成功创建用户"
// @Failure 400 {object} response.Response "请求参数错误"
// @Failure 500 {object} response.Response "服务器内部错误"
// @Router /api/v1/users [post]
func (h *UserHandler) Create(c *gin.Context) {
    // 处理器实现
}

API 文档生成

# 安装 swag
go install github.com/swaggo/swag/cmd/swag@latest

# 生成文档
swag init -g cmd/server/main.go

# 启动时访问文档
# http://localhost:8080/swagger/index.html

🔧 开发工具

路由调试

func PrintRoutes(router *gin.Engine) {
    routes := router.Routes()
    for _, route := range routes {
        fmt.Printf("[%s] %s -> %s\n", route.Method, route.Path, route.Handler)
    }
}

请求日志

func RequestLogger() gin.HandlerFunc {
    return gin.LoggerWithFormatter(func(param gin.LogFormatterParams) string {
        return fmt.Sprintf("[%s] %s %s %d %s\n",
            param.TimeStamp.Format("2006-01-02 15:04:05"),
            param.Method,
            param.Path,
            param.StatusCode,
            param.Latency,
        )
    })
}

💡 最佳实践

处理器设计

保持处理器轻量，业务逻辑放在服务层
统一错误处理和响应格式
完善的参数验证和错误提示
适当的日志记录

中间件使用

按需应用中间件，避免过度使用
注意中间件的执行顺序
错误处理中间件应该最先应用
认证中间件应该在业务中间件之前

路由设计

遵循 RESTful 设计原则
合理的路由分组和版本管理
清晰的路由命名和结构
适当的权限控制

性能考虑

使用响应压缩减少传输大小
适当的缓存控制
限制请求大小和频率
异步处理耗时操作

本模块是整个 API 的入口和门面，确保接口设计合理、响应格式统一、错误处理完善是项目成功的关键。

16 KiB Raw Blame History

HTTP 接口层 - CLAUDE.md

🎯 模块概览

职责范围

文件结构

🎯 处理器模式

标准处理器结构

处理器职责

🗺️ 路由设计

API 版本管理

RESTful API 设计

🛡️ 中间件管理

认证中间件

日志中间件

CORS 中间件

限流中间件

✅ 请求验证

验证器结构

自定义验证器

验证错误处理

📊 响应格式

统一响应结构

响应帮助函数

分页响应

🔍 错误处理

错误分类

错误恢复中间件

📊 性能优化

响应压缩

缓存控制

请求大小限制

🧪 测试策略

处理器测试

中间件测试

📚 API 文档

Swagger 注释

API 文档生成

🔧 开发工具

路由调试

请求日志

💡 最佳实践

处理器设计

中间件使用

路由设计

性能考虑

16 KiB

Raw Blame History