mongodb

package
v3.8.56 Latest Latest
Warning

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

Go to latest
Published: Oct 31, 2026 License: Apache-2.0 Imports: 26 Imported by: 1

Documentation

Overview

Package mongodb 提供基于 mongo-driver 的 MongoDB 客户端封装与集合操作增强。

该包通过 NewMongoDBClient 按 URI 缓存复用客户端,并以 Option 配置超时与连接池参数; Model 与 DecoratedCollection 在原生集合之上提供链式条件构造、故障保护、指标采集 与链路追踪;BeforeCreate、BeforeUpdate 负责在写入前完成结构体到 BSON 文档的转换与 _id 生成。

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func BeforeCreate

func BeforeCreate(document any) any

BeforeCreate 在写入前将输入转换为 BSON 文档:指针自动解引用,数组/切片递归逐项转换, 结构体按 bson 标签转为 bson.M,并为 ObjectID 类型或空 Id 字段补充 _id。 输入类型与转换假设不匹配时会触发类型断言 panic,调用方须传入结构体、切片或 bson.M。

func BeforeUpdate

func BeforeUpdate(document any) any

BeforeUpdate 在更新前将输入转换为 BSON 文档:指针解引用、数组递归转换,结构体按 bson 标签提取字段;标记 over 标签的字段被跳过,不进入更新内容。

func Caller added in v3.4.4

func Caller(skip int) map[string]string

Caller 返回跳过 skip 层调用栈后的调用方文件行号与函数名映射,供日志与追踪定位使用; skip 超出调用栈深度时返回零值字段。

func SetSlowThreshold added in v3.4.4

func SetSlowThreshold(threshold time.Duration)

SetSlowThreshold 全局设置 MongoDB 慢操作判定阈值。

Types

type DecoratedCollection added in v3.4.4

type DecoratedCollection struct {
	*mongo.Collection

	// EnableMetric 是否采集 MongoDB 操作指标。
	EnableMetric bool
	// EnableTrace 是否挂载 MongoDB 链路追踪。
	EnableTrace bool
	// contains filtered or unexported fields
}

DecoratedCollection 在原生 mongo.Collection 之上提供链式条件构造、指标采集与 链路追踪增强。链式条件在单次数据操作结束后自动清空,不会残留到下一次操作。

实例由 newCollection 内部创建,不对外构造;同一实例上的链式条件方法不保证并发安全, 应在单次操作内顺序调用。

func (*DecoratedCollection) Aggregate added in v3.4.4

func (c *DecoratedCollection) Aggregate(ctx context.Context, pipeline any, result any) (err error)

Aggregate 执行聚合管道,结果解码到 result;pipeline 为聚合阶段数组, result 须为可写入的结果接收对象。游标错误会被清空条件后返回。

func (*DecoratedCollection) Count added in v3.4.4

func (c *DecoratedCollection) Count(ctx context.Context) (result int64, err error)

Count 统计匹配 Where filter 的文档数量,操作附带 5 秒超时。

func (*DecoratedCollection) CreateIndex added in v3.4.4

func (c *DecoratedCollection) CreateIndex(ctx context.Context, key bson.D, op *options.IndexOptions) (res string, err error)

CreateIndex 在当前集合上创建单个索引,返回索引名称;key 为索引键,op 为索引选项, 可为 nil。操作按开关上报追踪与指标。

func (*DecoratedCollection) Delete added in v3.4.4

func (c *DecoratedCollection) Delete(ctx context.Context) (count int64, err error)

Delete 按 Where 设置的 filter 删除匹配文档并返回删除数量;filter 为空时拒绝执行, 避免误删整集合。操作附带 5 秒超时。

func (*DecoratedCollection) Drop added in v3.4.4

func (c *DecoratedCollection) Drop(ctx context.Context) (err error)

Drop 删除当前集合本身,操作附带 5 秒超时;调用方须确认该集合可被整体删除。

func (*DecoratedCollection) DropIndex added in v3.4.4

func (c *DecoratedCollection) DropIndex(ctx context.Context, name string, opts *options.DropIndexesOptions) (err error)

DropIndex 按名称删除当前集合上的指定索引;opts 为删除选项,可为 nil。

func (*DecoratedCollection) Fields added in v3.4.4

func (c *DecoratedCollection) Fields(fields bson.M) *DecoratedCollection

Fields 设置返回文档的投影字段,返回集合自身以便链式调用。

func (*DecoratedCollection) FindMany added in v3.4.4

func (c *DecoratedCollection) FindMany(ctx context.Context, documents any) (err error)

FindMany 按累积的 filter、skip、limit、sort、fields 查询多条文档并解码到 documents; documents 必须为指向切片的指针,否则返回错误。游标在读取结束后关闭。

func (*DecoratedCollection) FindOne added in v3.4.4

func (c *DecoratedCollection) FindOne(ctx context.Context, document any) (err error)

FindOne 按累积的 filter、skip、sort、fields 查询单条文档并解码到 document; document 须为指向目标结构的指针。文档不存在时返回 mongo.ErrNoDocuments。

func (*DecoratedCollection) InsertMany added in v3.4.4

func (c *DecoratedCollection) InsertMany(ctx context.Context, documents any) (val *mongo.InsertManyResult, err error)

InsertMany 批量写入文档;documents 须为结构体切片或 bson 文档切片, 写入前由 BeforeCreate 逐项转换并生成 _id。返回批量插入结果。

func (*DecoratedCollection) InsertOne added in v3.4.4

func (c *DecoratedCollection) InsertOne(ctx context.Context, document any) (val *mongo.InsertOneResult, err error)

InsertOne 向当前集合写入单条文档;document 为结构体、bson.M 或原生文档, 写入前由 BeforeCreate 完成转换与 _id 生成,返回插入结果。

func (*DecoratedCollection) Limit added in v3.4.4

Limit 设置返回记录条数上限,返回集合自身以便链式调用。

func (*DecoratedCollection) ListIndexes added in v3.4.4

func (c *DecoratedCollection) ListIndexes(ctx context.Context, opts *options.ListIndexesOptions) (val []string, err error)

ListIndexes 返回当前集合全部索引的名称列表;opts 为列表选项,可为 nil。 游标读取失败时清空条件并返回错误。

func (*DecoratedCollection) Skip added in v3.4.4

Skip 设置跳过的记录条数,返回集合自身以便链式调用。

func (*DecoratedCollection) Sort added in v3.4.4

Sort 设置排序条件,返回集合自身以便链式调用。

func (*DecoratedCollection) UpdateMany added in v3.4.4

func (c *DecoratedCollection) UpdateMany(ctx context.Context, document any) (val *mongo.UpdateResult, err error)

UpdateMany 在 Where 设置的 filter 上批量更新文档,更新字段由 BeforeUpdate 提取后包装为 $set;返回更新结果。

func (*DecoratedCollection) UpdateOne added in v3.4.4

func (c *DecoratedCollection) UpdateOne(ctx context.Context, document any) (val *mongo.UpdateResult, err error)

UpdateOne 在 Where 设置的 filter 上更新单个文档,更新字段由 BeforeUpdate 提取后包装为 $set;返回更新结果。

func (*DecoratedCollection) UpdateOneRaw added in v3.4.4

func (c *DecoratedCollection) UpdateOneRaw(ctx context.Context, document any, opt ...*options.UpdateOptions) (val *mongo.UpdateResult, err error)

UpdateOneRaw 在 Where 设置的 filter 上更新单个文档,document 作为原生更新表达式透传, 不做 $set 包装;opt 为可选更新选项。返回更新结果。

func (*DecoratedCollection) UpdateOrInsert added in v3.4.4

func (c *DecoratedCollection) UpdateOrInsert(ctx context.Context, documents []any) (val *mongo.UpdateResult, err error)

UpdateOrInsert 在 Where 设置的 filter 上执行批量更新,匹配不到文档时插入; documents 中的文档须携带 _id。返回更新结果。

func (*DecoratedCollection) Where added in v3.4.4

Where 设置查询匹配条件,覆盖此前累积的 filter,返回集合自身以便链式调用。

type Model added in v3.4.4

type Model struct {
	// Collection 为包装了熔断、指标与追踪的增强集合。
	Collection *DecoratedCollection
	// contains filtered or unexported fields
}

Model 绑定一个集合的增强操作句柄,对外提供链式条件构造与数据操作方法。

实例由 MongoDB.NewModel 创建;Collection 对外暴露全部增强操作能力。

type MongoDB

type MongoDB struct {
	*mongo.Client
	// EnableMetric 是否采集 MongoDB 操作指标。
	EnableMetric bool
	// EnableTrace 是否挂载 MongoDB 链路追踪。
	EnableTrace bool
	// Name 为连接的数据库名称,取自 URI 路径。
	Name string
	// Uri 为原始连接 URI,作为连接缓存的去重标识。
	Uri string
	// contains filtered or unexported fields
}

MongoDB 包装原生 mongo.Client,附加指标、追踪开关、库名与 URI 等元信息, 并提供断开连接、Ping 校验与集合模型创建方法。

实例由 NewMongoDBClient 创建并按 URI 缓存复用;并发使用安全由底层 mongo.Client 保证。

func NewMongoDBClient added in v3.4.4

func NewMongoDBClient(uri string, opts ...Option) (*MongoDB, error)

NewMongoDBClient 依据 URI 创建并缓存 MongoDB 客户端。

同一 URI 复用已建立的连接;URI 缺少数据库名、URI 解析失败、连接或 Ping 失败时, 记录日志并 panic。建立连接的上下文超时为 5 秒,默认操作超时 3 秒,可由传入的 Option 覆盖。

func (*MongoDB) Close added in v3.4.2

func (cs *MongoDB) Close() error

Close 断开底层 mongo.Client 与服务端的连接,返回 Disconnect 的错误。

func (*MongoDB) MustNewCollection added in v3.4.4

func (m *MongoDB) MustNewCollection(collection string) *DecoratedCollection

MustNewCollection 返回指定集合的 DecoratedCollection;Ping 或创建失败时记录日志并终止程序。

func (*MongoDB) MustNewModel added in v3.4.4

func (m *MongoDB) MustNewModel(collection string) *Model

MustNewModel 为指定集合创建 Model;Ping 或创建失败时记录日志并终止程序,适用于启动期初始化。

func (*MongoDB) NewCollection added in v3.4.4

func (m *MongoDB) NewCollection(collection string) (*DecoratedCollection, error)

NewCollection 校验连通性后返回指定集合的 DecoratedCollection;Ping 失败时返回错误。

func (*MongoDB) NewModel added in v3.4.4

func (m *MongoDB) NewModel(collection string) (*Model, error)

NewModel 校验连通性后为指定集合创建 Model,继承当前客户端的指标与追踪开关; Ping 失败时返回错误。collection 为集合名称,调用方须保证非空。

func (*MongoDB) Ping added in v3.4.4

func (m *MongoDB) Ping() error

Ping 校验与 MongoDB 服务端的连通性,返回 Ping 的错误。

func (*MongoDB) SetEnableMetric added in v3.8.21

func (m *MongoDB) SetEnableMetric(disableMetric bool) *MongoDB

SetEnableMetric 设置指标采集开关并返回客户端自身,便于链式调用。

func (*MongoDB) SetEnableTrace added in v3.8.21

func (m *MongoDB) SetEnableTrace(disableTrace bool) *MongoDB

SetEnableTrace 设置链路追踪开关并返回客户端自身,便于链式调用。

type Option added in v3.4.4

type Option func(opts *options.ClientOptions)

Option 是 mongo.ClientOptions 的配置选项函数,在 NewMongoDBClient 中依次装配。

func WithMaxConnIdleTime added in v3.4.4

func WithMaxConnIdleTime(d time.Duration) Option

WithMaxConnIdleTime 设置连接池中连接的最大空闲时长。

func WithMaxPoolSize added in v3.4.4

func WithMaxPoolSize(size uint64) Option

WithMaxPoolSize 设置连接池最大连接数。

func WithMinPoolSize added in v3.4.4

func WithMinPoolSize(size uint64) Option

WithMinPoolSize 设置连接池最小保持的连接数。

func WithTimeout added in v3.4.4

func WithTimeout(timeout time.Duration) Option

WithTimeout 设置客户端单次操作超时时间。

Jump to

Keyboard shortcuts

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