gin + es 实践 04

API 接口筹划

Go-ES 项目提供了一套完整的 RESTful API，用于产品管理和搜索。本文档详细先容了 API 的筹划原则、接口定义和使用方法。
API 筹划原则

本项目标 API 筹划遵照以下原则：

• RESTful 风格：使用标准的 HTTP 方法体现操作类型
  
• 资源导向：API 路径以资源名词为中央
  
• JSON 格式：请求和相应均使用 JSON 格式
  
• 版本控制：API 路径包含版本号
  
• 统一错误处理：使用一致的错误相应格式
  
• 自文档化：使用 Swagger 注解自动天生 API 文档
  

API 底子信息

• 底子路径：/api/v1
  
• 内容类型：application/json
  
• 认证方式：API Key（通过 Authorization 头）
  

API 端点概览

方法路径描述POST/products创建产品GET/products获取产品列表GET/products/{id}获取产品详情PUT/products/{id}更新产品DELETE/products/{id}删除产品GET/products/category/{category}获取指定种别产品GET/products/search搜索产品POST/products/reindex重修产品索引 API 详细分析

1. 创建产品

请求:

1. POST /api/v1/products
2. Content-Type: application/json
4. {
5.   "name": "示例产品",
6.   "description": "这是一个示例产品",
7.   "price": 99.99,
8.   "category": "电子产品",
9.   "tags": ["新品", "热销"]
10. }

复制代码

相应:

1. HTTP/1.1 201 Created
2. Content-Type: application/json
4. {
5.   "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
6.   "name": "示例产品",
7.   "description": "这是一个示例产品",
8.   "price": 99.99,
9.   "category": "电子产品",
10.   "tags": ["新品", "热销"],
11.   "created_at": "2023-05-01T12:00:00Z",
12.   "updated_at": "2023-05-01T12:00:00Z"
13. }

复制代码

处理逻辑:

1. func (h *ProductHandler) Create(c *gin.Context) {
2.     var req dto.CreateProductRequest
3.     if err := c.ShouldBindJSON(&req); err != nil {
4.         c.JSON(http.StatusBadRequest, gin.H{"error": "无效的请求数据"})
5.         return
6.     }
8.     product, err := h.productAppService.CreateProduct(c.Request.Context(), &req)
9.     if err != nil {
10.         c.JSON(http.StatusInternalServerError, gin.H{"error": fmt.Sprintf("创建产品失败: %v", err)})
11.         return
12.     }
14.     c.JSON(http.StatusCreated, product)
15. }

复制代码

2. 获取产品列表

请求:

1. GET /api/v1/products?page=1&size=10

复制代码

相应:

1. HTTP/1.1 200 OK
2. Content-Type: application/json
4. {
5.   "total": 100,
6.   "page": 1,
7.   "page_size": 10,
8.   "products": [
9.     {
10.       "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
11.       "name": "示例产品",
12.       "description": "这是一个示例产品",
13.       "price": 99.99,
14.       "category": "电子产品",
15.       "tags": ["新品", "热销"],
16.       "created_at": "2023-05-01T12:00:00Z",
17.       "updated_at": "2023-05-01T12:00:00Z"
18.     },
19.     // ... 更多产品
20.   ]
21. }

复制代码

处理逻辑:

1. func (h *ProductHandler) List(c *gin.Context) {
2.     page, _ := strconv.Atoi(c.DefaultQuery("page", "1"))
3.     size, _ := strconv.Atoi(c.DefaultQuery("size", "10"))
5.     products, err := h.productAppService.ListProducts(c.Request.Context(), page, size)
6.     if err != nil {
7.         c.JSON(http.StatusInternalServerError, gin.H{"error": fmt.Sprintf("获取产品列表失败: %v", err)})
8.         return
9.     }
11.     c.JSON(http.StatusOK, products)
12. }

复制代码

3. 获取产品详情

请求:

1. GET /api/v1/products/f47ac10b-58cc-4372-a567-0e02b2c3d479

复制代码

相应:

1. HTTP/1.1 200 OK
2. Content-Type: application/json
4. {
5.   "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
6.   "name": "示例产品",
7.   "description": "这是一个示例产品",
8.   "price": 99.99,
9.   "category": "电子产品",
10.   "tags": ["新品", "热销"],
11.   "created_at": "2023-05-01T12:00:00Z",
12.   "updated_at": "2023-05-01T12:00:00Z"
13. }

复制代码

处理逻辑:

1. func (h *ProductHandler) Get(c *gin.Context) {
2.     id := c.Param("id")
3.     if id == "" {
4.         c.JSON(http.StatusBadRequest, gin.H{"error": "产品ID不能为空"})
5.         return
6.     }
8.     product, err := h.productAppService.GetProduct(c.Request.Context(), id)
9.     if err != nil {
10.         if err.Error() == "产品不存在" {
11.             c.JSON(http.StatusNotFound, gin.H{"error": "产品不存在"})
12.             return
13.         }
14.         c.JSON(http.StatusInternalServerError, gin.H{"error": fmt.Sprintf("获取产品失败: %v", err)})
15.         return
16.     }
18.     c.JSON(http.StatusOK, product)
19. }

复制代码

4. 搜索产品

请求:

1. GET /api/v1/products/search?q=手机&category=电子产品&page=1&size=10

复制代码

相应:

1. HTTP/1.1 200 OK
2. Content-Type: application/json
4. {
5.   "total": 5,
6.   "page": 1,
7.   "page_size": 10,
8.   "products": [
9.     {
10.       "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
11.       "name": "高端智能手机",
12.       "description": "这是一款功能强大的智能手机",
13.       "price": 3999.99,
14.       "category": "电子产品",
15.       "tags": ["手机", "智能设备"],
16.       "created_at": "2023-05-01T12:00:00Z",
17.       "updated_at": "2023-05-01T12:00:00Z"
18.     },
19.     // ... 更多产品
20.   ]
21. }

复制代码

处理逻辑:

1. func (h *ProductHandler) Search(c *gin.Context) {
2.     var searchReq dto.SearchProductRequest
3.     if err := c.ShouldBindQuery(&searchReq); err != nil {
4.         c.JSON(http.StatusBadRequest, gin.H{"error": "无效的搜索参数"})
5.         return
6.     }
8.     products, err := h.productAppService.SearchProducts(c.Request.Context(), &searchReq)
9.     if err != nil {
10.         c.JSON(http.StatusInternalServerError, gin.H{"error": fmt.Sprintf("搜索产品失败: %v", err)})
11.         return
12.     }
14.     c.JSON(http.StatusOK, products)
15. }

复制代码

请求与相应模型

请求模型

创建产品请求

1. // CreateProductRequest 创建产品请求
2. type CreateProductRequest struct {
3.     Name        string   `json:"name" binding:"required"`
4.     Description string   `json:"description"`
5.     Price       float64  `json:"price" binding:"required,gt=0"`
6.     Category    string   `json:"category" binding:"required"`
7.     Tags        []string `json:"tags"`
8. }

复制代码

更新产品请求

1. // UpdateProductRequest 更新产品请求
2. type UpdateProductRequest struct {
3.     Name        string   `json:"name" binding:"required"`
4.     Description string   `json:"description"`
5.     Price       float64  `json:"price" binding:"required,gt=0"`
6.     Category    string   `json:"category" binding:"required"`
7.     Tags        []string `json:"tags"`
8. }

复制代码

搜索产品请求

1. // SearchProductRequest 搜索产品请求
2. type SearchProductRequest struct {
3.     Keyword  string `form:"q"`
4.     Category string `form:"category"`
5.     Page     int    `form:"page,default=1"`
6.     PageSize int    `form:"size,default=10"`
7. }

复制代码

相应模型

产品相应

1. // ProductResponse 产品响应
2. type ProductResponse struct {
3.     ID          string    `json:"id"`
4.     Name        string    `json:"name"`
5.     Description string    `json:"description"`
6.     Price       float64   `json:"price"`
7.     Category    string    `json:"category"`
8.     Tags        []string  `json:"tags"`
9.     CreatedAt   time.Time `json:"created_at"`
10.     UpdatedAt   time.Time `json:"updated_at"`
11. }

复制代码

产品列表相应

1. // ProductListResponse 产品列表响应
2. type ProductListResponse struct {
3.     Total    int64            `json:"total"`
4.     Page     int              `json:"page"`
5.     PageSize int              `json:"page_size"`
6.     Products []ProductResponse `json:"products"`
7. }

复制代码

错误处理

API 使用统一的错误相应格式：

1. {
2.   "error": "错误描述信息"
3. }

复制代码

常见的错误相应包括：

• 400 Bad Request: 请求参数无效
  
• 404 Not Found: 请求的资源不存在
  
• 500 Internal Server Error: 服务器内部错误
  

API 文档天生

本项目使用 Swagger 自动天生 API 文档。API 处理器中的注解如下所示：

1. // Create 创建产品
2. // @Summary 创建新产品
3. // @Description 创建一个新的产品并索引到Elasticsearch
4. // @Tags 产品
5. // @Accept  json
6. // @Produce  json
7. // @Param product body dto.CreateProductRequest true "产品信息"
8. // @Success 201 {object} dto.ProductResponse
9. // @Failure 400 {object} map[string]string "错误信息"
10. // @Failure 500 {object} map[string]string "错误信息"
11. // @Router /products [post]
12. func (h *ProductHandler) Create(c *gin.Context) {
13.     // 实现逻辑...
14. }

复制代码

使用 Swagger 文档

• 启动应用后，访问 Swagger UI：
  

1. http://localhost:8080/swagger/index.html

复制代码

• 在 Swagger UI 界面中可以:
  
  
  
  • 欣赏所有 API 端点
    
  • 检察请求参数和相应格式
    
  • 直接在欣赏器中测试 API
    
  
  

API 路由注册

所有 API 路由在 interfaces/api/router/router.go 中注册：

1. // SetupRouter 设置路由
2. func SetupRouter(engine *gin.Engine, productHandler *handler.ProductHandler) {
3.     // 设置中间件
4.     engine.Use(gin.Logger())
5.     engine.Use(gin.Recovery())
6.     engine.Use(middleware.Cors())
8.     // 添加Swagger
9.     engine.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerfiles.Handler))
11.     // API 路由组
12.     api := engine.Group("/api/v1")
13.     {
14.         // 产品相关路由
15.         products := api.Group("/products")
16.         {
17.             products.POST("", productHandler.Create)
18.             products.GET("", productHandler.List)
19.             products.GET("/:id", productHandler.Get)
20.             products.PUT("/:id", productHandler.Update)
21.             products.DELETE("/:id", productHandler.Delete)
22.             products.GET("/category/:category", productHandler.ListByCategory)
23.             products.GET("/search", productHandler.Search)
24.             products.POST("/reindex", productHandler.ReindexAll)
25.         }
26.     }
27. }

复制代码

跨域处理

API 支持跨域请求，通过自定义中间件实现：

1. // Cors 添加CORS头
2. func Cors() gin.HandlerFunc {
3.     return func(c *gin.Context) {
4.         c.Writer.Header().Set("Access-Control-Allow-Origin", "*")
5.         c.Writer.Header().Set("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS")
6.         c.Writer.Header().Set("Access-Control-Allow-Headers", "Content-Type, Content-Length, Accept-Encoding, X-CSRF-Token, Authorization")
7.         c.Writer.Header().Set("Access-Control-Max-Age", "86400")
9.         // 处理OPTIONS请求
10.         if c.Request.Method == "OPTIONS" {
11.             c.AbortWithStatus(200)
12.             return
13.         }
15.         // 处理请求
16.         c.Next()
17.     }
18. }

复制代码

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！更多信息从访问主页：qidao123.com:ToB企服之家，中国第一个企服评测及商务社交产业平台。