初始版本,工具基础类

2025-11-30 13:02:34 +08:00
commit ea4e2e305d
37 changed files with 7480 additions and 0 deletions
--- a/docs/http.md
+++ b/docs/http.md
@@ -0,0 +1,423 @@
+# HTTP Restful工具文档
+
+## 概述
+
+HTTP Restful工具提供了标准化的HTTP请求和响应处理功能，包含统一的响应结构、分页支持和HTTP状态码与业务状态码的分离。
+
+## 功能特性
+
+- 标准化的响应结构：`{code, message, timestamp, data}`
+- 分离HTTP状态码和业务状态码
+- 支持分页响应
+- 提供便捷的请求参数解析方法
+- 支持JSON请求体解析
+- 提供常用的HTTP错误响应方法
+
+## 响应结构
+
+### 标准响应结构
+
+```json
+{
+    "code": 0,
+    "message": "success",
+    "timestamp": 1704067200,
+    "data": {}
+}
+```
+
+### 分页响应结构
+
+```json
+{
+    "code": 0,
+    "message": "success",
+    "timestamp": 1704067200,
+    "data": {
+        "list": [],
+        "total": 100,
+        "page": 1,
+        "pageSize": 10
+    }
+}
+```
+
+## 使用方法
+
+### 1. 成功响应
+
+```go
+import (
+    "net/http"
+    "github.com/go-common/http"
+)
+
+// 简单成功响应（data为nil）
+http.Success(w, nil)
+
+// 带数据的成功响应
+data := map[string]interface{}{
+    "id": 1,
+    "name": "test",
+}
+http.Success(w, data)
+
+// 带消息的成功响应
+http.SuccessWithMessage(w, "操作成功", data)
+```
+
+### 2. 错误响应
+
+```go
+// 业务错误（HTTP 200，业务code非0）
+http.Error(w, 1001, "用户不存在")
+
+// 系统错误（HTTP 500）
+http.SystemError(w, "服务器内部错误")
+
+// 请求错误（HTTP 400）
+http.BadRequest(w, "请求参数错误")
+
+// 未授权（HTTP 401）
+http.Unauthorized(w, "未登录")
+
+// 禁止访问（HTTP 403）
+http.Forbidden(w, "无权限访问")
+
+// 未找到（HTTP 404）
+http.NotFound(w, "资源不存在")
+```
+
+### 3. 分页响应
+
+```go
+// 获取分页参数
+page, pageSize := http.GetPaginationParams(r)
+
+// 查询数据（示例）
+list, total := getDataList(page, pageSize)
+
+// 返回分页响应
+http.SuccessPage(w, list, total, page, pageSize)
+
+// 带消息的分页响应
+http.SuccessPageWithMessage(w, "查询成功", list, total, page, pageSize)
+```
+
+### 4. 解析请求
+
+#### 解析JSON请求体
+
+```go
+type CreateUserRequest struct {
+    Name  string `json:"name"`
+    Email string `json:"email"`
+}
+
+var req CreateUserRequest
+err := http.ParseJSON(r, &req)
+if err != nil {
+    http.BadRequest(w, "请求参数解析失败")
+    return
+}
+```
+
+#### 获取查询参数
+
+```go
+// 获取字符串参数
+name := http.GetQuery(r, "name", "")
+email := http.GetQuery(r, "email", "default@example.com")
+
+// 获取整数参数
+id := http.GetQueryInt(r, "id", 0)
+age := http.GetQueryInt(r, "age", 18)
+
+// 获取int64参数
+userId := http.GetQueryInt64(r, "userId", 0)
+
+// 获取布尔参数
+isActive := http.GetQueryBool(r, "isActive", false)
+
+// 获取浮点数参数
+price := http.GetQueryFloat64(r, "price", 0.0)
+```
+
+#### 获取表单参数
+
+```go
+// 获取表单字符串
+name := http.GetFormValue(r, "name", "")
+
+// 获取表单整数
+age := http.GetFormInt(r, "age", 0)
+
+// 获取表单int64
+userId := http.GetFormInt64(r, "userId", 0)
+
+// 获取表单布尔值
+isActive := http.GetFormBool(r, "isActive", false)
+```
+
+#### 获取请求头
+
+```go
+token := http.GetHeader(r, "Authorization", "")
+contentType := http.GetHeader(r, "Content-Type", "application/json")
+```
+
+#### 获取分页参数
+
+```go
+// 自动解析page和pageSize参数
+// 默认: page=1, pageSize=10
+// 限制: pageSize最大1000
+page, pageSize := http.GetPaginationParams(r)
+
+// 计算数据库查询偏移量
+offset := http.GetOffset(page, pageSize)
+```
+
+### 5. 自定义响应
+
+```go
+// 使用WriteJSON自定义响应
+http.WriteJSON(w, http.StatusOK, 0, "success", data)
+
+// 参数说明：
+// - httpCode: HTTP状态码（200, 400, 500等）
+// - code: 业务状态码（0表示成功，非0表示业务错误）
+// - message: 响应消息
+// - data: 响应数据
+```
+
+## 完整示例
+
+```go
+package main
+
+import (
+    "net/http"
+    "github.com/go-common/http"
+)
+
+// 用户列表接口
+func GetUserList(w http.ResponseWriter, r *http.Request) {
+    // 获取分页参数
+    page, pageSize := http.GetPaginationParams(r)
+    
+    // 获取查询参数
+    keyword := http.GetQuery(r, "keyword", "")
+    
+    // 查询数据
+    users, total := queryUsers(keyword, page, pageSize)
+    
+    // 返回分页响应
+    http.SuccessPage(w, users, total, page, pageSize)
+}
+
+// 创建用户接口
+func CreateUser(w http.ResponseWriter, r *http.Request) {
+    // 解析请求体
+    var req struct {
+        Name  string `json:"name"`
+        Email string `json:"email"`
+    }
+    
+    if err := http.ParseJSON(r, &req); err != nil {
+        http.BadRequest(w, "请求参数解析失败")
+        return
+    }
+    
+    // 参数验证
+    if req.Name == "" {
+        http.Error(w, 1001, "用户名不能为空")
+        return
+    }
+    
+    // 创建用户
+    user, err := createUser(req.Name, req.Email)
+    if err != nil {
+        http.SystemError(w, "创建用户失败")
+        return
+    }
+    
+    // 返回成功响应
+    http.SuccessWithMessage(w, "创建成功", user)
+}
+
+// 获取用户详情接口
+func GetUser(w http.ResponseWriter, r *http.Request) {
+    // 获取路径参数（需要配合路由框架使用）
+    id := http.GetQueryInt64(r, "id", 0)
+    
+    if id == 0 {
+        http.BadRequest(w, "用户ID不能为空")
+        return
+    }
+    
+    // 查询用户
+    user, err := getUserByID(id)
+    if err != nil {
+        http.SystemError(w, "查询用户失败")
+        return
+    }
+    
+    if user == nil {
+        http.Error(w, 1002, "用户不存在")
+        return
+    }
+    
+    http.Success(w, user)
+}
+```
+
+## API 参考
+
+### 响应方法
+
+#### Success(w http.ResponseWriter, data interface{})
+
+成功响应，HTTP 200，业务code 0。
+
+#### SuccessWithMessage(w http.ResponseWriter, message string, data interface{})
+
+带消息的成功响应。
+
+#### Error(w http.ResponseWriter, code int, message string)
+
+业务错误响应，HTTP 200，业务code非0。
+
+#### SystemError(w http.ResponseWriter, message string)
+
+系统错误响应，HTTP 500，业务code 500。
+
+#### BadRequest(w http.ResponseWriter, message string)
+
+请求错误响应，HTTP 400。
+
+#### Unauthorized(w http.ResponseWriter, message string)
+
+未授权响应，HTTP 401。
+
+#### Forbidden(w http.ResponseWriter, message string)
+
+禁止访问响应，HTTP 403。
+
+#### NotFound(w http.ResponseWriter, message string)
+
+未找到响应，HTTP 404。
+
+#### WriteJSON(w http.ResponseWriter, httpCode, code int, message string, data interface{})
+
+写入JSON响应（自定义）。
+
+**参数：**
+- `httpCode`: HTTP状态码
+- `code`: 业务状态码
+- `message`: 响应消息
+- `data`: 响应数据
+
+#### SuccessPage(w http.ResponseWriter, list interface{}, total int64, page, pageSize int)
+
+分页成功响应。
+
+#### SuccessPageWithMessage(w http.ResponseWriter, message string, list interface{}, total int64, page, pageSize int)
+
+带消息的分页成功响应。
+
+### 请求方法
+
+#### ParseJSON(r *http.Request, v interface{}) error
+
+解析JSON请求体。
+
+#### GetQuery(r *http.Request, key, defaultValue string) string
+
+获取查询参数（字符串）。
+
+#### GetQueryInt(r *http.Request, key string, defaultValue int) int
+
+获取查询参数（整数）。
+
+#### GetQueryInt64(r *http.Request, key string, defaultValue int64) int64
+
+获取查询参数（int64）。
+
+#### GetQueryBool(r *http.Request, key string, defaultValue bool) bool
+
+获取查询参数（布尔值）。
+
+#### GetQueryFloat64(r *http.Request, key string, defaultValue float64) float64
+
+获取查询参数（浮点数）。
+
+#### GetFormValue(r *http.Request, key, defaultValue string) string
+
+获取表单值（字符串）。
+
+#### GetFormInt(r *http.Request, key string, defaultValue int) int
+
+获取表单值（整数）。
+
+#### GetFormInt64(r *http.Request, key string, defaultValue int64) int64
+
+获取表单值（int64）。
+
+#### GetFormBool(r *http.Request, key string, defaultValue bool) bool
+
+获取表单值（布尔值）。
+
+#### GetHeader(r *http.Request, key, defaultValue string) string
+
+获取请求头。
+
+#### GetPaginationParams(r *http.Request) (page, pageSize int)
+
+获取分页参数。
+
+**返回：** page（页码，最小1），pageSize（每页大小，最小1，最大1000）
+
+#### GetOffset(page, pageSize int) int
+
+根据页码和每页大小计算偏移量。
+
+## 状态码说明
+
+### HTTP状态码
+
+- `200`: 正常响应（包括业务错误）
+- `400`: 请求参数错误
+- `401`: 未授权
+- `403`: 禁止访问
+- `404`: 资源不存在
+- `500`: 系统内部错误
+
+### 业务状态码
+
+- `0`: 成功
+- `非0`: 业务错误（具体错误码由业务定义）
+
+## 注意事项
+
+1. **HTTP状态码与业务状态码分离**：
+   - 业务错误（如用户不存在、参数验证失败等）返回HTTP 200，业务code非0
+   - 只有系统异常（如数据库连接失败、程序panic等）才返回HTTP 500
+
+2. **分页参数限制**：
+   - page最小值为1
+   - pageSize最小值为1，最大值为1000
+
+3. **响应格式统一**：
+   - 所有响应都遵循标准结构
+   - timestamp为Unix时间戳（秒）
+
+4. **错误处理**：
+   - 使用Error方法返回业务错误
+   - 使用SystemError返回系统错误
+   - 使用BadRequest等返回HTTP级别的错误
+
+## 示例
+
+完整示例请参考 `examples/http_example.go`
+