Documentation
¶
Index ¶
- func BuildCondition(params map[string]interface{}) (string, []interface{}, error)
- func Close() error
- func GetDbInstance() (*gorm.DB, error)
- func GormInit(config *PostgresConfig, models []interface{}) error
- func Health(ctx context.Context) error
- func Initialize(ctx context.Context, config *PostgresConfig, models ...interface{}) (*gorm.DB, error)
- func InitializeDatabase(ctx context.Context, config *Config, models ...interface{}) (*gorm.DB, error)
- func MigrateModels(ctx context.Context, models ...interface{}) error
- func MySQLDSN(config Config) (string, error)
- func RegisterDialector(driver Driver, factory DialectorFactory) error
- func WithScope(ctx context.Context, scope DataScope) context.Context
- func WithTx(ctx context.Context, fn func(tx *gorm.DB) error) error
- type Config
- type DataScope
- type DialectorFactory
- type Driver
- type Instance
- type Migration
- type Migrator
- type PageResult
- type PostgresConfig
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func BuildCondition ¶ added in v1.32.0
BuildCondition 构建 WHERE 条件(从 sg-mes-api 实战项目吸收的精华封装): 将 map 形式的查询参数转换为 GORM 可用的条件串与参数值, 支持常见操作符后缀,业务查询零样板。
用法:
params := map[string]interface{}{
"client_name like": "%" + keyword + "%",
"created_at >=": startDate,
"grade": 10,
}
condition, values, err := datasource.BuildCondition(params)
// condition: `client_name like ? AND created_at >= ? AND grade = ?`
db.Where(condition, values...).Find(&list)
支持的键格式:
- `field` 等值(= ?)
- `field like` 模糊(= LIKE ?)
- `field >` `>=` ` <` `<=` `<>` 比较
- `field in` 切片展开(IN (?, ?, ...))
- `field not in` NOT IN
- `field is null` / `field is not null` 空值判断(值忽略)
值处理:
- 空字符串忽略;nil 忽略;空切片忽略
- `like` 值自动前后加 %(传参时已带 % 则不重复加)
func GormInit ¶
func GormInit(config *PostgresConfig, models []interface{}) error
GormInit 保留旧版不接收 Context 的初始化入口。 新代码应使用 Initialize，以便调用方控制启动取消和超时。
func Initialize ¶
func Initialize(ctx context.Context, config *PostgresConfig, models ...interface{}) (*gorm.DB, error)
Initialize 校验配置、建立连接、执行 Ping，并按显式开关决定是否迁移 Model。 初始化失败会关闭已创建的连接池且不写入全局实例，后续调用可以安全重试。 返回的 *gorm.DB 属于默认实例；多数据源场景请使用 NewNamed。
func InitializeDatabase ¶
func InitializeDatabase(ctx context.Context, config *Config, models ...interface{}) (*gorm.DB, error)
InitializeDatabase 使用统一配置初始化默认关系数据库实例。 兼容入口：新代码建议使用 New / NewNamed 获得带生命周期的 Instance。
func MigrateModels ¶ added in v1.31.0
MigrateModels 对一组模型执行 AutoMigrate(业务手动迁移/初始化建表用)。 等价于 datasource.Get().DB().AutoMigrate(models...),但统一处理实例获取错误。
func MySQLDSN ¶
MySQLDSN 根据统一配置生成不记录到日志的 MySQL DSN。 调用方可以把返回值交给所选 MySQL GORM Driver，并通过 RegisterDialector 注册。
func RegisterDialector ¶
func RegisterDialector(driver Driver, factory DialectorFactory) error
RegisterDialector 注册或替换自定义关系数据库 Dialector。 典型用途是为 Oracle、SQL Server 或内部代理协议接入特定 GORM Driver。
Types ¶
type Config ¶
type Config struct {
// Driver 选择已注册的关系数据库驱动。
Driver Driver
// DSN 允许高级场景直接提供驱动连接串（SQLite 为文件路径）；禁止写入日志。
DSN string
// UserName 是数据库用户名。
UserName string
// Password 是数据库密码，禁止写入日志。
Password string
// Host 是数据库主机名或 IP。
Host string
// Port 是数据库监听端口。
Port int
// Database 是数据库名、Schema 服务名或驱动定义的逻辑数据库。
Database string
// SSLMode 是 PostgreSQL SSL 模式；其他驱动可以忽略。
SSLMode string
// Charset 是 MySQL 字符集，默认 utf8mb4。
Charset string
// TimeZone 是数据库会话时区，默认 Asia/Shanghai。
TimeZone string
// MaxIdleConns 是最大空闲连接数。
MaxIdleConns int
// MaxOpenConns 是最大打开连接数。
MaxOpenConns int
// ConnMaxLifetime 是连接最大复用时间。
ConnMaxLifetime time.Duration
// ConnectTimeout 是打开连接和 Ping 的最大时长。
ConnectTimeout time.Duration
// AutoMigrate 控制是否自动迁移 Model，默认关闭。
AutoMigrate bool
}
Config 定义关系数据库共享的连接、连接池和迁移配置。
type DataScope ¶ added in v1.11.0
DataScope 数据权限范围(组织/部门维度)。 与公共模型 OrgFields(org_id / dept_id)配套:业务查询时带上数据范围, 自动为 SQL 追加 org_id / dept_id 过滤条件,实现组织间数据隔离。
典型链路:
- 登录签发 token 时写入组织身份(apptoken.GenTokenFull)
- webiris.Auth 认证后通过 webiris.DataScope(ctx) 取回
- 查询时 Scopes(scope.Condition()) 自动过滤
func MustScope ¶ added in v1.11.0
MustScope 从 context 读取数据权限范围;未注入时返回零值(不限制)。 用于「范围可选」的业务场景,避免到处判断 ok。
func ScopeFrom ¶ added in v1.11.0
ScopeFrom 从 context 读取数据权限范围;未注入时返回 (零值, false)。 ctx 为 nil 时安全返回 (零值, false)。
func (DataScope) Condition ¶ added in v1.11.0
Condition 生成 GORM scope 过滤条件(字段名对齐 OrgFields 的 org_id/dept_id)。 仅对非零字段追加条件,零值字段不限制。
db.WithContext(ctx).Scopes(scope.Condition()).Find(&orders)
func (DataScope) ConditionFor ¶ added in v1.11.0
ConditionFor 生成使用自定义列名的过滤条件(业务表字段命名特殊时使用)。
type DialectorFactory ¶
DialectorFactory 根据统一配置创建 GORM Dialector。 实现不得记录 Config.DSN、Password 或其他认证信息。
type Driver ¶
type Driver string
Driver 标识关系数据库类型。
const ( // DriverPostgreSQL 使用 GORM 官方 PostgreSQL Dialector。 DriverPostgreSQL Driver = "postgres" // DriverMySQL 标识 MySQL/MariaDB，调用方需要注册选定的 GORM Dialector。 DriverMySQL Driver = "mysql" // DriverOracle 预留 Oracle 标识，调用方需要注册符合运行环境的 Oracle Dialector。 DriverOracle Driver = "oracle" // DriverSQLite 使用纯 Go SQLite 驱动（无 CGO），适合测试与轻量部署。 DriverSQLite Driver = "sqlite" )
type Instance ¶
type Instance struct {
// contains filtered or unexported fields
}
Instance 是独立的关系数据库连接实例。 一个进程可以创建多个实例（多数据源、读写分离、多租户），每个实例独立管理连接池与生命周期。
func NewNamed ¶
func NewNamed(ctx context.Context, name string, config *Config, models ...interface{}) (*Instance, error)
NewNamed 使用统一配置创建具名实例并注册到实例表。 同名实例已存在时返回错误；初始化失败不会注册任何实例。
type Migration ¶
type Migration struct {
// Name 是迁移名称（如 "20260815_create_orders"），重复名称会被拒绝。
Name string
// Up 执行迁移内容。
Up func(db *gorm.DB) error
// Down 回滚迁移内容；为 nil 时该迁移不可回滚。
Down func(db *gorm.DB) error
}
Migration 定义一次数据库结构迁移。 Name 必须全局唯一；Up 在事务中执行并记录版本，Down 用于回滚（可选）。
type Migrator ¶
type Migrator struct {
// contains filtered or unexported fields
}
Migrator 是轻量版本化迁移执行器。 迁移记录保存在 schema_migrations 表（可按需改名）。
func NewMigrator ¶
NewMigrator 创建迁移器。 迁移按传入顺序执行，未应用的部分在 Migrate 时按序补齐。
func (*Migrator) WithTableName ¶
WithTableName 覆盖默认迁移记录表名。
type PageResult ¶
type PageResult struct {
Total int64 // 符合条件的总记录数
Page int // 当前页（从 1 开始）
PageSize int // 每页大小
TotalPages int64 // 总页数
}
PageResult 是分页查询的元数据与结果容器。
type PostgresConfig ¶
type PostgresConfig struct {
// UserName 是数据库用户名。
UserName string
// Password 是数据库密码，禁止写入日志。
Password string
// Host 是数据库主机名或 IP。
Host string
// Port 是 PostgreSQL 监听端口。
Port int
// DbName 是目标数据库名称。
DbName string
// InitDb 是旧版自动迁移开关。
// Deprecated: 使用 AutoMigrate。
InitDb bool
// AliasName 是旧版连接别名字段，当前仅为源码兼容保留。
AliasName string
// SSL 是 PostgreSQL sslmode。
SSL string
// MaxIdleConns 是最大空闲连接数，零值使用默认值。
MaxIdleConns int
// MaxOpenConns 是最大打开连接数，零值使用默认值。
MaxOpenConns int
// ConnMaxLifetime 是连接可复用的最长时间，零值使用默认值。
ConnMaxLifetime time.Duration
// ConnectTimeout 是初始化和 Ping 的最大时长，零值使用默认值。
ConnectTimeout time.Duration
// AutoMigrate 控制是否在初始化成功后自动迁移 Model，默认关闭。
AutoMigrate bool
}
PostgresConfig 定义 PostgreSQL 建连、连接池和迁移策略。
Source Files
Directories