766 lines
20 KiB
Markdown
766 lines
20 KiB
Markdown
# HTTP Restful工具文档
|
||
|
||
## 概述
|
||
|
||
HTTP Restful工具提供了标准化的HTTP请求和响应处理功能，提供公共方法供外部调用，保持低耦合。
|
||
|
||
## 功能特性
|
||
|
||
- **低耦合设计**：提供公共方法，不封装Handler结构
|
||
- **标准化的响应结构**：`{code, message, timestamp, data}`
|
||
- **分离HTTP状态码和业务状态码**
|
||
- **支持分页响应**
|
||
- **提供便捷的请求参数解析方法**
|
||
- **支持JSON请求体解析**
|
||
- **Factory黑盒模式**：推荐使用 `factory.Success()` 等方法
|
||
|
||
## 响应结构
|
||
|
||
### 标准响应结构
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"timestamp": 1704067200,
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
**结构体类型（暴露在 factory 中）：**
|
||
|
||
```go
|
||
// 在 factory 包中可以直接使用
|
||
type Response struct {
|
||
Code int `json:"code"` // 业务状态码，0表示成功
|
||
Message string `json:"message"` // 响应消息
|
||
Timestamp int64 `json:"timestamp"` // 时间戳
|
||
Data interface{} `json:"data"` // 响应数据
|
||
}
|
||
```
|
||
|
||
### 分页响应结构
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"timestamp": 1704067200,
|
||
"data": {
|
||
"list": [],
|
||
"total": 100,
|
||
"page": 1,
|
||
"pageSize": 10
|
||
}
|
||
}
|
||
```
|
||
|
||
**结构体类型（暴露在 factory 中）：**
|
||
|
||
```go
|
||
// 在 factory 包中可以直接使用
|
||
type PageData struct {
|
||
List interface{} `json:"list"` // 数据列表
|
||
Total int64 `json:"total"` // 总记录数
|
||
Page int `json:"page"` // 当前页码
|
||
PageSize int `json:"pageSize"` // 每页大小
|
||
}
|
||
|
||
type PageResponse struct {
|
||
Code int `json:"code"`
|
||
Message string `json:"message"`
|
||
Timestamp int64 `json:"timestamp"`
|
||
Data *PageData `json:"data"`
|
||
}
|
||
```
|
||
|
||
### 使用暴露的结构体
|
||
|
||
外部项目可以直接使用 `factory.Response`、`factory.PageData` 等类型：
|
||
|
||
```go
|
||
import "git.toowon.com/jimmy/go-common/factory"
|
||
|
||
// 创建标准响应对象
|
||
response := factory.Response{
|
||
Code: 0,
|
||
Message: "success",
|
||
Data: userData,
|
||
}
|
||
|
||
// 创建分页数据对象
|
||
pageData := &factory.PageData{
|
||
List: users,
|
||
Total: 100,
|
||
Page: 1,
|
||
PageSize: 20,
|
||
}
|
||
|
||
// 传递给 Success 方法
|
||
fac.Success(w, pageData)
|
||
```
|
||
|
||
## 使用方法
|
||
|
||
### 方式一：使用Factory黑盒方法（推荐）⭐
|
||
|
||
这是最简单的方式，直接使用 `factory.Success()` 等方法：
|
||
|
||
```go
|
||
import (
|
||
"net/http"
|
||
"git.toowon.com/jimmy/go-common/factory"
|
||
commonhttp "git.toowon.com/jimmy/go-common/http"
|
||
"git.toowon.com/jimmy/go-common/tools"
|
||
)
|
||
|
||
func GetUser(w http.ResponseWriter, r *http.Request) {
|
||
fac, _ := factory.NewFactoryFromFile("config.json")
|
||
|
||
// 获取查询参数（使用类型转换方法）
|
||
id := tools.ConvertInt64(r.URL.Query().Get("id"), 0)
|
||
|
||
// 返回成功响应（使用factory方法）
|
||
fac.Success(w, data)
|
||
}
|
||
|
||
func CreateUser(w http.ResponseWriter, r *http.Request) {
|
||
fac, _ := factory.NewFactoryFromFile("config.json")
|
||
|
||
// 解析JSON（使用公共方法）
|
||
var req struct {
|
||
Name string `json:"name"`
|
||
}
|
||
if err := commonhttp.ParseJSON(r, &req); err != nil {
|
||
commonhttp.WriteJSON(w, http.StatusBadRequest, 400, "请求参数解析失败", nil)
|
||
return
|
||
}
|
||
|
||
// 返回成功响应（使用factory方法）
|
||
fac.Success(w, data, "创建成功")
|
||
}
|
||
|
||
func GetUserList(w http.ResponseWriter, r *http.Request) {
|
||
fac, _ := factory.NewFactoryFromFile("config.json")
|
||
|
||
// 获取分页参数（使用factory方法，推荐）
|
||
pagination := fac.ParsePaginationRequest(r)
|
||
page := pagination.GetPage()
|
||
pageSize := pagination.GetPageSize()
|
||
|
||
// 获取查询参数（直接使用HTTP原生方法）
|
||
keyword := r.URL.Query().Get("keyword")
|
||
|
||
// 查询数据
|
||
list, total := getDataList(keyword, page, pageSize)
|
||
|
||
// 返回分页响应（使用factory方法）
|
||
fac.SuccessPage(w, list, total, page, pageSize)
|
||
}
|
||
|
||
// 注册路由
|
||
http.HandleFunc("/user", GetUser)
|
||
http.HandleFunc("/users", GetUserList)
|
||
```
|
||
|
||
### 方式二：直接使用公共方法
|
||
|
||
如果不想使用Factory，可以直接使用 `http` 包的公共方法：
|
||
|
||
```go
|
||
import (
|
||
"net/http"
|
||
commonhttp "git.toowon.com/jimmy/go-common/http"
|
||
"git.toowon.com/jimmy/go-common/tools"
|
||
)
|
||
|
||
func GetUser(w http.ResponseWriter, r *http.Request) {
|
||
// 获取查询参数
|
||
id := tools.ConvertInt64(r.URL.Query().Get("id"), 0)
|
||
|
||
// 返回成功响应
|
||
commonhttp.Success(w, data)
|
||
}
|
||
|
||
func CreateUser(w http.ResponseWriter, r *http.Request) {
|
||
// 解析JSON
|
||
var req struct {
|
||
Name string `json:"name"`
|
||
}
|
||
if err := commonhttp.ParseJSON(r, &req); err != nil {
|
||
commonhttp.WriteJSON(w, http.StatusBadRequest, 400, "请求参数解析失败", nil)
|
||
return
|
||
}
|
||
|
||
// 返回成功响应
|
||
commonhttp.Success(w, data, "创建成功")
|
||
}
|
||
```
|
||
|
||
### 成功响应
|
||
|
||
```go
|
||
// 使用Factory（推荐）
|
||
fac.Success(w, data) // 只有数据，使用默认消息 "success"
|
||
fac.Success(w, data, "操作成功") // 数据+消息
|
||
|
||
// 或直接使用公共方法
|
||
commonhttp.Success(w, data) // 只有数据
|
||
commonhttp.Success(w, data, "操作成功") // 数据+消息
|
||
```
|
||
|
||
### 错误响应
|
||
|
||
```go
|
||
// 使用Factory（推荐）
|
||
fac.Error(w, 1001, "用户不存在") // 业务错误（HTTP 200，业务code非0）
|
||
fac.SystemError(w, "服务器内部错误") // 系统错误（HTTP 500）
|
||
|
||
// 或直接使用公共方法
|
||
commonhttp.Error(w, 1001, "用户不存在")
|
||
commonhttp.SystemError(w, "服务器内部错误")
|
||
commonhttp.WriteJSON(w, http.StatusBadRequest, 400, "请求参数错误", nil) // 自定义HTTP状态码（仅公共方法）
|
||
```
|
||
|
||
### 分页响应
|
||
|
||
```go
|
||
// 使用Factory（推荐）
|
||
fac.SuccessPage(w, list, total, page, pageSize)
|
||
fac.SuccessPage(w, list, total, page, pageSize, "查询成功")
|
||
|
||
// 或直接使用公共方法
|
||
commonhttp.SuccessPage(w, list, total, page, pageSize)
|
||
commonhttp.SuccessPage(w, list, total, page, pageSize, "查询成功")
|
||
```
|
||
|
||
### 解析请求
|
||
|
||
#### 解析JSON请求体
|
||
|
||
```go
|
||
// 使用公共方法
|
||
var req struct {
|
||
Name string `json:"name"`
|
||
Email string `json:"email"`
|
||
}
|
||
|
||
if err := commonhttp.ParseJSON(r, &req); err != nil {
|
||
commonhttp.WriteJSON(w, http.StatusBadRequest, 400, "请求参数解析失败", nil)
|
||
return
|
||
}
|
||
```
|
||
|
||
#### 获取查询参数
|
||
|
||
```go
|
||
import "git.toowon.com/jimmy/go-common/tools"
|
||
|
||
// 字符串直接获取
|
||
name := r.URL.Query().Get("name")
|
||
|
||
// 使用类型转换方法
|
||
id := tools.ConvertInt(r.URL.Query().Get("id"), 0)
|
||
userId := tools.ConvertInt64(r.URL.Query().Get("userId"), 0)
|
||
isActive := tools.ConvertBool(r.URL.Query().Get("isActive"), false)
|
||
price := tools.ConvertFloat64(r.URL.Query().Get("price"), 0.0)
|
||
```
|
||
|
||
#### 获取表单参数
|
||
|
||
```go
|
||
import "git.toowon.com/jimmy/go-common/tools"
|
||
|
||
// 字符串直接获取
|
||
name := r.FormValue("name")
|
||
|
||
// 使用类型转换方法
|
||
age := tools.ConvertInt(r.FormValue("age"), 0)
|
||
userId := tools.ConvertInt64(r.FormValue("userId"), 0)
|
||
isActive := tools.ConvertBool(r.FormValue("isActive"), false)
|
||
```
|
||
|
||
#### 获取请求头
|
||
|
||
```go
|
||
// 直接使用HTTP原生方法
|
||
token := r.Header.Get("Authorization")
|
||
contentType := r.Header.Get("Content-Type")
|
||
if contentType == "" {
|
||
contentType = "application/json" // 设置默认值
|
||
}
|
||
```
|
||
|
||
#### 获取分页参数
|
||
|
||
**方式1：使用 PaginationRequest 结构（推荐）**
|
||
|
||
```go
|
||
// 定义请求结构（包含分页字段）
|
||
type ListUserRequest struct {
|
||
Keyword string `json:"keyword"`
|
||
commonhttp.PaginationRequest // 嵌入分页请求结构
|
||
}
|
||
|
||
// 从JSON请求体解析（分页字段会自动解析）
|
||
var req ListUserRequest
|
||
if err := commonhttp.ParseJSON(r, &req); err != nil {
|
||
commonhttp.WriteJSON(w, http.StatusBadRequest, 400, "请求参数解析失败", nil)
|
||
return
|
||
}
|
||
|
||
// 使用分页方法
|
||
page := req.GetPage() // 获取页码（默认1）
|
||
pageSize := req.GetPageSize() // 获取每页数量（默认20，最大100）
|
||
offset := req.GetOffset() // 计算偏移量
|
||
```
|
||
|
||
**方式2：从查询参数/form解析分页**
|
||
|
||
```go
|
||
// 使用公共方法
|
||
pagination := commonhttp.ParsePaginationRequest(r)
|
||
page := pagination.GetPage()
|
||
pageSize := pagination.GetPageSize()
|
||
offset := pagination.GetOffset()
|
||
```
|
||
|
||
#### 获取时区
|
||
|
||
```go
|
||
// 使用公共方法
|
||
// 如果使用了middleware.Timezone中间件，可以从context中获取时区信息
|
||
// 如果未设置，返回默认时区 AsiaShanghai
|
||
timezone := commonhttp.GetTimezone(r)
|
||
```
|
||
|
||
## 完整示例
|
||
|
||
### 使用Factory（推荐）
|
||
|
||
```go
|
||
package main
|
||
|
||
import (
|
||
"log"
|
||
"net/http"
|
||
"git.toowon.com/jimmy/go-common/factory"
|
||
commonhttp "git.toowon.com/jimmy/go-common/http"
|
||
"git.toowon.com/jimmy/go-common/tools"
|
||
)
|
||
|
||
// 用户结构
|
||
type User struct {
|
||
ID int64 `json:"id"`
|
||
Name string `json:"name"`
|
||
Email string `json:"email"`
|
||
}
|
||
|
||
// 用户列表接口
|
||
func GetUserList(w http.ResponseWriter, r *http.Request) {
|
||
fac, _ := factory.NewFactoryFromFile("config.json")
|
||
|
||
// 获取分页参数（使用公共方法）
|
||
pagination := commonhttp.ParsePaginationRequest(r)
|
||
page := pagination.GetPage()
|
||
pageSize := pagination.GetPageSize()
|
||
|
||
// 获取查询参数（直接使用HTTP原生方法）
|
||
keyword := r.URL.Query().Get("keyword")
|
||
|
||
// 查询数据
|
||
users, total := queryUsers(keyword, page, pageSize)
|
||
|
||
// 返回分页响应（使用factory方法）
|
||
fac.SuccessPage(w, users, total, page, pageSize)
|
||
}
|
||
|
||
// 创建用户接口
|
||
func CreateUser(w http.ResponseWriter, r *http.Request) {
|
||
fac, _ := factory.NewFactoryFromFile("config.json")
|
||
|
||
// 解析请求体（使用公共方法）
|
||
var req struct {
|
||
Name string `json:"name"`
|
||
Email string `json:"email"`
|
||
}
|
||
|
||
if err := commonhttp.ParseJSON(r, &req); err != nil {
|
||
fac.WriteJSON(w, http.StatusBadRequest, 400, "请求参数解析失败", nil)
|
||
return
|
||
}
|
||
|
||
// 参数验证
|
||
if req.Name == "" {
|
||
fac.Error(w, 1001, "用户名不能为空")
|
||
return
|
||
}
|
||
|
||
// 创建用户
|
||
user, err := createUser(req.Name, req.Email)
|
||
if err != nil {
|
||
fac.SystemError(w, "创建用户失败")
|
||
return
|
||
}
|
||
|
||
// 返回成功响应（使用factory方法）
|
||
fac.Success(w, user, "创建成功")
|
||
}
|
||
|
||
// 获取用户详情接口
|
||
func GetUser(w http.ResponseWriter, r *http.Request) {
|
||
fac, _ := factory.NewFactoryFromFile("config.json")
|
||
|
||
// 获取查询参数（使用类型转换方法）
|
||
id := tools.ConvertInt64(r.URL.Query().Get("id"), 0)
|
||
|
||
if id == 0 {
|
||
commonhttp.WriteJSON(w, http.StatusBadRequest, 400, "用户ID不能为空", nil)
|
||
return
|
||
}
|
||
|
||
// 查询用户
|
||
user, err := getUserByID(id)
|
||
if err != nil {
|
||
fac.SystemError(w, "查询用户失败")
|
||
return
|
||
}
|
||
|
||
if user == nil {
|
||
fac.Error(w, 1002, "用户不存在")
|
||
return
|
||
}
|
||
|
||
// 返回成功响应（使用factory方法）
|
||
fac.Success(w, user)
|
||
}
|
||
|
||
func main() {
|
||
http.HandleFunc("/users", func(w http.ResponseWriter, r *http.Request) {
|
||
switch r.Method {
|
||
case http.MethodGet:
|
||
GetUserList(w, r)
|
||
case http.MethodPost:
|
||
CreateUser(w, r)
|
||
default:
|
||
commonhttp.WriteJSON(w, http.StatusMethodNotAllowed, 405, "方法不支持", nil)
|
||
}
|
||
})
|
||
|
||
http.HandleFunc("/user", GetUser)
|
||
|
||
log.Println("Server started on :8080")
|
||
log.Fatal(http.ListenAndServe(":8080", nil))
|
||
}
|
||
```
|
||
|
||
## API 参考
|
||
|
||
### Factory HTTP响应结构体（暴露给外部项目使用）
|
||
|
||
#### Response
|
||
|
||
标准响应结构体，外部项目可以直接使用 `factory.Response`。
|
||
|
||
**字段：**
|
||
- `Code`: 业务状态码，0表示成功
|
||
- `Message`: 响应消息
|
||
- `Timestamp`: 时间戳（Unix时间戳，秒）
|
||
- `Data`: 响应数据
|
||
|
||
**示例：**
|
||
```go
|
||
response := factory.Response{
|
||
Code: 0,
|
||
Message: "success",
|
||
Data: userData,
|
||
}
|
||
```
|
||
|
||
#### PageData
|
||
|
||
分页数据结构体，外部项目可以直接使用 `factory.PageData`。
|
||
|
||
**字段：**
|
||
- `List`: 数据列表
|
||
- `Total`: 总记录数
|
||
- `Page`: 当前页码
|
||
- `PageSize`: 每页大小
|
||
|
||
**示例：**
|
||
```go
|
||
pageData := &factory.PageData{
|
||
List: users,
|
||
Total: 100,
|
||
Page: 1,
|
||
PageSize: 20,
|
||
}
|
||
fac.Success(w, pageData)
|
||
```
|
||
|
||
#### PageResponse
|
||
|
||
分页响应结构体，外部项目可以直接使用 `factory.PageResponse`。
|
||
|
||
**字段：**
|
||
- `Code`: 业务状态码
|
||
- `Message`: 响应消息
|
||
- `Timestamp`: 时间戳
|
||
- `Data`: 分页数据（*PageData）
|
||
|
||
### Factory HTTP响应方法（推荐使用）
|
||
|
||
#### (f *Factory) Success(w http.ResponseWriter, data interface{}, message ...string)
|
||
|
||
成功响应，HTTP 200，业务code 0。
|
||
|
||
**参数：**
|
||
- `data`: 响应数据，可以为nil
|
||
- `message`: 响应消息（可选），如果为空则使用默认消息 "success"
|
||
|
||
**示例：**
|
||
```go
|
||
fac.Success(w, data) // 只有数据，使用默认消息 "success"
|
||
fac.Success(w, data, "操作成功") // 数据+消息
|
||
```
|
||
|
||
#### (f *Factory) Error(w http.ResponseWriter, code int, message string)
|
||
|
||
业务错误响应，HTTP 200，业务code非0。
|
||
|
||
**示例：**
|
||
```go
|
||
fac.Error(w, 1001, "用户不存在")
|
||
```
|
||
|
||
#### (f *Factory) SystemError(w http.ResponseWriter, message string)
|
||
|
||
系统错误响应，HTTP 500，业务code 500。
|
||
|
||
**示例：**
|
||
```go
|
||
fac.SystemError(w, "服务器内部错误")
|
||
```
|
||
|
||
#### (f *Factory) WriteJSON(w http.ResponseWriter, httpCode, code int, message string, data interface{})
|
||
|
||
写入JSON响应（自定义）。
|
||
|
||
**参数：**
|
||
- `httpCode`: HTTP状态码
|
||
- `code`: 业务状态码
|
||
- `message`: 响应消息
|
||
- `data`: 响应数据
|
||
|
||
**说明：**
|
||
- 此方法不在 Factory 中，直接使用 `commonhttp.WriteJSON()`
|
||
- 用于需要自定义HTTP状态码的场景（如 400, 401, 403, 404 等）
|
||
|
||
**示例：**
|
||
```go
|
||
commonhttp.WriteJSON(w, http.StatusBadRequest, 400, "请求参数错误", nil)
|
||
commonhttp.WriteJSON(w, http.StatusUnauthorized, 401, "未登录", nil)
|
||
```
|
||
|
||
#### (f *Factory) SuccessPage(w http.ResponseWriter, list interface{}, total int64, page, pageSize int, message ...string)
|
||
|
||
分页成功响应。
|
||
|
||
**参数：**
|
||
- `list`: 数据列表
|
||
- `total`: 总记录数
|
||
- `page`: 当前页码
|
||
- `pageSize`: 每页大小
|
||
- `message`: 响应消息（可选，如果为空则使用默认消息 "success"）
|
||
|
||
**示例：**
|
||
```go
|
||
fac.SuccessPage(w, users, total, page, pageSize)
|
||
fac.SuccessPage(w, users, total, page, pageSize, "查询成功")
|
||
```
|
||
|
||
### HTTP公共方法（直接使用）
|
||
|
||
#### WriteJSON(w http.ResponseWriter, httpCode, code int, message string, data interface{})
|
||
|
||
写入JSON响应（自定义HTTP状态码和业务状态码）。
|
||
|
||
**说明：**
|
||
- 此方法不在 Factory 中，直接使用 `commonhttp.WriteJSON()`
|
||
- 用于需要自定义HTTP状态码的场景（如 400, 401, 403, 404 等）
|
||
|
||
**示例：**
|
||
```go
|
||
commonhttp.WriteJSON(w, http.StatusBadRequest, 400, "请求参数错误", nil)
|
||
commonhttp.WriteJSON(w, http.StatusUnauthorized, 401, "未登录", nil)
|
||
```
|
||
|
||
#### ParseJSON(r *http.Request, v interface{}) error
|
||
|
||
解析JSON请求体。
|
||
|
||
**示例：**
|
||
```go
|
||
var req CreateUserRequest
|
||
if err := commonhttp.ParseJSON(r, &req); err != nil {
|
||
// 处理错误
|
||
}
|
||
```
|
||
|
||
#### 获取查询参数和表单参数
|
||
|
||
**推荐方式：使用类型转换工具**
|
||
|
||
```go
|
||
import "git.toowon.com/jimmy/go-common/tools"
|
||
|
||
// 字符串直接使用HTTP原生方法
|
||
name := r.URL.Query().Get("name")
|
||
if name == "" {
|
||
name = "default" // 设置默认值
|
||
}
|
||
|
||
// 类型转换使用tools包
|
||
id := tools.ConvertInt(r.URL.Query().Get("id"), 0)
|
||
userId := tools.ConvertInt64(r.URL.Query().Get("userId"), 0)
|
||
isActive := tools.ConvertBool(r.URL.Query().Get("isActive"), false)
|
||
price := tools.ConvertFloat64(r.URL.Query().Get("price"), 0.0)
|
||
|
||
// 表单参数类似
|
||
age := tools.ConvertInt(r.FormValue("age"), 0)
|
||
```
|
||
|
||
**类型转换方法说明：**
|
||
|
||
- `tools.ConvertInt(value string, defaultValue int) int` - 转换为int
|
||
- `tools.ConvertInt64(value string, defaultValue int64) int64` - 转换为int64
|
||
- `tools.ConvertUint64(value string, defaultValue uint64) uint64` - 转换为uint64
|
||
- `tools.ConvertUint32(value string, defaultValue uint32) uint32` - 转换为uint32
|
||
- `tools.ConvertBool(value string, defaultValue bool) bool` - 转换为bool
|
||
- `tools.ConvertFloat64(value string, defaultValue float64) float64` - 转换为float64
|
||
|
||
**获取请求头：**
|
||
|
||
```go
|
||
// 直接使用HTTP原生方法
|
||
token := r.Header.Get("Authorization")
|
||
contentType := r.Header.Get("Content-Type")
|
||
```
|
||
|
||
#### ParsePaginationRequest(r *http.Request) *PaginationRequest
|
||
|
||
从请求中解析分页参数。
|
||
|
||
**说明：**
|
||
- 支持从查询参数和form表单中解析
|
||
- 优先级：查询参数 > form表单
|
||
- 如果请求体是JSON格式且包含分页字段，建议先使用`ParseJSON`解析完整请求体到包含`PaginationRequest`的结构体中
|
||
|
||
#### GetTimezone(r *http.Request) string
|
||
|
||
从请求的context中获取时区。
|
||
|
||
**说明：**
|
||
- 如果使用了middleware.Timezone中间件，可以从context中获取时区信息
|
||
- 如果未设置，返回默认时区 AsiaShanghai
|
||
|
||
#### Success(w http.ResponseWriter, data interface{}, message ...string)
|
||
|
||
成功响应（公共方法）。
|
||
|
||
**参数：**
|
||
- `data`: 响应数据，可以为nil
|
||
- `message`: 响应消息（可选），如果为空则使用默认消息 "success"
|
||
|
||
**示例：**
|
||
```go
|
||
commonhttp.Success(w, data) // 只有数据
|
||
commonhttp.Success(w, data, "操作成功") // 数据+消息
|
||
```
|
||
|
||
#### Error(w http.ResponseWriter, code int, message string)
|
||
|
||
错误响应（公共方法）。
|
||
|
||
#### SystemError(w http.ResponseWriter, message string)
|
||
|
||
系统错误响应（公共方法）。
|
||
|
||
#### WriteJSON(w http.ResponseWriter, httpCode, code int, message string, data interface{})
|
||
|
||
写入JSON响应（公共方法，不在Factory中）。
|
||
|
||
**说明：**
|
||
- 用于需要自定义HTTP状态码的场景
|
||
- 直接使用 `commonhttp.WriteJSON()`，不在 Factory 中
|
||
|
||
#### SuccessPage(w http.ResponseWriter, list interface{}, total int64, page, pageSize int, message ...string)
|
||
|
||
分页成功响应（公共方法）。
|
||
|
||
### 分页请求结构
|
||
|
||
#### PaginationRequest
|
||
|
||
分页请求结构，支持从JSON和form中解析分页参数。
|
||
|
||
**字段：**
|
||
- `Page`: 页码（默认1）
|
||
- `PageSize`: 每页数量
|
||
|
||
**方法：**
|
||
- `GetPage() int`: 获取页码，如果未设置则返回默认值1
|
||
- `GetPageSize() int`: 获取每页数量，如果未设置则返回默认值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. **推荐使用Factory**：
|
||
- 使用 `factory.Success()` 等方法，代码更简洁
|
||
- 直接使用 `http` 包的公共方法，保持低耦合
|
||
- 不需要Handler结构，减少不必要的封装
|
||
|
||
## 示例
|
||
|
||
完整示例请参考：
|
||
- `examples/http_handler_example.go` - 使用Factory和公共方法
|
||
- `examples/http_pagination_example.go` - 分页示例
|
||
- `examples/factory_blackbox_example.go` - Factory黑盒模式示例
|