db233-go

module
v1.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 22, 2026 License: Apache-2.0

README

db233-go

Go 语言 ORM / 数据库库(github.com/neko233-com/db233-go)— 面向 有状态游戏逻辑服 与 MySQL 高 QPS:Session 一级缓存(在线读零查库)、批量 UPSERT、WAL 写不丢、连接池与冷启动预热。可作为 GORM / sqlx 的性能向替代方案。

版本 v1.1.0 · Go 1.25.12+
数据库 MySQL(主),PostgreSQL(连接层)
典型场景 MMORPG 逻辑服、单库单写、登录多表加载、entitysave 批量存档
文档 docs/README.md · FAQ · 对比 GORM · 是什么
go get github.com/neko233-com/db233-go@v1.1.0

发版压测:./scripts/run-benchmark.ps1(BENCHMARK.md)
推送前:./scripts/check-secrets.ps1(凭据仅 config.local.json / *.local.yaml)

框架性能对标(本地 MySQL)

复现:cd benchmarks && go test -run TestFrameworkCompare_Report -timeout 3m -v

图例(按列对比):🟩 最优 · 🟨 中等 · 🟥 最差 · ⬜ 不适用 — 延迟/倍率越小越绿

框架 单次 PK 读 登录 3 表 批量 UPSERT×50 Session 读×1000 相对 raw SQL 读
db233-go ~10.8 ~12.6 ~13.0 <0.001 ms ~0.5×
database/sql ~21.5 ~67.3 ~581 — 1.0×
sqlx ~18.9 ~58.1 ~974 — ~0.88×
GORM ~23.3 ~74.0 ~54.6 ~21s ~1.08×
能力 db233-go GORM sqlx database/sql
实体 CRUD / UPSERT ✅ ✅ 部分 ❌
批量 UPSERT 单 SQL ✅ 部分 ❌ ❌
Session 一级缓存(在线零查库) ✅ ❌ ❌ ❌
FindByIdConcurrent 登录 ✅ ❌ ❌ ❌
WAL 写不丢 ✅ ❌ ❌ ❌
*sql.Stmt 预编译池 ✅ 内部 ✅ 手动
内部对象池(字段 map / 批量 scratch) ✅ 部分 ❌ ❌
ORM 直扫字段(无 map 中转) ✅ ✅ ✅ 手动
冷启动预热(池+元数据+Stmt) ✅ 部分 ❌ ❌

游戏服读路径:登录 OpenSession 后 session.Get 走 L1,不经过 ORM/DB。
内存/GC:默认 enableAllocPool + enableFastOrmScan;见下文「相对 GORM 内存压力」。

相对 GORM 内存 / GC 压力(设计对比)
维度 db233-go GORM
单次读中间对象 直扫字段,无 map[string]any Schema + 反射 + 可能 clause 构建
批量写 200 行 1 个 field map scratch + 复用 []any 行缓冲 每行 Statement/反射链 + 可能 N 次 Exec
IN 查询 500 ID ?,?,? 字符串缓存(immutable) 每次拼接
在线读(Session) L1 指针复用,零 DB 对象分配 每次 First 新建 struct + 查库
返回给业务的对象 每行 1 个 entity(与 GORM 相同) 每行 1 个 struct
不可池化(安全边界) 返回的 entity / QueryNamed 的 map 仍独立分配 同

不能池化的(会破坏安全/语义):返回给调用方的 entity、*[]map 查询结果、WAL 持久化 JSON 副本、跨 goroutine 共享的可变 map。


文档与 FAQ

文档 说明
docs/README.md 文档中心(场景导航)
docs/OVERVIEW.md 是什么、适合谁、30 秒上手
docs/COMPARE-ORM.md db233 vs GORM vs sqlx 选型
docs/FAQ.md 常见问题
docs/BENCHMARK.md 压测标准与一键脚本
config-game-server-stateful.md 有状态游戏服配置
config-web-server.md Web/API 服配置

支持 命名参数查询 {paramName} 与批量命名更新。

📋 目录


命名参数查询

命名参数查询 - 更清晰的 SQL
旧写法(位置参数)
// 繁琐且容易出错
sql := "SELECT * FROM users WHERE age > ? AND status = ?"
rows := db.Query(sql, 18, "active")
新写法(命名参数)✨ 推荐
// 清晰易读易维护
sql := "SELECT * FROM users WHERE age > {minAge} AND status={status}"
rows := db.QueryNamed(sql, map[string]any{
    "minAge": 18,
    "status": "active",
})
命名参数批量更新 - 简化批量操作
// 批量更新 - 推荐使用
sql := "UPDATE users SET name={name}, age={age} WHERE id={id}"
updates := []map[string]any{
    {"id": 1, "name": "Alice", "age": 25},
    {"id": 2, "name": "Bob", "age": 30},
    {"id": 3, "name": "Charlie", "age": 35},
}
affected := db.ExecuteUpdateMultiRowsNamed(sql, updates)
// affected = 3
便利查询方法
// 直接返回标量值,无需类型断言
count := db.QueryNamedToInt64("SELECT COUNT(*) FROM users WHERE id > {minId}", 
    map[string]any{"minId": 100})

name := db.QueryNamedToString("SELECT name FROM users WHERE id={userId}", 
    map[string]any{"userId": 1})

ids := db.QueryNamedToInt64Slice("SELECT id FROM users WHERE status={status}", 
    map[string]any{"status": "active"})
严格 Entity 查询与事务 Repository

正确性关键读取应显式使用 StrictCrudRepository。它采用 all-or-error 语义:Query、Scan、字段转换、结果遍历或 Rows 关闭任一失败时都返回非 nil error,不会把空集或部分结果伪装为成功;成功加载的 Entity 会调用一次 DeserializeAfterLoadDb()。

ctx := context.Background()
repo := db233.NewStrictCrudRepository(db)

user, err := repo.FindByIdContext(ctx, userID, &User{})
if err != nil {
    return err // 数据库或映射失败
}
if user == nil {
    return ErrUserNotFound // 查询成功,但没有记录
}

需要跨删除、分块 UPSERT 和严格回读保持原子性时,先手工开启事务,再从 manager 获取绑定当前 *sql.Tx 的窄 Repository:

tm := db233.NewTransactionManager(db)
if err := tm.BeginContext(ctx); err != nil {
    return err
}
defer func() {
    if tm.IsActive() {
        _ = tm.Rollback()
    }
}()

txRepo, err := tm.CrudRepository()
if err != nil {
    return err
}
if _, err := txRepo.DeleteByConditionContext(
    ctx,
    "season_id = ?",
    []any{seasonID},
    &PvpPlan{},
); err != nil {
    return err
}
if err := txRepo.SaveBatchUpsertContext(ctx, plans); err != nil {
    return err
}
loaded, err := txRepo.FindByConditionContext(ctx, "season_id = ?", []any{seasonID}, &PvpPlan{})
if err != nil {
    return err
}
if err := validatePlans(loaded); err != nil {
    return err
}
if err := tm.Commit(); err != nil {
    return err // 业务侧按自身规则处理 commit-unknown
}

事务 Repository 只执行同步、串行的事务性 DML,不接入 WAL、WriteBuffer 或 DB 级 Prepared Statement 缓存。目标表必须使用 InnoDB 等事务引擎,同一 Unit of Work 内不得混入会隐式提交的 DDL。Commit/Rollback 后,已取得的 Repository 句柄永久失效。事务内 auto-increment 主键只在 Commit 成功后回填 Entity;回滚到保存点会同步丢弃保存点后的待回填 ID,Commit 返回 error 时仍须按 commit-unknown 规则回读并协调内存状态。若直接使用 TransactionManager.Query/QueryContext,在返回的 Rows.Close 前不得与同一 manager 的 Repository、Exec、保存点或 Commit/Rollback 并发混用。


核心特性

ORM 功能
  • ORM: 基于反射的自动对象关系映射
  • JPA 风格实体继承 - 通过结构体嵌入实现继承,代码量减少 90%
  • UPSERT 自动处理 - 所有 Save 操作自动使用 INSERT...ON DUPLICATE KEY UPDATE
  • 字段忽略机制 - 支持 db:"-" 和无 db tag 忽略字段
查询功能 ⭐ NEW!
  • 命名参数查询 - 使用 {paramName} 语法,更清晰易维护
  • 便利查询方法 - 直接返回标量值或切片
  • 标量查询 - QueryToInt/Int64/String/Float64/Bool
  • 切片查询 - QueryToXxxSlice
  • OLAP 查询 - 支持 COUNT, SUM, AVG, MAX, MIN 等聚合函数
更新功能 ⭐ NEW!
  • 命名参数批量更新 - ExecuteUpdateMultiRowsNamed(sql, []map[string]any)
  • 命名参数单行更新 - ExecuteUpdateNamed(sql, map[string]any)
  • 向后兼容 - 仍支持位置参数 ?
数据库功能
  • 分片策略 - 支持多种数据库和表分片策略
  • CRUD 操作 - 简化的数据访问接口
  • 连接池 - 高效的数据库连接管理
  • 事务管理 - 支持复杂事务和保存点
  • 数据迁移 - 版本控制的数据库模式迁移
系统功能
  • 插件系统 - 可扩展的钩子架构,支持监控和自定义逻辑
  • 实体缓存 - 线程安全的元数据缓存
  • 包扫描 - 自动类型发现和注册
  • 监控 - 性能监控、指标收集和日志记录
  • 健康检查 - 数据库连接和连接池健康监控
  • 配置管理 - 灵活的配置加载和管理
  • 日志系统 - 结构化日志记录

MonitoringReportGenerator.ExportReport 与 MetricsCollector.ExportToFile 的产物可能包含数据库、指标、标签、告警等业务监控标识。导出采用同目录临时文件原子替换,文件权限固定为 Unix 0600 / Windows 当前进程身份专用 DACL;由库新建的目录会设为私有。仍应写入受控目录,禁止提交仓库、公开下载或由不受信任进程共享。


快速开始

命名参数查询 - 新功能
基础查询
package main

import (
    "fmt"
    "github.com/neko233-com/db233-go/pkg/db233"
)

func main() {
    db := db233.InitDbManager(...) // 初始化

    // 命名参数查询
    sql := "SELECT * FROM users WHERE age > {minAge} AND status={status} ORDER BY id"
    rows := db.QueryNamed(sql, map[string]any{
        "minAge": 18,
        "status": "active",
    })
    
    for _, row := range rows {
        fmt.Printf("ID: %v, Name: %v, Age: %v\n", 
            row["id"], row["name"], row["age"])
    }
}
标量查询
// 查询单个值 - 自动转换类型
count := db.QueryNamedToInt64(
    "SELECT COUNT(*) FROM users WHERE age > {minAge}",
    map[string]any{"minAge": 18},
)
fmt.Printf("用户数: %d\n", count)

// 查询字符串
name := db.QueryNamedToString(
    "SELECT name FROM users WHERE id={userId}",
    map[string]any{"userId": 1},
)
fmt.Printf("用户名: %s\n", name)

// 查询列表
ids := db.QueryNamedToInt64Slice(
    "SELECT id FROM users WHERE status={status} ORDER BY id",
    map[string]any{"status": "active"},
)
fmt.Printf("活跃用户ID: %v\n", ids)
命名参数批量更新 - 新功能
单行更新
import "time"

sql := "UPDATE users SET email={email}, updated_at={updatedAt} WHERE id={userId}"
affected, err := db.ExecuteUpdateNamed(sql, map[string]any{
    "userId": 123,
    "email": "new@example.com",
    "updatedAt": time.Now().Unix(),
})
if err != nil {
	    fmt.Printf("更新失败: %s\n", db233.SafeErrorSummary(err))
    return
}
fmt.Printf("影响行数: %d\n", affected)
批量更新
import "time"

sql := "UPDATE products SET price={price}, stock={stock}, updated_at={updatedAt} WHERE id={id}"
updates := []map[string]any{
    {
        "id": 1,
        "price": 99.99,
        "stock": 100,
        "updatedAt": time.Now().Unix(),
    },
    {
        "id": 2,
        "price": 149.99,
        "stock": 50,
        "updatedAt": time.Now().Unix(),
    },
    {
        "id": 3,
        "price": 199.99,
        "stock": 25,
        "updatedAt": time.Now().Unix(),
    },
}

affected := db.ExecuteUpdateMultiRowsNamed(sql, updates)
fmt.Printf("批量更新了 %d 个产品\n", affected)
JPA 风格实体继承
// 基础实体
type BaseEntity struct {
    ID        int64  `db:"id" primary_key:"true"`
    CreatedAt int64  `db:"created_at"`
    UpdatedAt int64  `db:"updated_at"`
}

// 用户实体 - 通过嵌入继承
type User struct {
    BaseEntity  // 继承基础字段
    Name        string `db:"name"`
    Email       string `db:"email"`
    Age         int    `db:"age"`
}

// 使用
user := &User{
    Name:  "Alice",
    Email: "alice@example.com",
    Age:   25,
}

// 自动 UPSERT - 无需手动处理主键冲突
if err := db.Save(user); err != nil {
	    fmt.Printf("保存失败: %s\n", db233.SafeErrorSummary(err))
}
CRUD 操作
// 创建
user := &User{Name: "Bob", Email: "bob@example.com", Age: 30}
if err := db.Save(user); err != nil {
	    fmt.Printf("创建失败: %s\n", db233.SafeErrorSummary(err))
}

// 查询
var savedUser User
if err := db.FindById(user.ID, &savedUser); err != nil {
	    fmt.Printf("查询失败: %s\n", db233.SafeErrorSummary(err))
}

// 更新
user.Name = "Bob Smith"
if err := db.Update(user); err != nil {
	    fmt.Printf("更新失败: %s\n", db233.SafeErrorSummary(err))
}

// 删除
if err := db.Delete(user); err != nil {
	    fmt.Printf("删除失败: %s\n", db233.SafeErrorSummary(err))
}

命名参数完整指南

语法规则
  1. 占位符格式 - 使用 {paramName} 表示占位符
  2. 参数传递 - 通过 map[string]any 传递参数值
  3. 参数名规则 - 可以包含字母、数字和下划线
  4. 不区分大小写 - 参数名区分大小写
支持的方法
方法 返回类型 说明
QueryNamed() []map[string]any 原始查询结果
QueryNamedToInt() int 单个 int 值
QueryNamedToInt64() int64 单个 int64 值
QueryNamedToString() string 单个 string 值
QueryNamedToFloat64() float64 单个 float64 值
QueryNamedToInt64Slice() []int64 int64 切片
QueryNamedToStringSlice() []string string 切片
ExecuteUpdateNamed() (int64, error) 单行更新
ExecuteUpdateMultiRowsNamed() int 批量更新
使用示例
复杂查询
sql := `SELECT u.id, u.name, COUNT(o.id) as order_count
        FROM users u
        LEFT JOIN orders o ON u.id = o.user_id
        WHERE u.created_at > {startDate}
          AND u.status = {status}
          AND u.age BETWEEN {minAge} AND {maxAge}
        GROUP BY u.id
        ORDER BY order_count DESC`

results := db.QueryNamed(sql, map[string]any{
    "startDate": 1609459200,  // 2021-01-01
    "status":    "active",
    "minAge":    18,
    "maxAge":    65,
})

for _, row := range results {
    fmt.Printf("用户: %v, 订单数: %v\n", row["name"], row["order_count"])
}
条件更新
sql := `UPDATE inventory 
        SET quantity = quantity - {decrease}, updated_at = {now}
        WHERE product_id = {productId} AND quantity >= {decrease}`

affected, err := db.ExecuteUpdateNamed(sql, map[string]any{
    "decrease":  10,
    "productId": 123,
    "now":       time.Now().Unix(),
})

if err != nil {
	    fmt.Printf("库存扣减失败: %s\n", db233.SafeErrorSummary(err))
}
错误处理
缺少参数
sql := "SELECT * FROM users WHERE id={userId}"
// ❌ 错误:缺少 userId 参数
rows := db.QueryNamed(sql, map[string]any{})
// 返回错误:缺少必需的参数:userId
未闭合的占位符
sql := "SELECT * FROM users WHERE id={userId"  // ❌ 缺少 }
rows := db.QueryNamed(sql, map[string]any{"userId": 1})
// 返回错误:SQL 中存在未闭合的占位符
性能对比
操作 位置参数方式 命名参数方式 性能差异
单行查询 ~0.5ms ~0.5ms 相同 ✅
批量更新 10 行 ~5ms ~5ms 相同 ✅
批量更新 100 行 ~50ms ~50ms 相同 ✅

结论: 性能完全相同,优先使用命名参数获得更好的代码质量。


与位置参数的对比

特性 位置参数 ? 命名参数 {name}
易读性 ❌ 差 ✅ 优秀
易维护 ❌ 差 ✅ 优秀
参数顺序敏感 ✅ 严格 ✅ 灵活
出错率 ❌ 较高 ✅ 较低
性能 ✅ 高 ✅ 相同
向后兼容 ✅ 支持 ✅ 新增
推荐使用 ❌ 不推荐 ✅ 强烈推荐

API 文档

底层 Native SQL 接口
// 执行原生 SQL 并返回行数据
rows := db.ExecuteSqlByStatement(statement)

// 执行更新操作
affected, err := db.ExecuteUpdate(sql, params...)

// 批量更新(位置参数)
affected := db.ExecuteUpdateMultiRows(sql, [][]any{...})
ORM 查询接口
// 快捷查询 - 返回原始行数据
rows := db.Query(sql, params...)

// ORM 实体查询
var users []User
repo := db233.NewBaseCrudRepository(db)
repo.Find(query, &users)
便利查询接口
// 标量查询 - 旧方式(位置参数)
count := db.QueryToInt64("SELECT COUNT(*) FROM users WHERE age > ?", 18)

// 标量查询 - 新方式(命名参数)✨
count := db.QueryNamedToInt64("SELECT COUNT(*) FROM users WHERE age > {minAge}", 
    map[string]any{"minAge": 18})

测试

测试覆盖

✅ 10 个命名参数功能测试

  • TestNamedParamsBasicUpdateMultiple - 批量更新测试
  • TestNamedParamsSingleUpdate - 单行更新测试
  • TestNamedParamsQuery - 基础查询测试
  • TestNamedParamsQueryToInt64 - Int64 查询测试
  • TestNamedParamsQueryToString - String 查询测试
  • TestNamedParamsQueryToInt - Int 查询测试
  • TestNamedParamsQueryToFloat64 - Float64 查询测试
  • TestNamedParamsQueryToInt64Slice - Int64 切片查询测试
  • TestNamedParamsQueryToStringSlice - String 切片查询测试
  • TestNamedParamsPerformance - 性能测试

✅ 50+ 个现有功能测试

  • CRUD 操作测试
  • ORM 映射测试
  • UPSERT 测试
  • 继承机制测试
  • 分片策略测试
  • 缓存管理测试
  • 插件系统测试
  • 监控和指标测试
运行测试
# 运行所有测试
go test ./tests -timeout 120s

# 运行命名参数测试
go test ./tests -v -run "TestNamedParams" -timeout 120s

# 运行特定测试
go test ./tests -v -run "TestNamedParamsBasicUpdateMultiple" -timeout 120s

# 查看详细输出
go test ./tests -v -timeout 120s
测试结果
✅ TestNamedParamsBasicUpdateMultiple PASS
✅ TestNamedParamsSingleUpdate PASS
✅ TestNamedParamsQuery PASS
✅ TestNamedParamsQueryToInt64 PASS
✅ TestNamedParamsQueryToString PASS
✅ TestNamedParamsQueryToInt PASS
✅ TestNamedParamsQueryToFloat64 PASS
✅ TestNamedParamsQueryToInt64Slice PASS
✅ TestNamedParamsQueryToStringSlice PASS
✅ TestNamedParamsPerformance PASS

总计:60+ 个测试全部通过 ✅

安装

go get github.com/neko233-com/db233-go@latest

快速示例

package main

import (
    "fmt"
    "github.com/neko233-com/db233-go/pkg/db233"
)

func main() {
    // 初始化数据库
    dbManager := db233.InitDbManager(db233.Config{
        DataSourceName: "user:password@tcp(localhost:3306)/database",
        DriverName:     "mysql",
    })
    db := dbManager.GetDefaultDb()

    // 定义实体
    type User struct {
        ID    int64  `db:"id" primary_key:"true"`
        Name  string `db:"name"`
        Age   int    `db:"age"`
    }

    // 命名参数查询 - 新方式 ⭐
    users := db.QueryNamed(
        "SELECT * FROM users WHERE age > {minAge}",
        map[string]any{"minAge": 18},
    )
    fmt.Printf("找到 %d 个成年用户\n", len(users))

    // 命名参数更新 - 新方式 ⭐
    affected := db.ExecuteUpdateMultiRowsNamed(
        "UPDATE users SET age={age} WHERE id={id}",
        []map[string]any{
            {"id": 1, "age": 20},
            {"id": 2, "age": 25},
        },
    )
    fmt.Printf("更新了 %d 个用户\n", affected)

    // ORM CRUD
    user := &User{Name: "Alice", Age: 30}
    db.Save(user)

    db.Close()
}

常见问题

Q: 命名参数方式和位置参数方式性能有差异吗?

A: 没有差异。两种方式的性能完全相同。参数替换发生在 SQL 执行前,几乎没有开销。建议优先使用命名参数获得更好的代码可读性。

Q: 如何处理命名参数中的特殊字符?

A: 使用反引号引用参数名。例如:{user_name} 对应 map[string]any{"user_name": value}

Q: 命名参数是否支持默认值?

A: 不支持。所有参数必须显式提供。如需默认值,建议在应用层处理。

Q: 如何在命名参数中使用 NULL 值?

A: 直接传递 nil。例如:map[string]any{"email": nil}

Q: 是否可以混合使用位置参数和命名参数?

A: 不建议。建议在整个项目中保持一致的风格。


游戏逻辑服接入(v1.0.2+)

配置最佳实践(持续维护)

升级依赖
go get github.com/neko233-com/db233-go@v1.1.0
配置文件 config/db233-performance.json
{
  "concurrentMaxWorkers": 16,
  "batchUpsertChunkSize": 200,
  "writeBufferEnabled": true,
  "writeBufferFlushIntervalMs": 100,
  "maxOpenConns": 100,
  "maxIdleConns": 20,
  "enableLocalJournal": true,
  "localJournalPath": "./data/db233_journal",
  "entityCache": {
    "enabled": true,
    "evictionPolicy": "lru",
    "maxSessions": 10000,
    "sessionFlushIntervalMs": 60000,
    "flushOnEvict": true,
    "entityTypeLimits": {
      "PlayerBagEntity": 8000
    }
  }
}
entityCache 字段 说明
enabled 是否启用 Session 实体缓存(读内存、写 dirty 延迟落库)
evictionPolicy 淘汰策略,默认 lru
maxSessions 全局最大在线 Session 数,超出 LRU 淘汰
sessionFlushIntervalMs 定时刷写 dirty 到 DB(默认 60000=1 分钟);0 表示不自动刷写,仅下线/关服时落库
flushOnEvict LRU 淘汰前是否先刷写 dirty
negativeCacheEnabled 负缓存(默认 false);确认无记录后不再 SELECT
entityTypeLimits 各 XxxEntity 类型在缓存中的最大实例数(跨 Session 统计)

运行期可通过 GetEntityCacheSettings().Set("sessionFlushIntervalMs", 120000) 动态调整刷写间隔。
负缓存也可 Session 级 动态开关(不影响全局):session.SetNegativeCacheEnabled(true)。

启动初始化(一次性,运行期不变)
opts := db233.DefaultGameDbOptions()
// 生产必填:先从数据库中的持久化 epoch 元数据读取;清库/重建后必须更换。
opts.DatabaseGeneration = dataEpoch.EpochID
opts.PerformanceConfigPath = "config/db233-performance.json"
opts.EntityTypes = []db233.IDbEntity{&PlayerBaseEntity{}, &PlayerBagEntity{} /* 全部玩家表 */}

// 白名单:仅注册的 XxxEntity 可走 Session 缓存(JPA 风格)
opts.CacheableEntities = []db233.CacheableEntitySpec{
    {Prototype: &PlayerBaseEntity{}},
    {Prototype: &PlayerBagEntity{}, MaxInstances: 8000},
}
opts.EnableEntityCache = true

dbConfig := db233.NewDefaultMySQLConfig(host, port, user, pass, database)
sessionRepo, err := db233.InitGameDb(db, dbConfig, opts)
if err != nil { return err }
// db.SessionRepo 已绑定;关服必须检查 db.Close() 返回值。

DatabaseGeneration 会同时保护 Session、WriteBuffer、WAL 和失败重试队列。启动时必须先从数据库读取 epoch,再初始化 db233;运行中清库必须使用两阶段屏障,详见 数据库代次与安全清库。

登录 / 在线 / 下线
// 登录:并发加载可缓存实体到 L1(未注册类型不加载)
session, _ := sessionRepo.OpenSession(playerId, loginEntityTypes)

// 读:走内存(未命中可 GetOrLoad)
bag := session.Get(&PlayerBagEntity{}).(*PlayerBagEntity)

// 写:L1 + dirty;缓存开启时不立即写库,由定时刷写或下线/关服落库
bag.Gold += 100
if err := session.MarkDirty(bag); err != nil { return err }

// 下线:强制刷写 dirty 到 DB(同一 playerId PK,WAL 保护)
if err := sessionRepo.CloseSession(playerId); err != nil { return err }

// 关服:先停止业务/raw SQL 写入,再由 Close 严格刷写并关闭全部组件。
if err := db.Close(); err != nil { return err }

MarkDirty/Put 会立即捕获与业务对象隔离的不可变持久化快照;同一表和主键在下次 flush 前只保留最后一版。快照完成后继续修改内存对象不会改变已经排队的版本,下一次修改后必须再次 MarkDirty。调用快照时业务必须自行保证源对象没有并发写;含锁、channel、func、非导出可变状态的复杂实体应实现 EntitySnapshotter 提供受控深拷贝。

Db.Close() 会先拒绝新的 managed write,再依次排空 Session、WriteBuffer、WAL 和失败队列,最后停止后台任务并关闭连接。数据库不可用时,可恢复实体会先保留在本地 WAL,但 Close 仍返回聚合错误供进程告警;禁止忽略该错误。Close 幂等,重复调用返回同一结果。直接使用 Db.DataSource 的写入不受自动准入控制,必须由业务侧 shutdown writer gate 先行停止并排空。

Flush 写库压力指标
// lifetime:从本 Db 第一次真正 flush Exec 开始计算。
metrics := db.FlushWriteMetrics()
log.Printf("flush SQL/s=%.2f attempted=%d succeeded=%d failed=%d",
    db.AverageFlushWritesPerSecond(),
    metrics.AttemptedSQL,
    metrics.SucceededSQL,
    metrics.FailedSQL,
)

// 自选窗口:例如每 10 秒采样一次。
previous := metrics
time.Sleep(10 * time.Second)
rates := db.FlushWriteMetrics().RateSince(previous)
log.Printf("10s flush SQL/s=%.2f entities/s=%.2f",
    rates.AttemptedSQLPerSecond,
    rates.AttemptedEntitiesPerSecond,
)

AttemptedSQL 只统计 db233 管理的状态 flush:Session(含定时、下线、关服、代次排空)、WriteBuffer、显式 UpdateBatchUpsert 与恢复回放真正发给 database/sql 的 Exec;不统计调用方直接使用 DataSource / GetDataSource、raw SQL 或事务 Repository 发出的写入。合并后的 SQL 只算 1 次,每个 chunk 各算 1 次;失败请求也会形成数据库压力,因此计入 attempted。SQL 构建、序列化、WAL 追加或 Prepare 在 Exec 前失败不计;Exec 成功后即计 succeeded,即使后续 RowsAffected 或 WAL 清理失败。BySource 可区分 session、write_buffer、manual、wal_replay、fault_tolerance_replay;指标不保存 SQL、参数、错误文本、表名或玩家标识。

数据不丢保证
机制 说明
WAL 先落盘 fsync 后写库,失败保留 pending.ndjson
无限重试 FaultTolerantManager 默认永不丢弃
UPSERT 幂等 使用稳定业务主键时,实体 Save/Update/UPSERT 可安全重放
数据库代次 清库后隔离旧 Session、缓冲、WAL 与失败重试,防止历史数据复活

恢复语义是 at-least-once,不是跨数据库的 exactly-once。任意 ExecuteUpdate 在“服务端已提交、客户端收到连接错误”时可能被重复执行;这类 SQL 必须自行满足幂等性,或携带数据库唯一约束保护的业务幂等键。任何写 API 返回错误时,即使数据已进入 WAL/失败队列,业务层也不得向上游确认成功。

SQL 日志隐私

默认只记录 SQL 动词;不记录 SQL 文本、长度、可字典猜测的稳定哈希、绑定参数或驱动错误原文。包级 Log* 运行时日志还会把所有裸字符串参数变为仅含类型的摘要,防止表名、列名、路径、配置键或玩家标识意外外泄。临时诊断可调用 db233.SetLogFullSQL(true),完整 SQL 会以安全引用形式输出(控制字符会转义),参数仍不记录。完整 SQL 可能包含调用方自行拼入的字面量,只能在受控环境短时开启,诊断结束后必须恢复为 false。公开日志或 HTTP 错误使用 db233.SafeErrorSummary(err);应用若通过 GetLogger() 主动记录业务字符串,应自行承担脱敏责任。

读路径:缓存命中零查库

登录 OpenSession 会把可缓存实体一次性加载进 L1;之后:

  • session.Get(&XxxEntity{}) — 有值直接返回,不查库
  • session.GetOrLoad(&XxxEntity{}) — 正缓存命中不查库;负缓存开启且已确认无记录也不查库
  • session.IsResolved(&XxxEntity{}) — 是否已解析(有实体或负缓存 absent)
  • session.SetNegativeCacheEnabled(true) — Session 级负缓存开关(默认全局 false)
bag, _ := session.GetOrLoad(&PlayerBagEntity{})
if bag == nil {
    // 登录时已确认无记录,不会重复 SELECT
}
连接池(等价 Java HikariCP)

Go 标准库 database/sql.DB 即连接池。db233 两层配置:

层级 配置位置 对应 Java
创建时 config.local.json 或 DbConnectionConfig Hikari maximumPoolSize / minimumIdle
运行期 db233-performance.json 的 maxOpenConns 等 动态调参

InitGameDb 内调用 RegisterDbForConnectionPool(db),与 performance JSON 联动。

推荐游戏服参数(单逻辑服写库):

{
  "maxOpenConns": 50,
  "maxIdleConns": 10,
  "connMaxLifetimeSec": 3600,
  "connMaxIdleTimeSec": 600
}
本地测试配置 config.local.json / config.local.yaml(勿提交 Git)

安全:真实 host / password 只能写在下列 gitignore 文件中。仓库内仅保留 *.example 占位符。
推送前执行:./scripts/check-secrets.ps1

复制模板并填入真实连接(Unix 必须是 0600 或更严格):

install -m 600 config.local.json.example config.local.json
# 或
install -m 600 config.local.yaml.example config.local.yaml

Windows 使用仅当前用户/服务账号可访问的 NTFS 目录:

Copy-Item config.local.json.example config.local.json
{
  "host": "your-rds.mysql.rds.aliyuncs.com",
  "port": 3306,
  "username": "root",
  "password": "your-password",
  "database": "db233_go",
  "maxOpenConns": 50,
  "maxIdleConns": 10
}

*.local.json / config.local.json / *.local.yaml 已在 .gitignore 中忽略。加载器拒绝符号链接、非普通文件、超过 1 MiB 的配置,以及 Unix 下 group/other 可读写的文件;生产凭据优先由秘密管理系统注入。

// 本地开发 / 测试
db, dbConfig, err := db233.OpenDbFromLocalConfig("config.local.json")
sessionRepo, err := db233.InitGameDb(db, dbConfig, opts)

集成测试仅从 DB233_TEST_DSN 或未纳入 Git 的 config.local.json 读取连接,并强制要求 loopback/本机 Unix socket,避免误连远程数据库。常用本地环境可使用 127.0.0.1:3306 / root / root / db233_go。

Go 框架性能对比(实测)

环境:本地 MySQL 127.0.0.1:3306/db233_go,Go 1.25.12+。 复现:

cd benchmarks && go test -run TestFrameworkCompare_Report -timeout 3m -v
cd .. && go test ./tests/ -run "TrafficBurst|TestPerfStability" -timeout 3m -v
cd benchmarks && go test -run TestStability -timeout 3m -v
延迟对比(中位数 ms,越小越好 · 启用 FastOrmScan + 冷启动预热)

色阶同文首:按列 越小越绿、越大越红。

框架 单次 PK 读 登录 3 表 批量 UPSERT×50 Session 读×1000
db233-go ~10.8 ~12.6 ~13.0 <0.001
database/sql 21.5 67.3 581 —
sqlx 18.9 58.1 974 —
GORM 23.3 74.0 54.6 ~21s
相对基线(database/sql 单次读 = 1.0×)
场景 db233-go GORM 结论
单次 PK 读 0.50×(快 2×) 1.08× 直扫字段 + Stmt 缓存 + 启动预热
登录 3 表 5.4× 更快 0.91× FindByIdConcurrent 并发加载
批量写 50 行 45× 更快 10.6× 单条 SQL 批量 UPSERT
在线读×1000 >10⁶× ~21s 估算 Session L1 内存读

游戏服应走 OpenSession + session.Get:在线读不经过 ORM/DB 往返,这是相对 Spring JPA / GORM 一级缓存(Session) 的结构性优势。

稳定性验证(突发流量 / 抖动)
测试 场景 结果
TestStability_TrafficBurst 80 goroutine × 15 混合读写/Session 0 错误,无 Session 泄漏
TestStability_ConnectionPoolSpike 30×5 并发读,池上限 10 Ping 恢复,池 idle=10
TestStability_LRUBurst 100 Session 洪峰,max=30 LRU 在线数=30
TestStability_WALBurst 20×10 并发 WAL 写 pending=0
TestTrafficBurst_Stability 50 worker 突发 连接池恢复

停止优化条件(已满足):单次读 ≤2.5× raw SQL;登录/批量写 ≥ GORM;Session 读数量级领先;稳定性测试全绿。


常见问题 FAQ

db233-go 是什么?和 GORM 有什么区别?

db233-go 是面向 有状态游戏逻辑服 的 Go ORM:登录后玩家数据在 Session 内存(L1),在线 session.Get 不查库;写用 批量 UPSERT + WAL。
与 GORM 相比:RDS 实测 单次 PK 读更快、Session 读 1000 次亚毫秒级(GORM 需循环查库)。通用 CRUD / 关联预加载仍可选 GORM。
→ 完整对比 docs/COMPARE-ORM.md · docs/FAQ.md

如何安装与初始化游戏服?
go get github.com/neko233-com/db233-go@v1.1.0
install -m 600 config.local.json.example config.local.json   # Unix 本地凭据,勿提交 Git
sessionRepo, _ := db233.InitGameDb(db, dbConfig, opts) // 见上文「游戏逻辑服接入」
数据库密码会进 Git 吗?

不会(若遵循规范)。真实连接仅写在 gitignore 的 config.local.json / config.local.yaml;推送前运行 ./scripts/check-secrets.ps1。

在线读慢怎么办?

业务读应走 session.Get,不要循环 repo.FindById。FindById 仅用于未 OpenSession 或运维查询。见 docs/FAQ.md。

更多问题 → docs/FAQ.md(含英文 Quick Answers)


普通实体统一建表与迁移

业务只需提供实体原型清单,db233-go 统一完成批量建表、补列、建索引、并发幂等和最终严格验证。生产安全默认不修改类型、不删除列、不替换或删除索引:

report, err := db.AutoMigrateSchema(ctx, []any{
    &PlayerEntity{},
    &InventoryEntity{},
}, nil)
if err != nil {
    return err
}
_ = report

启动前可先用 DryRun 审阅计划,或调用 VerifySchema 做纯只读检查。完整权限、报告与 MySQL DDL 边界见 统一 Schema 建表与迁移。

埋点描述文件自动建表

适合埋点接收服:客户端新增行为埋点时,只改 JSON 描述文件;db233-go 根据描述自动建表、补列、建索引,并暴露元数据给上层做 map[string]any 上报校验。

此机制与现有 IDbEntity / CrudManager.AutoCreateTable 是两套独立机制,可同时存在,互不影响。

描述文件只支持 JSON;文件内允许 // 和 /* */ 注释。完整样板见 docs/config/tracking-schema.example.json。

{
  // JSONC: .json 文件允许注释
  "version": "1",
  "tables": [
    {
      "name": "player_behavior_events",
      "comment": "player behavior tracking",
      "columns": [
        {"name": "player_id", "type": "string", "size": 64, "primaryKey": true, "required": true},
        {"name": "event_time", "type": "timestamp", "required": true, "default": "CURRENT_TIMESTAMP"},
        {"name": "action", "type": "string", "size": 64, "required": true, "enum": ["login", "level_up"]},
        {"name": "level", "type": "int"},
        {"name": "extra", "type": "json"}
      ],
      "indexes": [
        {"name": "idx_player_behavior_action", "columns": ["action"]}
      ]
    }
  ]
}
schema, plan, err := db233.ApplyTrackingSchemaFile(db, "tracking-schema.json", nil)
if err != nil {
	    log.Fatal(db233.SafeErrorSummary(err))
}
_ = plan

table, ok := schema.GetTable("player_behavior_events")
if !ok {
    log.Fatal("tracking table 未定义")
}
payload := map[string]any{
    "player_id":  "p001",
    "event_time": "2026-06-12T10:00:00Z",
    "action":     "login",
    "level":      10,
    "extra":      map[string]any{"device": "android"},
}
if errs := table.ValidatePayload(payload, false); len(errs) > 0 {
    panic(errs[0])
}
_, err = db233.InsertTrackingPayload(db, table, payload)

热重载:

reloader := db233.NewTrackingSchemaReloader(db, "tracking-schema.json", 5*time.Second, db233.TrackingSchemaApplyOptions{})
reloader.OnReload(func(schema *db233.TrackingSchema, plan db233.TrackingSchemaPlan) {
    // schema 可缓存给上报层做 KV 校验
})
reloader.Start()
defer reloader.Stop()

本地记录与增量同步:

opts := &db233.TrackingSchemaApplyOptions{
    CachePath: "runtime/tracking-schema.cache.json", // 可选;不填则使用 tracking-schema.json.cache.json
}
schema, plan, err := db233.ApplyTrackingSchemaFile(db, "configs/tracking-schema.json", opts)

机制说明:

  • 本地 cache 记录上次成功同步的描述文件 hash、版本、时间、SQL 数量。
  • 文件 hash 未变化时直接跳过 SQL 规划和执行。
  • 文件 hash 变化时读取数据库真实结构,只做增量改动:缺表建表、缺列补列、缺索引建索引。
  • ForceApply: true 可强制重新检查数据库结构。
  • DisableLocalCache: true 可关闭本地记录。

默认安全策略:只建表、补列、建索引,不删列。当前自动执行 SQL 路径支持 MySQL。


更新日志

完整记录见 CHANGELOG.md。

v1.1.0 (2026-07-22) — 生产一致性与生命周期加固
  • 新增数据库代次屏障,清库后旧 Session、WriteBuffer、WAL 和失败重试数据不会跨代写回
  • 补齐严格 ORM、事务、保存点、错误链、资源关闭与并发缓存的 fail-closed 契约
  • 新增真实 MySQL 100 玩家并发回归,以及 Linux/MySQL、race、benchmark 和 Windows CI 门禁
  • SQL 与配置日志默认脱敏;仅 db233.SetLogFullSQL(true) 显式 opt-in 可记录安全引用的完整 SQL,参数值与驱动错误原文不进入日志;公开边界统一使用 SafeErrorSummary
v1.0.10 (2026-07-22) — 严格错误传播与事务能力
  • 新增 Strict Query、Strict Entity Repository 和事务绑定 Repository
  • 修复事务 context 生命周期、终态 reset、rollback error 与 panic 回滚语义
  • 保持旧 Query、CrudRepository、Begin 和 WithTransaction API 编译兼容
v1.0.2 (2026-05-30) — 文档完善
  • 文档中心、FAQ、GORM 对比、项目概览
  • README 版本号与发版说明修正
v1.0.1 (2026-05-30) — 性能正式化
  • FastOrmScan、对象池、冷启动预热、发版 benchmark 门禁
  • 详见 CHANGELOG.md
v1.0.0 (2026-05-30) — 生产就绪:游戏服 Session 缓存 + WAL + 连接池

首个稳定版,面向有状态游戏逻辑服。

压测:go test ./tests/ -run TestPerfStability_Short -timeout 90s -v

v0.1.2 (2026-05-30) — Session 实体缓存 + 延迟刷写
  • EntityCache 配置(LRU / 按类型上限 / 定时刷写)
  • CacheableEntity 白名单 + InitGameDb 返回 SessionRepository
v0.1.0 (2026-05-30) — 游戏服高性能 + 数据不丢
  • FindByIds / SaveBatchUpsert / UpdateBatchUpsert / FindByIdConcurrent
  • Session L1 + WriteBuffer + LocalWriteJournal (WAL)
  • InitGameDb 一站式初始化

许可证

Apache License 2.0 - 详见 LICENSE 文件


贡献

欢迎提交 Issue 和 Pull Request!


文档最后更新: 2026-07-22 · v1.1.0 · 文档中心 · FAQ

Directories

Path Synopsis
pkg

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL