# go-bean

**Repository Path**: love_bass/go-bean

## Basic Information

- **Project Name**: go-bean
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-23
- **Last Updated**: 2025-10-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# go-bean

一个基于 Gin 封装的轻量服务框架，统一 Handler 上下文，简化路由注册，并同时支持 HTTP/2 与 HTTP/3（QUIC）。适合快速搭建安全的 API 服务。

## 特性
- 同时支持 `HTTP/2`、`HTTP/3` 或两者一起运行
- 简洁路由：只需提供 `Method`、`Path`、`Handler`
- 统一上下文 `bean.Context`，屏蔽底层 Gin 细节
- 内置可选 `CORS` 中间件
- 基于 `zap` 的日志注入

## 安装
```bash
go get gitee.com/love_bass/go-bean@latest
```

## 快速开始
```go
package main

import (
    bean "gitee.com/love_bass/go-bean"
    "go.uber.org/zap"
)

func main() {
    // 初始化日志
    logger, _ := zap.NewProduction()
    sugar := logger.Sugar()

    // 配置与路由
    cfg := &bean.Config{
        Port:               8443,
        Mode:               bean.MODE_BOTH,          // 可选：MODE_HTTP2 / MODE_HTTP3 / MODE_BOTH
        AllowedCORS:        true,
        InsecureSkipVerify: true,                    // 仅测试用，生产请使用有效证书
        Logger:             sugar,
        CertFile:           "server.crt",
        KeyFile:            "server.key",
        Routes: []bean.Route{
            {
                Method:       bean.MethodGet,
                RelativePath: "/ping",
                Handler: func(ctx bean.Context) {
                    ctx.JSON(200, map[string]string{"message": "pong"})
                },
            },
        },
    }

    // 启动服务
    srv := bean.NewServer(cfg)
    srv.StartServer()

    // 简单阻塞（实际项目建议使用 OS 信号优雅退出）
    select {}
}
```

## 优雅退出示例
```go
package main

import (
    bean "gitee.com/love_bass/go-bean"
    "go.uber.org/zap"
    "os"
    "os/signal"
    "syscall"
)

func main() {
    lg, _ := zap.NewDevelopment()
    sugar := lg.Sugar()

    cfg := &bean.Config{ /* 省略，参考上文 */ }
    srv := bean.NewServer(cfg)
    srv.StartServer()

    // 监听系统信号
    sigCh := make(chan os.Signal, 1)
    signal.Notify(sigCh, syscall.SIGINT, syscall.SIGTERM)

    <-sigCh
    sugar.Info("收到退出信号，开始关闭服务")
    srv.StopServer()
}
```

## 核心概念与 API

### 路由定义
- `type Route struct { Method Method; RelativePath string; Handler HandlerFunc }`
- `HandlerFunc` 形如：`func(ctx bean.Context)`，使用统一上下文接口。

### 统一上下文 `bean.Context`
- 响应：`Status(code)`, `JSON(code, obj)`, `String(code, format, ...)`
- 请求参数：`Param(key)`, `Query(key)`, `PostForm(key)`
- 绑定：`Bind(obj)`（JSON）
- 头部：`Header(key)`, `SetHeader(key, value)`
- 其他：`GetClientIP()`, `Method()`, `Path()`

### HTTP 方法枚举 `Method`
```go
const (
    MethodGet     Method = "GET"
    MethodHead    Method = "HEAD"
    MethodPost    Method = "POST"
    MethodPut     Method = "PUT"
    MethodPatch   Method = "PATCH"
    MethodDelete  Method = "DELETE"
    MethodOptions Method = "OPTIONS"
)
```

### 运行模式枚举 `Mode`
```go
const (
    MODE_BOTH  Mode = iota
    MODE_HTTP2 Mode = iota
    MODE_HTTP3 Mode = iota
)
```
- 当 `Mode == MODE_BOTH` 时，同时监听 `TCP(HTTP/2)` 与 `UDP(HTTP/3)`，地址 `0.0.0.0:<Port>`。

### 服务器接口 `Server`
- `StartServer()`：启动服务
- `StopServer()`：优雅关闭
- `GetServiceType() string`：返回 `HTTP2/HTTP3`、`HTTP2` 或 `HTTP3`

## CORS 支持
- 将 `Config.AllowedCORS = true` 即可启用内置中间件：
  - `Access-Control-Allow-Origin: *`
  - `Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS`
  - 预检请求（OPTIONS）直接返回 `204`
- 生产环境建议将 `Allow-Origin` 配置为指定域名。

## TLS 与安全
- 框架需要可用的 `CertFile` / `KeyFile`（PEM），否则启动失败。
- `InsecureSkipVerify` 仅用于测试环境；生产务必提供有效证书。
- HTTP/3 依赖 `UDP` 端口可用，云主机/防火墙需放行。

## 示例：POST JSON 绑定
```go
Routes: []bean.Route{
    {
        Method:       bean.MethodPost,
        RelativePath: "/echo",
        Handler: func(ctx bean.Context) {
            var body struct { Message string `json:"message"` }
            if err := ctx.Bind(&body); err != nil {
                ctx.JSON(400, map[string]string{"error": err.Error()})
                return
            }
            ctx.JSON(200, body)
        },
    },
}
```

## 依赖与环境
- Go：`go 1.25.1`
- 主要依赖：`github.com/gin-gonic/gin`, `github.com/quic-go/quic-go`, `go.uber.org/zap`

## 项目结构
```
├── config.go      # 配置与路由类型
├── context.go     # 上下文封装与 HandlerFunc
├── middleware.go  # 内置 CORS 中间件
├── mode.go        # 运行模式枚举
├── method.go      # HTTP 方法枚举
├── server.go      # 服务实现：HTTP/2 + HTTP/3
├── go.mod
├── go.sum
└── README.md
```

## 常见问题
- 启动时报 "加载证书文件失败"：检查证书/私钥路径与格式（PEM）。
- 浏览器访问 HTTP/3：确保浏览器支持 QUIC，并放行 UDP 端口；部分环境可能因网络策略而回退到 HTTP/2。

## 贡献
欢迎提交 Issue / PR 来完善文档与功能。