feat(db,docs): 优化数据库连接池与生产日志，新增 Web 访客端接入指南

server/internal/model/db_test.go

@@ -0,0 +1,96 @@
+package model
+
+import (
+	"database/sql"
+	"fmt"
+	"os"
+	"testing"
+	"time"
+
+	"gorm.io/driver/sqlite"
+	"gorm.io/gorm"
+	"gorm.io/gorm/logger"
+)
+
+func TestDefaultDBPoolConfig(t *testing.T) {
+	// 默认兜底测试
+	cfg := DefaultDBPoolConfig()
+	if cfg.MaxOpenConns <= 0 || cfg.MaxIdleConns <= 0 {
+		t.Fatalf("连接池默认值非法: %+v", cfg)
+	}
+	if cfg.MaxIdleConns > cfg.MaxOpenConns {
+		t.Fatalf("MaxIdleConns 不能大于 MaxOpenConns: %+v", cfg)
+	}
+
+	// 环境变量覆盖测试
+	os.Setenv("DB_MAX_OPEN_CONNS", "120")
+	os.Setenv("DB_MAX_IDLE_CONNS", "30")
+	os.Setenv("DB_CONN_MAX_LIFETIME_MINUTES", "120")
+	os.Setenv("DB_CONN_MAX_IDLE_MINUTES", "30")
+	defer func() {
+		os.Unsetenv("DB_MAX_OPEN_CONNS")
+		os.Unsetenv("DB_MAX_IDLE_CONNS")
+		os.Unsetenv("DB_CONN_MAX_LIFETIME_MINUTES")
+		os.Unsetenv("DB_CONN_MAX_IDLE_MINUTES")
+	}()
+
+	customCfg := DefaultDBPoolConfig()
+	if customCfg.MaxOpenConns != 120 {
+		t.Errorf("期望 MaxOpenConns=120, 实际=%d", customCfg.MaxOpenConns)
+	}
+	if customCfg.MaxIdleConns != 30 {
+		t.Errorf("期望 MaxIdleConns=30, 实际=%d", customCfg.MaxIdleConns)
+	}
+	if customCfg.ConnMaxLifetime != 120*time.Minute {
+		t.Errorf("期望 ConnMaxLifetime=120m, 实际=%v", customCfg.ConnMaxLifetime)
+	}
+	if customCfg.ConnMaxIdleTime != 30*time.Minute {
+		t.Errorf("期望 ConnMaxIdleTime=30m, 实际=%v", customCfg.ConnMaxIdleTime)
+	}
+}
+
+func TestApplyPoolConfig(t *testing.T) {
+	db, err := gorm.Open(sqlite.Open(fmt.Sprintf("file:pool_test_%d?mode=memory&cache=shared", time.Now().UnixNano())), &gorm.Config{})
+	if err != nil {
+		t.Fatalf("打开 sqlite 失败: %v", err)
+	}
+	sqlDB, err := db.DB()
+	if err != nil {
+		t.Fatalf("获取 sql.DB 失败: %v", err)
+	}
+
+	cfg := DBPoolConfig{
+		MaxOpenConns:    25,
+		MaxIdleConns:    5,
+		ConnMaxLifetime: 30 * time.Minute,
+		ConnMaxIdleTime: 10 * time.Minute,
+	}
+	ApplyPoolConfig(sqlDB, cfg)
+	ApplyPoolConfig(nil, cfg) // 防空指针保护
+
+	stats := sqlDB.Stats()
+	if stats.MaxOpenConnections != 25 {
+		t.Errorf("期望 MaxOpenConnections=25, 实际=%d", stats.MaxOpenConnections)
+	}
+}
+
+func TestBuildGormLogger(t *testing.T) {
+	os.Setenv("GIN_MODE", "release")
+	relLog := BuildGormLogger()
+	if relLog == nil {
+		t.Fatal("release logger 为空")
+	}
+
+	os.Setenv("GIN_MODE", "debug")
+	debLog := BuildGormLogger()
+	if debLog == nil {
+		t.Fatal("debug logger 为空")
+	}
+	os.Unsetenv("GIN_MODE")
+}
+
+func init() {
+	// 避免测试时与真实 sql.DB 产生类型告警
+	var _ *sql.DB
+	var _ = logger.Warn
+}