424 lines
9.0 KiB
Markdown
424 lines
9.0 KiB
Markdown
# 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`
|
||
|