jimmy/go-common
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

将工厂改成黑盒模式,降低用户使用成本

Browse Source
This commit is contained in:
Jimmy Xue
2025-11-30 15:54:27 +08:00
parent 6323b49517
commit d454d8e143
18 changed files with 2075 additions and 1046 deletions
Download Patch File Download Diff File Expand all files Collapse all files

279
http/handler.go Normal file
View File

@@ -0,0 +1,279 @@
package http
import (
"context"
"encoding/json"
"io"
"net/http"
"strconv"
"git.toowon.com/jimmy/go-common/middleware"
)
// Handler HTTP处理器包装器，封装ResponseWriter和Request，提供简洁的API
type Handler struct {
w http.ResponseWriter
r *http.Request
}
// NewHandler 创建Handler实例
func NewHandler(w http.ResponseWriter, r *http.Request) *Handler {
return &Handler{
w: w,
r: r,
}
}
// ResponseWriter 获取原始的ResponseWriter（需要时使用）
func (h *Handler) ResponseWriter() http.ResponseWriter {
return h.w
}
// Request 获取原始的Request（需要时使用）
func (h *Handler) Request() *http.Request {
return h.r
}
// Context 获取请求的Context
func (h *Handler) Context() context.Context {
return h.r.Context()
}
// ========== 响应方法（黑盒模式） ==========
// Success 成功响应
// data: 响应数据，可以为nil
func (h *Handler) Success(data interface{}) {
writeJSON(h.w, http.StatusOK, 0, "success", data)
}
// SuccessWithMessage 带消息的成功响应
func (h *Handler) SuccessWithMessage(message string, data interface{}) {
writeJSON(h.w, http.StatusOK, 0, message, data)
}
// Error 错误响应
// code: 业务错误码，非0表示业务错误
// message: 错误消息
func (h *Handler) Error(code int, message string) {
writeJSON(h.w, http.StatusOK, code, message, nil)
}
// SystemError 系统错误响应（返回HTTP 500）
// message: 错误消息
func (h *Handler) SystemError(message string) {
writeJSON(h.w, http.StatusInternalServerError, 500, message, nil)
}
// WriteJSON 写入JSON响应（自定义HTTP状态码和业务状态码）
// httpCode: HTTP状态码（200表示正常，500表示系统错误等）
// code: 业务状态码（0表示成功，非0表示业务错误）
// message: 响应消息
// data: 响应数据
func (h *Handler) WriteJSON(httpCode, code int, message string, data interface{}) {
writeJSON(h.w, httpCode, code, message, data)
}
// SuccessPage 分页成功响应
// list: 数据列表
// total: 总记录数
// page: 当前页码
// pageSize: 每页大小
// message: 响应消息（可选，如果为空则使用默认消息 "success"）
func (h *Handler) SuccessPage(list interface{}, total int64, page, pageSize int, message ...string) {
msg := "success"
if len(message) > 0 && message[0] != "" {
msg = message[0]
}
pageData := &PageData{
List: list,
Total: total,
Page: page,
PageSize: pageSize,
}
writeJSON(h.w, http.StatusOK, 0, msg, pageData)
}
// ========== 请求解析方法（黑盒模式） ==========
// ParseJSON 解析JSON请求体
// v: 目标结构体指针
func (h *Handler) ParseJSON(v interface{}) error {
body, err := io.ReadAll(h.r.Body)
if err != nil {
return err
}
defer h.r.Body.Close()
if len(body) == 0 {
return nil
}
return json.Unmarshal(body, v)
}
// GetQuery 获取查询参数
// key: 参数名
// defaultValue: 默认值
func (h *Handler) GetQuery(key, defaultValue string) string {
value := h.r.URL.Query().Get(key)
if value == "" {
return defaultValue
}
return value
}
// GetQueryInt 获取整数查询参数
// key: 参数名
// defaultValue: 默认值
func (h *Handler) GetQueryInt(key string, defaultValue int) int {
value := h.r.URL.Query().Get(key)
if value == "" {
return defaultValue
}
intValue, err := strconv.Atoi(value)
if err != nil {
return defaultValue
}
return intValue
}
// GetQueryInt64 获取int64查询参数
func (h *Handler) GetQueryInt64(key string, defaultValue int64) int64 {
value := h.r.URL.Query().Get(key)
if value == "" {
return defaultValue
}
intValue, err := strconv.ParseInt(value, 10, 64)
if err != nil {
return defaultValue
}
return intValue
}
// GetQueryBool 获取布尔查询参数
func (h *Handler) GetQueryBool(key string, defaultValue bool) bool {
value := h.r.URL.Query().Get(key)
if value == "" {
return defaultValue
}
boolValue, err := strconv.ParseBool(value)
if err != nil {
return defaultValue
}
return boolValue
}
// GetQueryFloat64 获取float64查询参数
func (h *Handler) GetQueryFloat64(key string, defaultValue float64) float64 {
value := h.r.URL.Query().Get(key)
if value == "" {
return defaultValue
}
floatValue, err := strconv.ParseFloat(value, 64)
if err != nil {
return defaultValue
}
return floatValue
}
// GetFormValue 获取表单值
func (h *Handler) GetFormValue(key, defaultValue string) string {
value := h.r.FormValue(key)
if value == "" {
return defaultValue
}
return value
}
// GetFormInt 获取表单整数
func (h *Handler) GetFormInt(key string, defaultValue int) int {
value := h.r.FormValue(key)
if value == "" {
return defaultValue
}
intValue, err := strconv.Atoi(value)
if err != nil {
return defaultValue
}
return intValue
}
// GetFormInt64 获取表单int64
func (h *Handler) GetFormInt64(key string, defaultValue int64) int64 {
value := h.r.FormValue(key)
if value == "" {
return defaultValue
}
intValue, err := strconv.ParseInt(value, 10, 64)
if err != nil {
return defaultValue
}
return intValue
}
// GetFormBool 获取表单布尔值
func (h *Handler) GetFormBool(key string, defaultValue bool) bool {
value := h.r.FormValue(key)
if value == "" {
return defaultValue
}
boolValue, err := strconv.ParseBool(value)
if err != nil {
return defaultValue
}
return boolValue
}
// GetHeader 获取请求头
func (h *Handler) GetHeader(key, defaultValue string) string {
value := h.r.Header.Get(key)
if value == "" {
return defaultValue
}
return value
}
// ParsePaginationRequest 从请求中解析分页参数
// 支持从查询参数和form表单中解析
// 优先级：查询参数 > form表单
func (h *Handler) ParsePaginationRequest() *PaginationRequest {
return ParsePaginationRequest(h.r)
}
// GetTimezone 从请求的context中获取时区
// 如果使用了middleware.Timezone中间件，可以从context中获取时区信息
// 如果未设置，返回默认时区 AsiaShanghai
func (h *Handler) GetTimezone() string {
return middleware.GetTimezoneFromContext(h.r.Context())
}
// HandleFunc 将Handler函数转换为标准的http.HandlerFunc
// 这样可以将Handler函数直接用于http.HandleFunc
// 示例：
//
// http.HandleFunc("/users", http.HandleFunc(func(h *http.Handler) {
// h.Success(data)
// }))
func HandleFunc(fn func(*Handler)) http.HandlerFunc {
return func(w http.ResponseWriter, r *http.Request) {
h := NewHandler(w, r)
fn(h)
}
}

231
http/request.go
View File

@@ -1,49 +1,12 @@
package http
import (
"context"
"encoding/json"
"io"
"net/http"
"strconv"
"git.toowon.com/jimmy/go-common/middleware"
)
// ParseJSON 解析JSON请求体
// r: HTTP请求
// v: 目标结构体指针
func ParseJSON(r *http.Request, v interface{}) error {
body, err := io.ReadAll(r.Body)
if err != nil {
return err
}
defer r.Body.Close()
if len(body) == 0 {
return nil
}
return json.Unmarshal(body, v)
}
// GetQuery 获取查询参数
// r: HTTP请求
// key: 参数名
// defaultValue: 默认值
func GetQuery(r *http.Request, key, defaultValue string) string {
value := r.URL.Query().Get(key)
if value == "" {
return defaultValue
}
return value
}
// GetQueryInt 获取整数查询参数
// r: HTTP请求
// key: 参数名
// defaultValue: 默认值
func GetQueryInt(r *http.Request, key string, defaultValue int) int {
// getQueryInt 获取整数查询参数（内部方法，供ParsePaginationRequest使用）
func getQueryInt(r *http.Request, key string, defaultValue int) int {
value := r.URL.Query().Get(key)
if value == "" {
return defaultValue
@@ -57,62 +20,8 @@ func GetQueryInt(r *http.Request, key string, defaultValue int) int {
return intValue
}
// GetQueryInt64 获取int64查询参数
func GetQueryInt64(r *http.Request, key string, defaultValue int64) int64 {
value := r.URL.Query().Get(key)
if value == "" {
return defaultValue
}
intValue, err := strconv.ParseInt(value, 10, 64)
if err != nil {
return defaultValue
}
return intValue
}
// GetQueryBool 获取布尔查询参数
func GetQueryBool(r *http.Request, key string, defaultValue bool) bool {
value := r.URL.Query().Get(key)
if value == "" {
return defaultValue
}
boolValue, err := strconv.ParseBool(value)
if err != nil {
return defaultValue
}
return boolValue
}
// GetQueryFloat64 获取float64查询参数
func GetQueryFloat64(r *http.Request, key string, defaultValue float64) float64 {
value := r.URL.Query().Get(key)
if value == "" {
return defaultValue
}
floatValue, err := strconv.ParseFloat(value, 64)
if err != nil {
return defaultValue
}
return floatValue
}
// GetFormValue 获取表单值
func GetFormValue(r *http.Request, key, defaultValue string) string {
value := r.FormValue(key)
if value == "" {
return defaultValue
}
return value
}
// GetFormInt 获取表单整数
func GetFormInt(r *http.Request, key string, defaultValue int) int {
// getFormInt 获取表单整数（内部方法，供ParsePaginationRequest使用）
func getFormInt(r *http.Request, key string, defaultValue int) int {
value := r.FormValue(key)
if value == "" {
return defaultValue
@@ -126,82 +35,82 @@ func GetFormInt(r *http.Request, key string, defaultValue int) int {
return intValue
}
// GetFormInt64 获取表单int64
func GetFormInt64(r *http.Request, key string, defaultValue int64) int64 {
value := r.FormValue(key)
if value == "" {
return defaultValue
}
intValue, err := strconv.ParseInt(value, 10, 64)
if err != nil {
return defaultValue
}
return intValue
// PaginationRequest 分页请求结构
// 支持从JSON和form中解析分页参数
type PaginationRequest struct {
Page int `json:"page" form:"page"` // 页码，默认1
Size int `json:"size" form:"size"` // 每页数量（兼容旧版本）
PageSize int `json:"page_size" form:"page_size"` // 每页数量（推荐使用）
}
// GetFormBool 获取表单布尔值
func GetFormBool(r *http.Request, key string, defaultValue bool) bool {
value := r.FormValue(key)
if value == "" {
return defaultValue
// GetPage 获取页码，如果未设置则返回默认值1
func (p *PaginationRequest) GetPage() int {
if p.Page <= 0 {
return 1
}
boolValue, err := strconv.ParseBool(value)
if err != nil {
return defaultValue
}
return boolValue
return p.Page
}
// GetHeader 获取请求头
func GetHeader(r *http.Request, key, defaultValue string) string {
value := r.Header.Get(key)
if value == "" {
return defaultValue
// GetSize 获取每页数量，如果未设置则返回默认值20，最大限制100
// 优先使用 PageSize 字段，如果未设置则使用 Size 字段（兼容旧版本）
func (p *PaginationRequest) GetSize() int {
size := p.PageSize
if size <= 0 {
size = p.Size // 兼容旧版本的 Size 字段
}
return value
if size <= 0 {
return 20 // 默认20条
}
if size > 100 {
return 100 // 最大100条
}
return size
}
// GetPaginationParams 获取分页参数
// 返回 page, pageSize
// 默认 page=1, pageSize=10
func GetPaginationParams(r *http.Request) (page, pageSize int) {
page = GetQueryInt(r, "page", 1)
pageSize = GetQueryInt(r, "pageSize", 10)
// 参数校验
if page < 1 {
page = 1
}
if pageSize < 1 {
pageSize = 10
}
if pageSize > 1000 {
pageSize = 1000 // 限制最大页面大小
}
return page, pageSize
// GetOffset 计算数据库查询的偏移量
func (p *PaginationRequest) GetOffset() int {
return (p.GetPage() - 1) * p.GetSize()
}
// GetOffset 根据页码和每页大小计算偏移量
func GetOffset(page, pageSize int) int {
if page < 1 {
page = 1
// getPaginationFromQuery 从查询参数获取分页参数（内部辅助方法）
func getPaginationFromQuery(r *http.Request) (page, size, pageSize int) {
page = getQueryInt(r, "page", 0)
size = getQueryInt(r, "size", 0)
pageSize = getQueryInt(r, "page_size", 0)
return
}
// getPaginationFromForm 从form表单获取分页参数（内部辅助方法）
func getPaginationFromForm(r *http.Request) (page, size, pageSize int) {
page = getFormInt(r, "page", 0)
size = getFormInt(r, "size", 0)
pageSize = getFormInt(r, "page_size", 0)
return
}
// ParsePaginationRequest 从请求中解析分页参数
// 支持从查询参数和form表单中解析
// 优先级：查询参数 > form表单
// 注意：如果请求体是JSON格式且包含分页字段，建议先使用ParseJSON解析完整请求体到包含PaginationRequest的结构体中
func ParsePaginationRequest(r *http.Request) *PaginationRequest {
req := &PaginationRequest{}
// 1. 从查询参数解析（优先级最高）
req.Page, req.Size, req.PageSize = getPaginationFromQuery(r)
// 2. 如果查询参数中没有，尝试从form表单解析
if req.Page == 0 || (req.Size == 0 && req.PageSize == 0) {
page, size, pageSize := getPaginationFromForm(r)
if req.Page == 0 && page != 0 {
req.Page = page
}
if req.Size == 0 && size != 0 {
req.Size = size
}
if req.PageSize == 0 && pageSize != 0 {
req.PageSize = pageSize
}
}
return (page - 1) * pageSize
}
// GetTimezone 从请求的context中获取时区
// 如果使用了middleware.Timezone中间件，可以从context中获取时区信息
// 如果未设置，返回默认时区 AsiaShanghai
func GetTimezone(r *http.Request) string {
return middleware.GetTimezoneFromContext(r.Context())
}
// GetTimezoneFromContext 从context中获取时区
func GetTimezoneFromContext(ctx context.Context) string {
return middleware.GetTimezoneFromContext(ctx)
return req
}

92
http/response.go
View File

@@ -30,56 +30,12 @@ type PageData struct {
PageSize int `json:"pageSize"` // 每页大小
}
// Success 成功响应
// data: 响应数据，可以为nil
func Success(w http.ResponseWriter, data interface{}) {
WriteJSON(w, http.StatusOK, 0, "success", data)
}
// SuccessWithMessage 带消息的成功响应
func SuccessWithMessage(w http.ResponseWriter, message string, data interface{}) {
WriteJSON(w, http.StatusOK, 0, message, data)
}
// Error 错误响应
// code: 业务错误码，非0表示业务错误
// message: 错误消息
func Error(w http.ResponseWriter, code int, message string) {
WriteJSON(w, http.StatusOK, code, message, nil)
}
// SystemError 系统错误响应（返回HTTP 500）
// message: 错误消息
func SystemError(w http.ResponseWriter, message string) {
WriteJSON(w, http.StatusInternalServerError, 500, message, nil)
}
// BadRequest 请求错误响应（HTTP 400）
func BadRequest(w http.ResponseWriter, message string) {
WriteJSON(w, http.StatusBadRequest, 400, message, nil)
}
// Unauthorized 未授权响应（HTTP 401）
func Unauthorized(w http.ResponseWriter, message string) {
WriteJSON(w, http.StatusUnauthorized, 401, message, nil)
}
// Forbidden 禁止访问响应（HTTP 403）
func Forbidden(w http.ResponseWriter, message string) {
WriteJSON(w, http.StatusForbidden, 403, message, nil)
}
// NotFound 未找到响应（HTTP 404）
func NotFound(w http.ResponseWriter, message string) {
WriteJSON(w, http.StatusNotFound, 404, message, nil)
}
// WriteJSON 写入JSON响应
// writeJSON 写入JSON响应（内部方法）
// httpCode: HTTP状态码（200表示正常，500表示系统错误等）
// code: 业务状态码（0表示成功，非0表示业务错误）
// message: 响应消息
// data: 响应数据
func WriteJSON(w http.ResponseWriter, httpCode, code int, message string, data interface{}) {
func writeJSON(w http.ResponseWriter, httpCode, code int, message string, data interface{}) {
w.Header().Set("Content-Type", "application/json; charset=utf-8")
w.WriteHeader(httpCode)
@@ -92,47 +48,3 @@ func WriteJSON(w http.ResponseWriter, httpCode, code int, message string, data i
json.NewEncoder(w).Encode(response)
}
// SuccessPage 分页成功响应
// list: 数据列表
// total: 总记录数
// page: 当前页码
// pageSize: 每页大小
func SuccessPage(w http.ResponseWriter, list interface{}, total int64, page, pageSize int) {
w.Header().Set("Content-Type", "application/json; charset=utf-8")
w.WriteHeader(http.StatusOK)
response := PageResponse{
Code: 0,
Message: "success",
Timestamp: time.Now().Unix(),
Data: &PageData{
List: list,
Total: total,
Page: page,
PageSize: pageSize,
},
}
json.NewEncoder(w).Encode(response)
}
// SuccessPageWithMessage 带消息的分页成功响应
func SuccessPageWithMessage(w http.ResponseWriter, message string, list interface{}, total int64, page, pageSize int) {
w.Header().Set("Content-Type", "application/json; charset=utf-8")
w.WriteHeader(http.StatusOK)
response := PageResponse{
Code: 0,
Message: message,
Timestamp: time.Now().Unix(),
Data: &PageData{
List: list,
Total: total,
Page: page,
PageSize: pageSize,
},
}
json.NewEncoder(w).Encode(response)
}