core

Core Web Framework v3 - 完整帮助文档

概述

Core 是一个用于快速开发企业级 Go 应用程序的 Web 框架，包括 RESTful API、Web 应用和后端服务。它受到 Tornado、Sinatra 和 Koa (Node.js) 的启发，并具有一些 Go 特有的功能，如接口和结构体嵌入。

主要特性

• 自动路由注册 - 无需手动配置路由
• Koa 风格开发 - 类似 Node.js Koa 框架的中间件链式调用
• 轻量级框架 - 简单易用，性能高效
• 多数据库支持 - MySQL、PostgreSQL、SQLite、ClickHouse
• 内置验证器 - 基于 go-playground/validator
• JSON/XML 支持 - 内置 JSON 和 XML 响应处理
• 文件上传 - 支持单文件和多文件上传
• WebSocket 支持 - 内置 WebSocket 处理
• 模板引擎 - 支持 HTML 模板渲染
• Fetch 客户端 - 独立 fetch 包，支持 API 调用、公共/单次 Header、Cookie、请求/响应 Hook
• Redis Cache - 独立 cache 包，支持 DB fallback、自动回填、singleflight 防击穿、空值缓存
• 中间件系统 - 灵活的中间件扩展机制
• ai-context - AI 的工作流程指南
• skills - 模式库和示例

参考文档：

• ./AI_CONTEXT.md - Core 框架完整上下文
• ./skills/ - 场景化开发模板

快速开始

安装

go get github.com/xs23933/core/v3

最小示例

package main

import "github.com/xs23933/core/v3"

type Handler struct {
    core.Handler
}

func (Handler) Get(c core.Ctx) {
    c.SendString("Hello, World!")
}

func init() {
    core.RegHandle(new(Handler))
}

func main() {
    app := core.New()
    app.Listen(":8080")
}

项目结构

project/
├── cmd/               # 命令行目录
│   └── main.go        # 主入口文件
├── config.yaml        # 配置文件
├── views/             # 模板文件
├── static/            # 静态文件
├── internal/          # 内部目录
    ├── handler/       # 处理器目录
    │   └── handler.go # 业务逻辑
    ├── models/        # 数据模型
    │   └── models.go  # 数据库模型定义
    ├── middleware/    # 中间件
    ├── service/       # (业务逻辑：事务操作，调用 dao/model)
    └── dao/           # (数据访问：复杂查询封装)

配置

config.yaml 示例

debug: true # 调试模式
network: tcp4 # 网络协议
listen: 8080 # 监听端口
prefork: false # 是否启用 prefork 模式
log: /var/log/myapp/app.log # 可选：日志文件路径
log_rotate:
  - size: 300M # 文件达到 300MB 后切割
  - daily # 每日切割
  - rotate: 30 # 保留最近 30 天的切割日志
  - compress # 切割后的日志 gzip 压缩
  - delaycompress: 24h # 延迟压缩，需配合 compress
  - missingok # 日志文件不存在时不报错
  - notifempty # 空日志不切割
  - copytruncate # 复制后截断原文件，不替换当前文件句柄

# RESTful 响应格式配置
restful:
  data: data # 数据字段名
  status: success # 状态字段名
  message: msg # 消息字段名

# 数据库配置
database:
  type: sqlite3 # 数据库类型: mysql, pg, sqlite3, clickhouse
  dsn: dat # 数据库连接字符串
  # MySQL 示例: user:password@tcp(localhost:3306)/dbname?charset=utf8mb4&parseTime=True&loc=Local
  # PostgreSQL 示例: host=localhost user=postgres password=postgres dbname=test port=5432 sslmode=disable

核心概念

1. 应用 (Core)

应用是框架的核心，负责管理路由、中间件和服务器。

// 创建应用
app := core.New(core.LoadConfigFile("config.yaml"))

// 启动服务器
app.Listen()

2. 上下文 (Ctx)

上下文对象封装了 HTTP 请求和响应，提供了丰富的操作方法。

func (Handler) Get(c core.Ctx) {
    // 获取请求信息
    method := c.Method()      // 请求方法
    path := c.Path()          // 请求路径
    ip := c.RemoteIP()        // 客户端 IP

    // 获取参数
    id := c.Params("id")              // 路径参数
    name := c.Query("name")           // 查询参数
    age := c.QueryInt("age", 18)      // 查询参数转int

    // 获取表单数据
    email := c.FormValue("email")

    // 获取请求头
    token := c.GetHeader("Authorization")

    // 设置响应头
    c.SetHeader("Content-Type", "application/json")

    // 发送响应
    c.SendString("Hello")
    c.JSON(map[string]any{"code": 200, "msg": "success"})
    c.SendStatus(404, "Not Found")
}

3. 处理器 (Handler)

处理器是业务逻辑的载体，通过嵌入 core.Handler 来获得框架功能。

type UserHandler struct {
    core.Handler
}

// Init 定义Prefix 此Handler 下都加上了 /users group
func (UserHandler) Init() {
	core.Prefix("/users")
}

// GET /users
func (UserHandler) Get(c core.Ctx) {
    users, err := models.GetUsers()
    c.ToJSON(users, err)
}

// POST /users
func (UserHandler) Post(c core.Ctx) {
    var user models.User
    if err := c.ReadBody(&user); err != nil {
        c.ToJSON(nil, err)
        return
    }
    c.ToJSON(user, user.Save())
}

// GET /users/:id
func (UserHandler) GetByID(c core.Ctx) {
    id, err := c.ParamsUid("id")
    if err != nil {
        c.ToJSON(nil, err)
        return
    }
    user, err := models.GetUserByID(id)
    c.ToJSON(user, err)
}

// 自动注册路由
func init() {
    core.RegHandle(new(UserHandler))
}

4. 路由系统

框架支持自动路由注册，基于方法名和注释生成路由。

路由规则

关键字	路由规则	结果
Param	参数关键词	:param
Params	参数关键词	:params?
_id	下划线	/:id
By	参数关键字	/:
__	中横线	-
__dot__	点	.

Params 是可选关键词 即:params?

• Get → GET /
• GetParam → GET /:param
• GetParams → GET /:params?
• GetByID → GET /:id
• GetDetailParam → GET /detail/:param
• PostUser → POST /user
• PutUserParam → PUT /user/:param
• GetUserByID → GET /user/:id
• GetUser__Create → GET /user-create
• GetUser__dot__Html → GET /user.html

路由注释

// GetUser 获取用户信息
// get /user/:param
// @id: uid.UID 用户ID
func (Handler) GetUserParam(c core.Ctx) {
    id, err := c.ParamsUid("param")
	c.ToJSON(nil, err)
}

5. 数据模型

框架集成了 GORM，提供了便捷的数据库操作。

package models

import "github.com/xs23933/core/v3"

type User struct {
    core.Model
    Username string `json:"username" gorm:"size:32;uniqueIndex"`
    Email    string `json:"email" gorm:"size:128;uniqueIndex"`
    Password string `json:"-" gorm:"size:96"`
    Age      int    `json:"age" gorm:"default:18"`
}

// 创建用户
func (u *User) Create() error {
    return db.Create(u).Error
}

// 根据ID查询用户
func GetUserByID(id uid.UID) (user User, err error) {
    err = db.First(&user, "id = ?", id).Error
    return
}

// 分页查询用户
func GetUsers(page, size int) (users []User, total int64, err error) {
    err = db.Model(&User{}).Count(&total).Error
    if err != nil {
        return
    }
    offset := (page - 1) * size
    err = db.Offset(offset).Limit(size).Find(&users).Error
    return
}


var db *core.DB
// 初始化数据库
func InitDB() {
    db := core.Conn()
    db.AutoMigrate(&User{})
}

6. 中间件

框架支持灵活的中间件系统。

// 自定义中间件
func AuthMiddleware(next core.HandlerFunc) core.HandlerFunc {
    return func(c core.Ctx) error {
        token := c.GetHeader("Authorization")
        if token == "" {
            return c.SendStatus(401, "Unauthorized")
        }
        // 验证 token
        // ...
        return next(c)
    }
}

// 使用中间件
app.Use(AuthMiddleware)

// 路由级中间件
app.GET("/admin", AdminHandler, AuthMiddleware)

内置中间件

import (
    "github.com/xs23933/core/v3/middleware/requestid"
    "github.com/xs23933/core/v3/middleware/cors"
    "github.com/xs23933/core/v3/middleware/logger"
    "github.com/xs23933/core/v3/middleware/recover"
)

app.Use(requestid.New())  // 请求ID
app.Use(cors.New(app))    // CORS 支持
app.Use(logger.New())     // 请求日志
app.Use(recover.New())    // 异常恢复

7. 验证器

框架集成了 go-playground/validator，支持结构体验证。

type LoginForm struct {
    Username string `json:"username" validate:"required,min=3,max=32"`
    Password string `json:"password" validate:"required,min=6,max=128"`
    Email    string `json:"email" validate:"omitempty,email"`
}

func (Handler) Login(c core.Ctx) {
    var form LoginForm
    if err := c.ReadBody(&form); err != nil {
        c.ToJSON(nil, err)
        return
    }

    // 自动验证
    if err := c.Validate(&form); err != nil {
        c.ToJSON(nil, err)
        return
    }

    // 业务逻辑
    // ...
}

8. 文件上传

// 单文件上传
func (Handler) Upload(c core.Ctx) {
    file, err := c.FormFile("file")
    if err != nil {
        c.ToJSON(nil, err)
        return
    }

    // 保存文件
    relpath, abspath, err := c.SaveFile("file", "./uploads")
    if err != nil {
        c.ToJSON(nil, err)
        return
    }

    c.ToJSON(map[string]string{
        "filename": file.Filename,
        "path":     relpath,
        "size":     fmt.Sprintf("%d", file.Size),
    })
}

// 多文件上传
func (Handler) UploadMultiple(c core.Ctx) {
    files, err := c.SaveFiles("files", "./uploads")
    if err != nil {
        c.ToJSON(nil, err)
        return
    }

    c.ToJSON(files)
}

9. WebSocket 支持

import "github.com/xs23933/core/v3/websocket"


func main() {
	app := core.New()
	app.GET("/ws", websocket.New().
		OnConnect(func(c *websocket.Conn) {
			c.Send([]byte("Welcome to WebSocket"))
		}).
		OnMessage(
			func(c *websocket.Conn, mt websocket.MessageType, b []byte) {
				c.SendWithType(mt, b) //reply
                core.Info("Received message: %s", string(b))
			},
		).OnClose(func(c *websocket.Conn) {
		println("Connection closed")
	}).Handler())
	app.Run()
}

10. 模板渲染

import (
    "github.com/xs23933/core/v3/middleware/view"
    "github.com/xs23933/core/v3/middleware/view/html"
)

// 配置模板引擎
var viewEngine view.IEngine = html.NewHtmlView("./views", ".html", app.Debug)
app.Use(viewEngine)

// 渲染模板
func (Handler) Index(c core.Ctx) {
    c.Render("index", core.Map{
        "title": "首页",
        "users": []User{...},
    })
}

gRPC、etcd 与网关

Core 支持同时运行 HTTP 与 gRPC，并通过 etcd 做服务注册、服务发现和网关动态路由。推荐把链路拆成三类程序理解：

1. 业务服务：注册 protobuf 生成的 gRPC service，启动 gRPC，必要时注册到 etcd。
2. 内部客户端：通过 app.GrpcClient("service-name") 按服务名发现并调用 gRPC。
3. 网关服务：监听 etcd 服务变化，通过 gRPC reflection 自动发现方法并生成 HTTP 路由。

1. gRPC 服务

服务端必须先注册 gRPC service，再启动应用。只需要 gRPC 时使用 EnableGRPC；需要被网关发现时使用 EnableEtcdRegistry，它会自动创建/复用 gRPC server、注册服务到 etcd，并开启 gRPC reflection。

package main

import (
    "context"

    "github.com/xs23933/core/v3"
    "google.golang.org/grpc"

    pb "your_project/proto/user/v1"
)

type UserService struct {
    pb.UnimplementedUserServiceServer
}

func (s *UserService) GetProfile(ctx context.Context, req *pb.GetProfileRequest) (*pb.User, error) {
    return &pb.User{Id: req.Id, Name: "tom"}, nil
}

func main() {
    app := core.New()

    app.RegisterGRPCService(func(s *grpc.Server) {
        pb.RegisterUserServiceServer(s, &UserService{})
    })

    app.EnableGRPC(":9001")

    if err := app.Listen(":8080"); err != nil {
        panic(err)
    }
}

HTTP 和 gRPC 使用不同端口时，Listen(":8080") 负责 HTTP，EnableGRPC(":9001") 负责 gRPC。

如果希望 HTTP/1 和 gRPC 共用端口，可以让 EnableGRPC 使用和 Listen 相同的地址。框架会根据 HTTP/2 与 Content-Type: application/grpc 自动分流。

app.RegisterGRPCService(func(s *grpc.Server) {
    pb.RegisterUserServiceServer(s, &UserService{})
})
app.EnableGRPC(":8080")
app.Listen(":8080")

需要注册到 etcd 并提供给网关时：

app := core.New(core.LoadConfigFile("config.yaml"))

app.RegisterGRPCService(func(s *grpc.Server) {
    pb.RegisterUserServiceServer(s, &UserService{})
})

if err := app.EnableEtcdRegistry(nil); err != nil {
    panic(err)
}

if err := app.Listen(":8080"); err != nil {
    panic(err)
}

2. etcd 配置

EnableEtcdRegistry(nil) 会读取 etcd 配置。服务端最少需要配置 endpoints、service name 和暴露给其它进程访问的 service addr。

etcd:
  endpoints:
    - 127.0.0.1:2379
  dial_timeout: 5
  service_name: user-service
  service_addr: 127.0.0.1:8080
  service_id: user-service-1
  ttl: 10
  version: 1.0.0

也可以直接传 etcd.Options，适合测试或多环境注入：

if err := app.EnableEtcdRegistry(&etcd.Options{
    Endpoints:   []string{"127.0.0.1:2379"},
    ServiceName: "user-service",
    ServiceAddr: "127.0.0.1:8080",
    ServiceID:   "user-service-1",
    TTL:         10,
    Version:     "1.0.0",
    Metadata: map[string]string{
        "env": "dev",
    },
}); err != nil {
    panic(err)
}

注意：

• service_addr 必须是客户端和网关能访问到的地址，不一定等于本机监听地址。
• 使用网关自动注册路由时，优先用 EnableEtcdRegistry，因为它会自动开启 reflection。
• RegisterGRPCService 要在 Listen 或 Run 前调用。

3. gRPC 客户端

内部服务调用优先使用 GrpcClient，它会通过 etcd resolver 按服务名连接后端实例。

app := core.New(core.LoadConfigFile("config.yaml"))

conn, err := app.GrpcClient("user-service")
if err != nil {
    panic(err)
}
defer conn.Close()

client := pb.NewUserServiceClient(conn)

如果依赖 GrpcClient 自动初始化 discovery，客户端读取 etcd.endpoints 和 etcd.dialTimeout；网关配置读取 etcd.dial_timeout。

如果启动阶段必须拿到连接，可以用 MustGrpcClient；它失败会 panic，适合 main 函数初始化，不适合请求处理链路。

conn := app.MustGrpcClient("user-service")
client := pb.NewUserServiceClient(conn)

4. 网关启动

网关服务只需要连接 etcd 并启用 gateway。启动时会读取已有服务实例，之后继续 watch 服务上下线和路由变化。业务服务需要使用 EnableEtcdRegistry 注册并开启 reflection，网关才能自动发现方法。

package main

import (
    "log"

    "github.com/xs23933/core/v3"
    "github.com/xs23933/core/v3/gateway"
)

func main() {
    app := core.New(core.LoadConfigFile("config.yaml"))

    if err := app.EnableEtcdDiscovery(nil); err != nil {
        log.Fatal("启用 etcd 服务发现失败:", err)
    }

    _, err := gateway.NewEtcdGateway(app)
    if err != nil {
        panic(err)
    }

    app.Listen(":8080")
}

网关内置本地管理接口，仅允许 loopback 地址访问：

方法	路径	说明
GET	/admin/gateway/routes	路由列表
GET	/admin/gateway/routes/:id	路由详情
POST	/admin/gateway/routes	创建路由
PUT	/admin/gateway/routes/:id	更新或禁用路由
DELETE	/admin/gateway/routes/:id	删除路由

5. 自动注册路由规则

网关通过 gRPC reflection 读取服务方法，并按方法名前缀自动生成 HTTP 路由。

gRPC 方法名	HTTP 方法	HTTP 路径示例
PostLogin	POST	/v1/auth/user/login
GetProfile	GET	/v1/auth/user/profile
PutProfile	PUT	/v1/auth/user/profile
DeleteSession	DELETE	/v1/auth/user/session
GetUserById	GET	/v1/auth/user/:id
GetOrderByUserId	GET	/v1/order/order/:user/id

转换逻辑：

• proto package v1.auth 转为路径前缀 /v1/auth
• service v1.auth.UserService 转为 /user
• 方法前缀 Post/Get/Put/Delete 转为 HTTP method
• 方法名剩余部分按 CamelCase 拆成路径
• By 转为路径参数标记 :
• 缩写建议使用 Id 而不是 ID，避免被拆成 /i/d

例如：

syntax = "proto3";

package v1.auth;

service UserService {
  rpc PostLogin(LoginRequest) returns (LoginResponse);
  rpc GetUserById(GetUserRequest) returns (User);
}

自动生成：

POST /v1/auth/user/login      -> /v1.auth.UserService/PostLogin
GET  /v1/auth/user/:id        -> /v1.auth.UserService/GetUserById

当服务 reflection 中的方法减少，或 etcd 中的路由被删除/禁用时，网关会注销旧 HTTP 路由。

6. 手动配置网关路由

除了自动注册，也可以通过管理接口写入路由配置。

POST http://127.0.0.1:8080/admin/gateway/routes
Content-Type: application/json

{
  "method": "POST",
  "path": "/api/login",
  "service_name": "user-service",
  "grpc_method": "/v1.auth.UserService/PostLogin",
  "description": "manual login route"
}

禁用路由：

PUT http://127.0.0.1:8080/admin/gateway/routes/{route_id}
Content-Type: application/json

{
  "method": "POST",
  "path": "/api/login",
  "service_name": "user-service",
  "grpc_method": "/v1.auth.UserService/PostLogin",
  "enabled": false
}

7. HTTP 到 gRPC 的请求映射

网关会把 HTTP 路径参数、query 参数和 JSON body 合并为一个 JSON 对象，然后按 reflection 中的请求 message 反序列化。

GET /v1/auth/user/123?expand=true
Authorization: Bearer token
X-Request-Id: req-1

会转成类似：

{
  "id": "123",
  "expand": "true"
}

默认透传的 metadata：

• authorization
• x-request-id
• x-user-id
• Ctx.Vars() 中的本地变量 用于前置 middleware 处理后的后传参数 例如 jwt处理的: Ctx.Set("user_id", "123")

8. Demo 目录

仓库内置了几个最小 demo：

目录	说明	运行命令
example/restful	REST、模板、中间件、自动路由	go run ./example/restful
example/work	配置文件、数据库模型、分页查询	go run ./example/work
example/websocket	WebSocket echo 示例	go run ./example/websocket

REST demo 中同时展示了手写路由和自动路由：

app.GET("/", func(c core.Ctx) {
    c.SendString("what happend")
})

type handler struct {
    core.Handler
}

func (handler) GetHello(c core.Ctx) {
    c.SendString("ok")
}

func (handler) GetUser_id(c core.Ctx) {
    c.SendString("id is %s", c.Params("id"))
}

func init() {
    core.RegHandle(&handler{})
}

生成的自动路由：

GET /hello
GET /user/:id

高级功能

1. 数据库事务

func CreateUserWithProfile(db *core.DB, user User, profile Profile) error {
    return db.Transaction(func(tx *core.DB) error {
        if err := tx.Create(&user).Error; err != nil {
            return err
        }

        profile.UserID = user.ID
        if err := tx.Create(&profile).Error; err != nil {
            return err
        }

        return nil
    })
}

2. 连接多个数据库

database:
  default:
    type: mysql
    dsn: user:pass@tcp(localhost:3306)/main
  log:
    type: clickhouse
    dsn: tcp://localhost:9000?database=logs

// 使用默认数据库
db := core.Conn()

// 使用指定数据库
logDB := core.Conn("log")

3. 查询构建器

// 链式查询
var users []User
err := core.Conn().
    Select("id, username, email").
    Where("age > ?", 18).
    Where("status = ?", "active").
    Order("created_at DESC").
    Limit(10).
    Offset(0).
    Find(&users).Error

// 原生 SQL
var count int
core.Conn().Raw("SELECT COUNT(*) FROM users WHERE age > ?", 18).Scan(&count)

// 子查询
subQuery := core.Conn().Model(&Order{}).Select("user_id").Where("amount > ?", 1000)
core.Conn().Where("id IN (?)", subQuery).Find(&users)

4. 分页查询：FindPageBy 与 FindNextBy

FindPageBy 和 FindNextBy 都会读取 core.Map 中的分页和筛选参数，并可以接收一个已经拼好的 *core.DB 作为基础查询。

常用参数：

参数	说明
p	页码，默认 1
l	每页数量，默认 20
asc	升序字段，如 created_at
desc	降序字段，如 created_at
name	内置 name 模糊查询
field IN	IN 查询，如 status IN: []int{}
field >	比较查询，支持 > < >= <=
field*	包含匹配，等价于 %value%
^field	前缀匹配，等价于 value%
field$	后缀匹配，等价于 %value

两者区别：

• FindPageBy：返回 Page[T]，包含 total 总数；适合后台管理、需要显示总页数的列表。代价是会执行 count。
• FindNextBy：返回 NextPage[T]，包含 next/prev；通过查询 limit + 1 判断是否还有下一页，不统计总数。适合滚动加载、移动端列表、数据量较大的查询。

FindPageBy：带总数分页

type UsersViewDAO struct {
    db *core.DB
}

func (dao *UsersViewDAO) ListPage(ctx context.Context, whr *core.Map) (core.Page[user.UsersView], error) {
    if _, ok := (*whr)["asc"].(string); !ok {
        if _, ok := (*whr)["desc"].(string); !ok {
            (*whr)["desc"] = "created_at"
        }
    }

    tx := dao.db.WithContext(ctx).
        Model(&user.UsersView{}).
        Select("users_profiles.*, users.status").
        Joins("JOIN users ON users.id = users_profiles.user_id").
        Joins("JOIN users_identities ON users_profiles.user_id = users_identities.user_id")

    res := make([]user.UsersView, 0)
    return core.FindPageBy(whr, &res, tx)
}

返回结构：

{
  "p": 1,
  "l": 20,
  "total": 128,
  "data": []
}

FindNextBy：后推分页

FindNextBy 会多查一条数据判断 next。如果 ret.Next == true，通常需要把多查出来的最后一条裁掉再返回。

func (dao *UsersViewDAO) ListNext(ctx context.Context, whr *core.Map) (core.NextPage[user.UsersView], error) {
    if _, ok := (*whr)["asc"].(string); !ok {
        if _, ok := (*whr)["desc"].(string); !ok {
            (*whr)["desc"] = "created_at"
        }
    }

    tx := dao.db.WithContext(ctx).
        Model(&user.UsersView{}).
        Select("users_profiles.*, users.status").
        Joins("JOIN users ON users.id = users_profiles.user_id").
        Joins("JOIN users_identities ON users_profiles.user_id = users_identities.user_id")

    res := make([]user.UsersView, 0)
    ret, err := core.FindNextBy(whr, &res, tx)
    if ret.Next {
        ret.Data = res[:len(res)-1]
    }
    return ret, err
}

返回结构：

{
  "p": 1,
  "l": 20,
  "next": true,
  "prev": false,
  "data": []
}

同一个 DAO 根据参数切换分页模式

func (dao *UsersViewDAO) List(ctx context.Context, whr *core.Map, page bool) (any, error) {
    _, asc := (*whr)["asc"].(string)
    _, desc := (*whr)["desc"].(string)
    if !asc && !desc {
        (*whr)["desc"] = "created_at"
    }
    if tp := whr.GetString("type"); tp != "" {
        (*whr)["type"] = constants.ParseLoginType(tp)
    }

    tx := dao.db.WithContext(ctx).
        Model(&user.UsersView{}).
        Select("users_profiles.*, users.status").
        Joins("JOIN users ON users.id = users_profiles.user_id").
        Joins("JOIN users_identities ON users_profiles.user_id = users_identities.user_id")

    res := make([]user.UsersView, 0)

    if page {
        return core.FindPageBy(whr, &res, tx)
    }

    ret, err := core.FindNextBy(whr, &res, tx)
    if ret.Next {
        ret.Data = res[:len(res)-1]
    }
    return ret, err
}

5. 事件钩子

type User struct {
    core.Model
    Username string
    Password string
}

// 保存前钩子 具体可参照 gorm官方文档
func (u *User) BeforeSave(tx *core.DB) error {
    if u.Password != "" {
        hashed, err := bcrypt.GenerateFromPassword([]byte(u.Password), bcrypt.DefaultCost)
        if err != nil {
            return err
        }
        u.Password = string(hashed)
    }
    return nil
}

// 查询后钩子
func (u *User) AfterFind(tx *core.DB) error {
    u.Password = "" // 隐藏密码字段
    return nil
}

Redis Cache 通用包装器

cache 是独立子包，用于封装“先读缓存，未命中再查 DB，并自动回填缓存”的常见模式。

导入路径：

import "github.com/xs23933/core/v3/cache"

推荐为每类数据创建可复用 cache 实例，把 Redis 连接、前缀、TTL 和空值缓存策略集中配置一次。

type UserVO struct {
    ID   string `json:"id"`
    Name string `json:"name"`
}

var userCache = cache.New(
    core.RConn("cache"),
    cache.Prefix("user:"),
    cache.TTL(10*time.Minute),
    cache.EmptyTTL(time.Minute),
    cache.Jitter(30*time.Second),
    cache.CacheNil(true),
)

func GetUser(ctx context.Context, id string) (UserVO, error) {
    var user UserVO
    err := userCache.Take(ctx, id, &user, func(ctx context.Context) (any, error) {
        return dao.GetUserByID(ctx, id)
    })
    return user, err
}

同一个 cache 实例可以缓存不同类型，类型由 out 指针决定。

var order OrderVO
err := userCache.Take(ctx, "order:"+orderID, &order, func(ctx context.Context) (any, error) {
    return dao.GetOrderByID(ctx, orderID)
})

想保留返回值风格时，用包级泛型 helper。它不要求 New 绑定类型。

user, err := cache.Load[UserVO](userCache, ctx, "user:"+id, func(ctx context.Context) (UserVO, error) {
    return dao.GetUserByID(ctx, id)
})

user, err = cache.Get(ctx, "user:"+id, func(ctx context.Context) (UserVO, error) {
    return dao.GetUserByID(ctx, id)
})

空值缓存用于防止不存在的数据持续打到 DB。默认识别 cache.ErrNotFound，也可以接入项目自己的 not found 错误。

var userCache = cache.New(
    core.RConn("cache"),
    cache.Prefix("user:"),
    cache.CacheNil(true),
    cache.NotFound(func(err error) bool {
        return errors.Is(err, gorm.ErrRecordNotFound)
    }),
)

更新或删除数据后删除缓存：

if err := userCache.Delete(ctx, id); err != nil {
    return err
}

规则：

• Take / Load 内部使用 singleflight 合并同进程并发 miss，避免缓存击穿。
• Redis 读失败会降级执行 loader；写缓存失败不会影响返回结果。
• TTL 可用 Jitter 增加随机抖动，避免大量 key 同时过期。
• 不要在每次请求中重复 cache.New；应创建可复用实例。

Fetch API 客户端

fetch 是独立子包，用于调用外部 HTTP API。设计接近前端 JavaScript fetch 的使用习惯，但保留 Go 的显式错误处理和结构体 decode。

导入路径：

import "github.com/xs23933/core/v3/fetch"

1. 最简调用

包级快捷方法使用 fetch.Default，适合一次性调用或简单脚本。

type UserVO struct {
    ID   string `json:"id"`
    Name string `json:"name"`
}

var user UserVO
res, err := fetch.Get("https://api.example.com/users/1", &user)
if err != nil {
    return err
}

token := res.Header.Get("X-Token")
_ = token

POST / PUT 带参数时，params 会按类型自动处理：

参数类型	处理方式
nil	不发送 body
[]byte	原始 body
string	字符串 body
其它类型	JSON body，并设置 Content-Type: application/json; charset=utf-8

var out UserVO

_, err := fetch.Post(
    "https://api.example.com/users",
    map[string]any{"name": "tom"},
    &out,
)

_, err = fetch.Put(
    "https://api.example.com/users/1",
    map[string]any{"name": "jerry"},
    &out,
)

_, err = fetch.Delete("https://api.example.com/users/1", nil)

2. 可复用 Client

业务服务中推荐创建可复用 client，统一配置 baseURL、公共 Header、Cookie 和 Hook。

var api = fetch.New("https://api.example.com").
    Header("X-App", "core-service").
    Header("Accept", "application/json").
    UseCookie(true)

func GetUser(ctx context.Context, id string) (UserVO, error) {
    var user UserVO

    res, err := api.DoGet(ctx, "/users/"+id, &user)
    if err != nil {
        return user, err
    }

    refreshedToken := res.Header.Get("X-Token")
    _ = refreshedToken

    return user, nil
}

公共 Header 和单次 Header 分开：

api := fetch.New("https://api.example.com").
    Header("X-App", "core-service") // 每次请求都有

var out UserVO
res, err := api.Post("/users").
    Header("X-Request-ID", "req-123"). // 只对本次请求生效
    JSON(map[string]any{"name": "tom"}).
    Result(context.Background(), &out)

3. 请求前 Hook：签名、鉴权、时间戳

Before 在请求发出前执行，可以读取最终 body 并修改 *http.Request。常用于 hash 签名、认证 Header、请求追踪。

api := fetch.New("https://api.example.com").
    Before(func(ctx context.Context, req *http.Request, body []byte) error {
        sign := core.SHA256HashBytes(body)
        req.Header.Set("X-Sign", sign)
        req.Header.Set("X-Timestamp", strconv.FormatInt(time.Now().Unix(), 10))
        return nil
    })

var out UserVO
_, err := api.DoPost(context.Background(), "/users", map[string]any{"name": "tom"}, &out)

4. 响应后 Hook：解包、解密、统一 decode

After 在响应 body 读取完成后执行，返回值会作为最终 body 继续 decode。适合统一响应格式解包。

type Envelope struct {
    Code int             `json:"code"`
    Msg  string          `json:"msg"`
    Data json.RawMessage `json:"data"`
}

api := fetch.New("https://api.example.com").
    After(func(ctx context.Context, resp *http.Response, body []byte) ([]byte, error) {
        var env Envelope
        if err := json.Unmarshal(body, &env); err != nil {
            return nil, err
        }
        if env.Code != 0 {
            return nil, fmt.Errorf("api error %d: %s", env.Code, env.Msg)
        }
        return env.Data, nil
    })

var user UserVO
_, err := api.DoGet(context.Background(), "/users/1", &user)

5. 获取响应 Header、Status、Body

使用 Result 或 DoGet/DoPost/DoPut/DoDelete 会返回 *fetch.FetchResult。

res, err := api.Get("/session").Result(context.Background(), &out)
if err != nil {
    if ferr, ok := err.(*fetch.FetchError); ok {
        retryToken := ferr.Header.Get("X-Token")
        body := string(ferr.Body)
        _ = retryToken
        _ = body
    }
    return err
}

token := res.Header.Get("X-Token")
status := res.StatusCode
body := res.Body

6. Cookie 开关

默认不保存 Cookie，避免隐式状态。需要模拟浏览器会话时显式启用：

api := fetch.New("https://api.example.com").UseCookie(true)

// 禁用并清空 cookie jar
api.UseCookie(false)

错误处理

自定义错误处理

// 全局错误处理
app.ErrorHandler = func(c core.Ctx, err error) {
    if e, ok := err.(*core.HTTPError); ok {
        c.SendStatus(e.Code, e.Message)
        return
    }

    // 记录错误日志
    core.Erro("请求处理失败: %v", err)

    // 生产环境隐藏详细错误
    if app.Debug {
        c.SendStatus(500, err.Error())
    } else {
        c.SendStatus(500, "Internal Server Error")
    }
}

// 业务错误
func (Handler) GetUser(c core.Ctx) {
    user, err := models.GetUserByID(id)
    if err != nil {
        if errors.Is(err, gorm.ErrRecordNotFound) {
            c.SendStatus(404, "用户不存在")
            return
        }
        c.SendStatus(500, "服务器错误")
        return
    }
    c.ToJSON(user)
}

性能优化

1. 连接池配置

database:
  type: mysql
  dsn: user:pass@tcp(localhost:3306)/dbname
  pool:
    max_idle: 10 # 最大空闲连接数
    max_open: 100 # 最大打开连接数
    max_lifetime: 1h # 连接最大生命周期

2. 启用 Prefork 模式

prefork: true # 启用多进程模式，充分利用多核CPU

测试

单元测试

package handler_test

import (
    "testing"
    "github.com/xs23933/core/v3"
)

func TestUserHandler(t *testing.T) {
    app := core.New()

    // 模拟请求
    req := core.TestRequest{
        Method: "GET",
        Path:   "/users/1",
    }

    resp := app.Test(req)

    if resp.StatusCode != 200 {
        t.Errorf("期望状态码 200，得到 %d", resp.StatusCode)
    }
}

集成测试

@baseURL = http://localhost:8080
@contentType = application/json

### 创建用户
POST {{baseURL}}/users
Content-Type: {{contentType}}

{
    "username": "testuser",
    "email": "test@example.com",
    "password": "password123"
}

### 获取用户
GET {{baseURL}}/users/1

### 获取用户列表
GET {{baseURL}}/users?page=1&size=10

部署

1. 编译

go build -o app main.go

2. 使用 Systemd

# /etc/systemd/system/myapp.service
[Unit]
Description=My Core Application
After=network.target

[Service]
Type=simple
User=appuser
WorkingDirectory=/opt/myapp
ExecStart=/opt/myapp/app
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

3. 使用 Docker

FROM golang:1.24-alpine AS builder

WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN go build -o app main.go

FROM alpine:latest
RUN apk --no-cache add ca-certificates
WORKDIR /root/
COPY --from=builder /app/app .
COPY --from=builder /app/config.yaml .
EXPOSE 8080
CMD ["./app"]

常见问题

1. 路由不生效

问题: 处理器方法已定义，但路由不生效。

解决方案:

• 确保处理器嵌入了 core.Handler
• 确保在 init() 函数中调用 core.RegHandle()
• 检查方法名是否符合路由规则
• 查看日志确认路由注册情况

2. 数据库连接失败

问题: 数据库连接失败，返回错误。

解决方案:

• 检查 config.yaml 中的数据库配置
• 确认数据库服务是否运行
• 检查连接字符串格式是否正确
• 查看数据库日志获取详细错误信息

3. 跨域问题

问题: 前端请求被浏览器阻止，提示跨域错误。

解决方案:

• 启用 CORS 中间件
• 配置正确的 CORS 选项

import "github.com/xs23933/core/v3/middleware/cors"

app.Use(cors.New(app, cors.Config{
    AllowOrigins:     "http://localhost:3000",
    AllowMethods:     "GET,POST,PUT,DELETE,OPTIONS",
    AllowHeaders:     "Content-Type,Authorization",
    AllowCredentials: true,
}))

4. 文件上传大小限制

问题: 上传大文件时失败。

解决方案:

• 调整最大文件大小限制

app := core.New(core.Options{
    "max_body_size": "10MB", // 10MB 限制
})

API 参考

核心方法

Ctx 接口主要方法

方法	说明	示例
Params(key)	获取路径参数	c.Params("id")
Query(key)	获取查询参数	c.Query("name")
FormValue(key)	获取表单值	c.FormValue("email")
ReadBody(out)	读取请求体	c.ReadBody(&user)
Validate(out)	验证结构体	c.Validate(&form)
ToJSON(data, err)	返回 JSON 响应	c.ToJSON(user, nil)
JSON(data)	返回 JSON 响应	c.JSON(user)
Type(ty)	设置响应类型	c.Type("json")
Send(msg)	发送[]byte	c.Send([]byte( "Not Found"))
SendString(msg)	发送状String	c.SendString("Not Found")
SendStatus(code, msg)	发送状态码	c.SendStatus(404, "Not Found")
SetHeader(key, value)	设置响应头	c.SetHeader("Content-Type", "application/json")
GetHeader(key)	获取请求头	c.GetHeader("Authorization")
FormFile(key)	获取上传文件	c.FormFile("file")
SaveFile(key, dst)	保存上传文件	c.SaveFile("file", "./uploads")

数据库操作

方法	说明	示例
core.DB	gorm.DB别名	db *core.DB
core.Conn(name)	获取指定数据库连接	core.Conn("log")
core.Transaction(fn)	执行事务	core.Transaction(func(tx) { ... })
core.Find(out)	查询数据	core.Find(&users)
core.First(out, where)	查询单条数据	core.First(&user, "id = ?", id)

配置选项

选项	类型	默认值	说明
debug	bool	false	调试模式
listen	string	":8080"	监听地址
network	string	"tcp4"	网络协议
prefork	bool	false	是否启用 prefork
max_body_size	string	"1MB"	最大请求体大小
read_timeout	string	"5s"	读取超时
write_timeout	string	"10s"	写入超时

最佳实践

1. 项目组织

project/
├── cmd/
│   └── server/
│       └── main.go          # 应用入口
├── internal/
│   ├── handler/             # 处理器
│   │   ├── user.go
│   │   └── auth.go
│   ├── model/               # 数据模型
│   │   ├── user.go
│   │   └── order.go
│   ├── service/             # 业务逻辑
│   │   ├── user_service.go
│   │   └── auth_service.go
│   └── middleware/          # 中间件
│       ├── auth.go
│       └── logger.go
├── pkg/
│   └── utils/               # 工具函数
├── configs/
│   └── config.yaml          # 配置文件
├── migrations/              # 数据库迁移
├── scripts/                 # 部署脚本
├── tests/                   # 测试文件
├── go.mod
└── go.sum

2. 错误处理

// 定义业务错误
var (
    ErrUserNotFound = errors.New("用户不存在")
    ErrInvalidToken = errors.New("无效的令牌")
)

// 统一错误响应
func ErrorResponse(c core.Ctx, err error) {
    switch err {
    case ErrUserNotFound:
        c.SendStatus(404, err.Error())
    case ErrInvalidToken:
        c.SendStatus(401, err.Error())
    case gorm.ErrRecordNotFound:
        c.SendStatus(404, "记录不存在")
    default:
        core.Erro("未处理的错误: %v", err)
        c.SendStatus(500, "服务器内部错误")
    }
}

// 使用示例
func (Handler) GetUser(c core.Ctx) {
    user, err := services.GetUserByID(id)
    if err != nil {
        ErrorResponse(c, err)
        return
    }
    c.ToJSON(user)
}

3. 日志记录

// 配置日志
import "github.com/xs23933/core/v3/middleware/logger"

app.Use(logger.New(logger.Options{
    Format: "${time} ${status} ${method} ${path} ${latency}\n",
    Output: os.Stdout,
}))

// 自定义日志级别
core.Info("用户登录成功: %s", username)
core.Warn("API 调用频繁: %s", ip)
core.Erro("数据库连接失败: %v", err)
core.D("请求参数: %v", params)

日志轮转

框架内置日志文件轮转，配置文件方式：

log: /var/log/myapp/app.log
log_rotate:
  - size: 300M
  - daily
  - rotate: 30
  - compress
  - delaycompress: 24h
  - missingok
  - notifempty
  - copytruncate

只要配置了 log 且 log_rotate 未配置、为 null、空字符串或空数组，框架会自动套用上面的默认轮转配置。

参数说明：

参数	含义
size: 300M	日志文件达到指定大小后切割，支持 K/KB/M/MB/G/GB，也支持纯数字字节数
daily	按天切割，跨日期后第一次写入会创建新的日志文件
rotate: 30	保留最近 30 天的切割日志，超过期限自动删除
compress	切割后的日志文件压缩为 .gz
delaycompress	延迟压缩切割日志，默认延迟 24h，需配合 compress
delaycompress: 2h	指定延迟压缩时长，支持 Go duration 格式，如 30m、2h、24h
missingok	日志文件不存在时继续运行并重新创建，不返回错误
notifempty	当前日志文件为空时不切割、不压缩、不生成空的轮转文件
copytruncate	切割时复制当前日志再截断原文件，适合不希望替换文件句柄的部署方式

代码方式：

w, err := core.NewRotatingLogWriter(
    "/var/log/myapp/app.log",
    "size: 300M",
    "daily",
    "rotate: 30",
    "compress",
    "delaycompress: 24h",
    "missingok",
    "notifempty",
    "copytruncate",
)
if err != nil {
    panic(err)
}
defer w.Close()

app.Use(core.Logger(core.LoggerConfig{
    App:    app,
    Debug:  app.Debug,
    Output: w,
}))

4. 性能监控

import (
    "time"

    "github.com/xs23933/core/v3/middleware/metrics"
    "github.com/xs23933/core/v3/middleware/ratelimit"
)

// 启用指标收集
m, mw := metrics.New()
app.Use(mw)
metrics.Mount(app, "/metrics", m)

// 启用限流（默认内存）
app.Use(ratelimit.New(ratelimit.Config{
    Max:    300,
    Window: time.Minute,
}))

// 更平滑的用户级限流
app.Use(ratelimit.New(ratelimit.Config{
    Max:       120,
    Window:    time.Minute,
    Algorithm: ratelimit.SlidingWindow,
    KeyFunc: func(c core.Ctx) string {
        return c.GetString("user_id", c.RemoteIP().String())
    },
}))

扩展开发

1. 开发自定义中间件

package middleware

import (
    "time"

    "github.com/xs23933/core/v3"
)

func AccessLog() core.HandlerFunc {
    return func(c core.Ctx) error {
        start := time.Now()
        err := c.Next()
        core.Info("%s %s status=%d cost=%s",
            c.Method(), c.Path(), c.GetStatus(), time.Since(start))
        return err
    }
}

2. 开发插件

package plugin

import "github.com/xs23933/core/v3"

type Plugin struct {
    core.Handler
    config map[string]any
}

func New(config map[string]any) *Plugin {
    return &Plugin{
        config: config,
    }
}

func (p *Plugin) Install(app *core.Core) {
    // 注册路由
    app.Get("/plugin/status", p.Status)

    // 注册中间件
    app.Use(p.Middleware)

    // 初始化资源
    p.Init()
}

func (p *Plugin) Status(c core.Ctx) {
    c.ToJSON(map[string]any{
        "name":    p.config["name"],
        "version": p.config["version"],
        "status":  "running",
    })
}

func (p *Plugin) Middleware(c core.Ctx) error {
    // 插件中间件逻辑
    c.Set("plugin_data", p.config)
    return c.Next()
}

func (p *Plugin) Init() {
    // 初始化逻辑
    core.Info("插件 %s 已初始化", p.config["name"])
}

Core/V3 框架路由自动注册规范

本文档描述 github.com/xs23933/core/v3 框架的路由自动注册机制。

---

一、命名约定

1.1 Handler 结构体

type UserHandler struct {
    core.Handler  // 必须嵌入 core.Handler
    // ... 依赖字段
}

• Handler 结构体名以 Handler 结尾
• 框架自动注册时会去掉 Handler 后缀作为路由组名
• 例：UserHandler → 路由组前缀为 /user（可通过 Init() 覆盖）

1.2 方法命名规则

HTTP 方法前缀 + 路径片段（驼峰命名）：

方法名前缀	HTTP 方法
Get	GET
Post	POST
Put	PUT
Delete	DELETE
Patch	PATCH
All	ALL

---

二、路径转换规则（核心）

2.1 基本规则

字符特征	转换结果	示例
大写字母开头	路径片段 /xxx	Profile → /profile
下划线 + 小写字母	路径参数 :xxx	_id → :id
Param（固定关键字）	路径参数 :param	Param → :param
Params（固定关键字）	可选参数 :param?	Params → :param?

2.2 大写字母 = 路径分隔

每个大写字母开头的片段都会生成一个新的路径层级：

// 方法名 → 路由
func (h *Handler) GetProfile(c core.Ctx) error {}
// GET /profile

func (h *Handler) GetCurrentUser(c core.Ctx) error {}
// GET /current/user

func (h *Handler) GetId(c core.Ctx) error {}
// GET /id  （Id 是路径片段，不是参数！）

2.3 下划线 = 自定义路径参数

下划线开头 + 小写字母 = 自定义路径参数名：

// 方法名 → 路由
func (h *Handler) GetByID(c core.Ctx) error {}
// GET /:id

func (h *Handler) GetByUserid(c core.Ctx) error {}
// GET /:userid

func (h *Handler) GetByIDProfile(c core.Ctx) error {}
// GET /:id/profile

2.4 固定关键字 Param / Params

Param 和 Params 是框架固定关键字：

// 方法名 → 路由
func (h *Handler) GetParam(c core.Ctx) error {}
// GET /:param  （必选参数）

func (h *Handler) GetParams(c core.Ctx) error {}
// GET /:param?  （可选参数）

func (h *Handler) GetParam_Callback(c core.Ctx) error {}
// GET /:param/callback

func (h *Handler) GetParams_Detail(c core.Ctx) error {}
// GET /:param?/detail

⚠️ 关键区别：

• Param → :param（必选）
• Params → :param?（可选）
• 参数名固定为 param，通过 c.Params("param") 获取

---

三、参数获取

3.1 固定关键字参数

// 路由: GET /:param
func (h *Handler) GetParam(c core.Ctx) error {
    val := c.Params("param")  // 参数名固定为 "param"
    // ...
}

// 路由: GET /:param/callback
func (h *Handler) GetParam_Callback(c core.Ctx) error {
    provider := c.Params("param")  // 同样是 "param"
    // ...
}

3.2 自定义参数名

// 路由: GET /:id
func (h *Handler) GetByID(c core.Ctx) error {
    id := c.Params("id")  // 参数名为 "id"
    // ...
}

// 路由: GET /:userid/profile
func (h *Handler) GetByUseridProfile(c core.Ctx) error {
    userId := c.Params("userId")  // 参数名为 "userId"
    // ...
}

---

四、路由前缀设置

4.1 默认前缀

框架根据 Handler 名称自动推断前缀：

type UserHandler struct { core.Handler }
// 默认前缀: /user

type OAuthHandler struct { core.Handler }
// 默认前缀: /oauth

4.2 自定义前缀

在 Init() 方法中使用 Prefix() 设置：

func (h *OAuthHandler) Init() {
    h.Prefix("/api/v1/oauth")
}

---

五、完整示例

5.1 OAuth Handler 示例

type OAuthHandler struct {
    core.Handler
    oauthService *OAuthService
}

func (h *OAuthHandler) Init() {
    h.Prefix("/api/v1/oauth")
}

// GET /api/v1/oauth/:param
func (h *OAuthHandler) GetParam(c core.Ctx) error {
    provider := c.Params("param") // google, facebook, twitter, github
    // ...
}

// GET /api/v1/oauth/:param/callback
func (h *OAuthHandler) GetParam_Callback(c core.Ctx) error {
    provider := c.Params("param")
    // ...
}

生成的路由：

GET /api/v1/oauth/:param           → OAuthHandler.GetParam
GET /api/v1/oauth/:param/callback  → OAuthHandler.GetParam_Callback

访问示例：

URL	匹配路由	param 值
GET /api/v1/oauth/google	GetParam	"google"
GET /api/v1/oauth/facebook/callback	GetParam_Callback	"facebook"
GET /api/v1/oauth	404	必选参数缺失

5.2 User Handler 示例

type UserHandler struct {
    core.Handler
}

func (h *UserHandler) Init() {
    h.Prefix("/api/v1/users")
}

// GET /api/v1/users
func (h *UserHandler) Get(c core.Ctx) error {}

// GET /api/v1/users/:id
func (h *UserHandler) GetByID(c core.Ctx) error {
    id := c.Params("id")
}

// GET /api/v1/users/:id/profile
func (h *UserHandler) GetByID_Profile(c core.Ctx) error {
    id := c.Params("id")
}

// GET /api/v1/users/current
func (h *UserHandler) GetCurrent(c core.Ctx) error {}

// POST /api/v1/users
func (h *UserHandler) Post(c core.Ctx) error {}

// PUT /api/v1/users/:id
func (h *UserHandler) Put_id(c core.Ctx) error {}

// DELETE /api/v1/users/:id
func (h *UserHandler) Delete_id(c core.Ctx) error {}

---

六、命名转换规则（ToNamer）

框架内部使用 ToNamer 函数进行命名转换：

转换逻辑：

1. 提取 HTTP 方法前缀（Get/Post/Put/Delete/Patch）
2. 遍历剩余字符：
   • 大写字母 → 新路径片段（转小写）
   • _ + 小写字母 → 自定义路径参数
   • Param（关键字）→ :param
   • Params（关键字）→ :param?

转换示例：

方法名	解析过程	最终路由
GetProfile	Profile → /profile	GET /profile
GetCurrentUser	Current + User → /current/user	GET /current/user
GetByID	ByID → /:id	GET /:id
Get_userId	_userId → /:userId	GET /:userId
GetByID_Profile	_id + Profile → /:id/profile	GET /:id/profile
GetParam	Param → /:param	GET /:param
GetParam_Callback	Param + Callback → /:param/callback	GET /:param/callback
GetParams	Params → /:param?	GET /:param?
GetParams_Detail	Params + Detail → /:param?/detail	GET /:param?/detail
GetId	Id → /id	GET /id（不是参数！）
PostLogin	Login → /login	POST /login

---

七、常见错误

7.1 混淆大写和下划线

// ❌ 错误：期望 /:id，实际得到 /id
func (h *Handler) GetId(c core.Ctx) error {}
// GET /id  （Id 是路径片段，不是参数）

// ✅ 正确：使用下划线定义参数
func (h *Handler) GetByID(c core.Ctx) error {}
// GET /:id

7.2 混淆 Param 和 Params

// ❌ 错误：期望可选参数，实际是必选
func (h *Handler) GetParam(c core.Ctx) error {}
// GET /:param  （必选）

// ✅ 正确：使用 Params 表示可选
func (h *Handler) GetParams(c core.Ctx) error {}
// GET /:param?  （可选）

7.3 Param 与自定义参数混用

// ⚠️ 注意：Param 固定参数名为 "param"
func (h *Handler) GetParam(c core.Ctx) error {}
// GET /:param，用 c.Params("param") 获取

// 自定义参数名用下划线
func (h *Handler) GetByID(c core.Ctx) error {}
// GET /:id，用 c.Params("id") 获取

---

八、调试技巧

8.1 查看注册的路由

框架启动时会打印所有注册的路由：

[DBUG] AutoRoute handler.UserHandler
[DBUG] route: GET /profile > handler.UserHandler.GetProfile
[DBUG] route: POST /login > handler.AuthHandler.PostLogin
[DBUG] route: GET /api/v1/oauth/:param > handler.OAuthHandler.GetParam

8.2 常见问题排查

问题	原因	解决方案
404 路由不匹配	参数必选但未提供	使用 Params 改为可选，或确保 URL 包含参数
参数值为空	使用 Params 但未传参	检查是否应该用 Param 改为必选
路由不是参数	用了大写开头（如 Id）	改用下划线开头（如 _id）
路由冲突	多个方法映射到同一路径	检查方法命名是否重复

---

九、快速参考卡

┌─────────────────────────────────────────────────────────────┐
│  命名规则                                                    │
├─────────────────────────────────────────────────────────────┤
│  大写字母开头    → 路径片段 /xxx                              │
│  _xxx（下划线）  → 自定义路径参数 :xxx                        │
│  Param（关键字） → 路径参数 :param（必选）                    │
│  Params（关键字）→ 路径参数 :param?（可选）                   │
├─────────────────────────────────────────────────────────────┤
│  方法名               →  路由                               │
├─────────────────────────────────────────────────────────────┤
│  Get                  →  GET /                              │
│  GetProfile           →  GET /profile                       │
│  GetCurrent           →  GET /current                       │
│  GetCurrentProfile    →  GET /current/profile               │
│  GetByID              →  GET /:id       (自定义参数)          │
│  GetUserid            →  GET /:userid   (自定义参数)         │
│  GetByID_Profile      →  GET /:id/profile                   │
│  GetParam             →  GET /:param     (必选关键字)        │
│  GetParam_Callback    →  GET /:param/callback               │
│  GetParams            →  GET /:param?    (可选关键字)        │
│  GetParams_Detail     →  GET /:param?/detail                │
│  GetId                →  GET /id       (不是参数！)          │
│  Post                 →  POST /                             │
│  PostLogin            →  POST /login                        │
│  PutID                →  PUT /:id                           │
│  DeleteID             →  DELETE /:id                        │
└─────────────────────────────────────────────────────────────┘

参数获取:
  - 关键字参数: c.Params("param")
  - 自定义参数: c.Params("id"), c.Params("userId") 等

版本历史

v3.1.0 (当前版本)

• 支持 Go 1.24
• 性能优化，提升 30% 吞吐量
• 新增 WebSocket 支持
• 改进中间件系统
• 增强数据库支持

v2.0

• 引入自动路由注册
• 支持多数据库连接
• 改进错误处理机制
• 新增文件上传功能

v1.0

• 初始版本发布
• 基础路由功能
• 数据库集成
• 中间件支持

社区支持

• GitHub: https://github.com/xs23933/core
• 问题反馈: https://github.com/xs23933/core/issues

贡献指南

欢迎贡献代码！请遵循以下步骤：

1. Fork 项目仓库
2. 创建功能分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add some amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 创建 Pull Request

许可证

本项目采用 MIT 许可证。详见 LICENSE 文件。

---

文档最后更新: 2026-03-31 Core Framework v3.0.0