# HTTP Restful工具文档

## 概述

HTTP Restful工具提供了标准化的HTTP请求和响应处理功能，采用Handler黑盒模式，封装了`ResponseWriter`和`Request`，提供简洁的API，无需每次都传递这两个参数。

## 功能特性

- **黑盒模式**：封装`ResponseWriter`和`Request`，提供简洁的API
- **标准化的响应结构**：`{code, message, timestamp, data}`
- **分离HTTP状态码和业务状态码**
- **支持分页响应**
- **提供便捷的请求参数解析方法**
- **支持JSON请求体解析**

## 响应结构

### 标准响应结构

```json
{
    "code": 0,
    "message": "success",
    "timestamp": 1704067200,
    "data": {}
}
```

### 分页响应结构

```json
{
    "code": 0,
    "message": "success",
    "timestamp": 1704067200,
    "data": {
        "list": [],
        "total": 100,
        "page": 1,
        "pageSize": 10
    }
}
```

## 使用方法

### 1. 创建Handler

```go
import (
    "net/http"
    commonhttp "git.toowon.com/jimmy/go-common/http"
)

// 方式1：使用HandleFunc包装器（推荐，最简洁）
func GetUser(h *commonhttp.Handler) {
    id := h.GetQueryInt64("id", 0)
    h.Success(data)
}

http.HandleFunc("/user", commonhttp.HandleFunc(GetUser))

// 方式2：手动创建Handler（需要更多控制时）
http.HandleFunc("/user", func(w http.ResponseWriter, r *http.Request) {
    h := commonhttp.NewHandler(w, r)
    GetUser(h)
})
```

### 2. 成功响应

```go
func handler(h *commonhttp.Handler) {
    // 简单成功响应（data为nil）
    h.Success(nil)
    
    // 带数据的成功响应
    data := map[string]interface{}{
        "id": 1,
        "name": "test",
    }
    h.Success(data)
    
    // 带消息的成功响应
    h.SuccessWithMessage("操作成功", data)
}
```

### 3. 错误响应

```go
func handler(h *commonhttp.Handler) {
    // 业务错误（HTTP 200，业务code非0）
    h.Error(1001, "用户不存在")
    
    // 系统错误（HTTP 500）
    h.SystemError("服务器内部错误")
    
    // 其他HTTP错误状态码，使用WriteJSON直接指定
    // 请求错误（HTTP 400）
    h.WriteJSON(http.StatusBadRequest, 400, "请求参数错误", nil)
    
    // 未授权（HTTP 401）
    h.WriteJSON(http.StatusUnauthorized, 401, "未登录", nil)
    
    // 禁止访问（HTTP 403）
    h.WriteJSON(http.StatusForbidden, 403, "无权限访问", nil)
    
    // 未找到（HTTP 404）
    h.WriteJSON(http.StatusNotFound, 404, "资源不存在", nil)
}
```

### 4. 分页响应

```go
func handler(h *commonhttp.Handler) {
    // 获取分页参数
    pagination := h.ParsePaginationRequest()
    page := pagination.GetPage()
    pageSize := pagination.GetSize()
    
    // 查询数据（示例）
    list, total := getDataList(page, pageSize)
    
    // 返回分页响应（使用默认消息）
    h.SuccessPage(list, total, page, pageSize)
    
    // 返回分页响应（自定义消息）
    h.SuccessPage(list, total, page, pageSize, "查询成功")
}
```

### 5. 解析请求

#### 解析JSON请求体

```go
func handler(h *commonhttp.Handler) {
    type CreateUserRequest struct {
        Name  string `json:"name"`
        Email string `json:"email"`
    }
    
    var req CreateUserRequest
    if err := h.ParseJSON(&req); err != nil {
        h.WriteJSON(http.StatusBadRequest, 400, "请求参数解析失败", nil)
        return
    }
    
    // 使用req...
}
```

#### 获取查询参数

```go
func handler(h *commonhttp.Handler) {
    // 获取字符串参数
    name := h.GetQuery("name", "")
    email := h.GetQuery("email", "default@example.com")
    
    // 获取整数参数
    id := h.GetQueryInt("id", 0)
    age := h.GetQueryInt("age", 18)
    
    // 获取int64参数
    userId := h.GetQueryInt64("userId", 0)
    
    // 获取布尔参数
    isActive := h.GetQueryBool("isActive", false)
    
    // 获取浮点数参数
    price := h.GetQueryFloat64("price", 0.0)
}
```

#### 获取表单参数

```go
func handler(h *commonhttp.Handler) {
    // 获取表单字符串
    name := h.GetFormValue("name", "")
    
    // 获取表单整数
    age := h.GetFormInt("age", 0)
    
    // 获取表单int64
    userId := h.GetFormInt64("userId", 0)
    
    // 获取表单布尔值
    isActive := h.GetFormBool("isActive", false)
}
```

#### 获取请求头

```go
func handler(h *commonhttp.Handler) {
    token := h.GetHeader("Authorization", "")
    contentType := h.GetHeader("Content-Type", "application/json")
}
```

#### 获取分页参数

**方式1：使用 PaginationRequest 结构（推荐）**

```go
func handler(h *commonhttp.Handler) {
    // 定义请求结构（包含分页字段）
    type ListUserRequest struct {
        Keyword string `json:"keyword"`
        commonhttp.PaginationRequest // 嵌入分页请求结构
    }
    
    // 从JSON请求体解析（分页字段会自动解析）
    var req ListUserRequest
    if err := h.ParseJSON(&req); err != nil {
        h.WriteJSON(http.StatusBadRequest, 400, "请求参数解析失败", nil)
        return
    }
    
    // 使用分页方法
    page := req.GetPage()      // 获取页码（默认1）
    size := req.GetSize()       // 获取每页数量（默认20，最大100，优先使用page_size）
    offset := req.GetOffset()   // 计算偏移量
}

// 或者从查询参数/form解析分页
func handler(h *commonhttp.Handler) {
    pagination := h.ParsePaginationRequest()
    page := pagination.GetPage()
    size := pagination.GetSize()
    offset := pagination.GetOffset()
}
```

#### 获取时区

```go
func handler(h *commonhttp.Handler) {
    // 从请求的context中获取时区
    // 如果使用了middleware.Timezone中间件，可以从context中获取时区信息
    // 如果未设置，返回默认时区 AsiaShanghai
    timezone := h.GetTimezone()
}
```

### 6. 访问原始对象

如果需要访问原始的`ResponseWriter`或`Request`：

```go
func handler(h *commonhttp.Handler) {
    // 获取原始ResponseWriter
    w := h.ResponseWriter()
    
    // 获取原始Request
    r := h.Request()
    
    // 获取Context
    ctx := h.Context()
}
```

## 完整示例

```go
package main

import (
    "log"
    "net/http"
    commonhttp "git.toowon.com/jimmy/go-common/http"
)

// 用户结构
type User struct {
    ID    int64  `json:"id"`
    Name  string `json:"name"`
    Email string `json:"email"`
}

// 用户列表接口
func GetUserList(h *commonhttp.Handler) {
    // 获取分页参数
    pagination := h.ParsePaginationRequest()
    page := pagination.GetPage()
    pageSize := pagination.GetSize()
    
    // 获取查询参数
    keyword := h.GetQuery("keyword", "")
    
    // 查询数据
    users, total := queryUsers(keyword, page, pageSize)
    
    // 返回分页响应
    h.SuccessPage(users, total, page, pageSize)
}

// 创建用户接口
func CreateUser(h *commonhttp.Handler) {
    // 解析请求体
    var req struct {
        Name  string `json:"name"`
        Email string `json:"email"`
    }
    
    if err := h.ParseJSON(&req); err != nil {
        h.WriteJSON(http.StatusBadRequest, 400, "请求参数解析失败", nil)
        return
    }
    
    // 参数验证
    if req.Name == "" {
        h.Error(1001, "用户名不能为空")
        return
    }
    
    // 创建用户
    user, err := createUser(req.Name, req.Email)
    if err != nil {
        h.SystemError("创建用户失败")
        return
    }
    
    // 返回成功响应
    h.SuccessWithMessage("创建成功", user)
}

// 获取用户详情接口
func GetUser(h *commonhttp.Handler) {
    // 获取查询参数
    id := h.GetQueryInt64("id", 0)
    
    if id == 0 {
        h.WriteJSON(http.StatusBadRequest, 400, "用户ID不能为空", nil)
        return
    }
    
    // 查询用户
    user, err := getUserByID(id)
    if err != nil {
        h.SystemError("查询用户失败")
        return
    }
    
    if user == nil {
        h.Error(1002, "用户不存在")
        return
    }
    
    h.Success(user)
}

func main() {
    // 使用HandleFunc包装器（推荐）
    http.HandleFunc("/users", commonhttp.HandleFunc(func(h *commonhttp.Handler) {
        switch h.Request().Method {
        case http.MethodGet:
            GetUserList(h)
        case http.MethodPost:
            CreateUser(h)
        default:
            h.WriteJSON(http.StatusMethodNotAllowed, 405, "方法不支持", nil)
        }
    }))
    
    http.HandleFunc("/user", commonhttp.HandleFunc(GetUser))
    
    log.Println("Server started on :8080")
    log.Fatal(http.ListenAndServe(":8080", nil))
}
```

## API 参考

### Handler结构

Handler封装了`ResponseWriter`和`Request`，提供更简洁的API。

```go
type Handler struct {
    w http.ResponseWriter
    r *http.Request
}
```

### 创建Handler

#### NewHandler(w http.ResponseWriter, r *http.Request) *Handler

创建Handler实例。

#### HandleFunc(fn func(*Handler)) http.HandlerFunc

将Handler函数转换为标准的http.HandlerFunc（便捷包装器）。

**示例：**
```go
http.HandleFunc("/users", commonhttp.HandleFunc(func(h *commonhttp.Handler) {
    h.Success(data)
}))
```

### Handler响应方法

#### (h *Handler) Success(data interface{})

成功响应，HTTP 200，业务code 0。

#### (h *Handler) SuccessWithMessage(message string, data interface{})

带消息的成功响应。

#### (h *Handler) Error(code int, message string)

业务错误响应，HTTP 200，业务code非0。

#### (h *Handler) SystemError(message string)

系统错误响应，HTTP 500，业务code 500。

#### (h *Handler) WriteJSON(httpCode, code int, message string, data interface{})

写入JSON响应（自定义）。

**参数：**
- `httpCode`: HTTP状态码
- `code`: 业务状态码
- `message`: 响应消息
- `data`: 响应数据

#### (h *Handler) SuccessPage(list interface{}, total int64, page, pageSize int, message ...string)

分页成功响应。

**参数：**
- `list`: 数据列表
- `total`: 总记录数
- `page`: 当前页码
- `pageSize`: 每页大小
- `message`: 响应消息（可选，如果为空则使用默认消息 "success"）

### Handler请求解析方法

#### (h *Handler) ParseJSON(v interface{}) error

解析JSON请求体。

#### (h *Handler) GetQuery(key, defaultValue string) string

获取查询参数（字符串）。

#### (h *Handler) GetQueryInt(key string, defaultValue int) int

获取查询参数（整数）。

#### (h *Handler) GetQueryInt64(key string, defaultValue int64) int64

获取查询参数（int64）。

#### (h *Handler) GetQueryBool(key string, defaultValue bool) bool

获取查询参数（布尔值）。

#### (h *Handler) GetQueryFloat64(key string, defaultValue float64) float64

获取查询参数（浮点数）。

#### (h *Handler) GetFormValue(key, defaultValue string) string

获取表单值（字符串）。

#### (h *Handler) GetFormInt(key string, defaultValue int) int

获取表单值（整数）。

#### (h *Handler) GetFormInt64(key string, defaultValue int64) int64

获取表单值（int64）。

#### (h *Handler) GetFormBool(key string, defaultValue bool) bool

获取表单值（布尔值）。

#### (h *Handler) GetHeader(key, defaultValue string) string

获取请求头。

#### (h *Handler) ParsePaginationRequest() *PaginationRequest

从请求中解析分页参数。

**说明：**
- 支持从查询参数和form表单中解析
- 优先级：查询参数 > form表单
- 如果请求体是JSON格式且包含分页字段，建议先使用`ParseJSON`解析完整请求体到包含`PaginationRequest`的结构体中

#### (h *Handler) GetTimezone() string

从请求的context中获取时区。

**说明：**
- 如果使用了middleware.Timezone中间件，可以从context中获取时区信息
- 如果未设置，返回默认时区 AsiaShanghai

### Handler访问原始对象

#### (h *Handler) ResponseWriter() http.ResponseWriter

获取原始的ResponseWriter（需要时使用）。

#### (h *Handler) Request() *http.Request

获取原始的Request（需要时使用）。

#### (h *Handler) Context() context.Context

获取请求的Context。

### 分页请求结构

#### PaginationRequest

分页请求结构，支持从JSON和form中解析分页参数。

**字段：**
- `Page`: 页码（默认1）
- `Size`: 每页数量（兼容旧版本）
- `PageSize`: 每页数量（推荐使用，优先于Size）

**方法：**
- `GetPage() int`: 获取页码，如果未设置则返回默认值1
- `GetSize() int`: 获取每页数量，优先使用PageSize，如果未设置则使用Size，默认20，最大100
- `GetOffset() int`: 计算数据库查询的偏移量

#### ParsePaginationRequest(r *http.Request) *PaginationRequest

从请求中解析分页参数（内部函数，Handler内部使用）。

## 状态码说明

### HTTP状态码

- `200`: 正常响应（包括业务错误）
- `400`: 请求参数错误
- `401`: 未授权
- `403`: 禁止访问
- `404`: 资源不存在
- `500`: 系统内部错误

### 业务状态码

- `0`: 成功
- `非0`: 业务错误（具体错误码由业务定义）

## 注意事项

1. **HTTP状态码与业务状态码分离**：
   - 业务错误（如用户不存在、参数验证失败等）返回HTTP 200，业务code非0
   - 只有系统异常（如数据库连接失败、程序panic等）才返回HTTP 500

2. **分页参数限制**：
   - page最小值为1
   - pageSize最小值为1，最大值为100

3. **响应格式统一**：
   - 所有响应都遵循标准结构
   - timestamp为Unix时间戳（秒）

4. **错误处理**：
   - 使用`Error`方法返回业务错误（HTTP 200，业务code非0）
   - 使用`SystemError`返回系统错误（HTTP 500）
   - 其他HTTP错误状态码（400, 401, 403, 404等）使用`WriteJSON`方法直接指定

5. **黑盒模式**：
   - 所有功能都通过Handler对象调用，无需传递`w`和`r`参数
   - 代码更简洁，减少调用方工作量

## 示例

完整示例请参考 `examples/http_handler_example.go`