Documentation
¶
Overview ¶
Package mongodb 提供基于 mongo-driver 的 MongoDB 客户端封装与集合操作增强。
该包通过 NewMongoDBClient 按 URI 缓存复用客户端,并以 Option 配置超时与连接池参数; Model 与 DecoratedCollection 在原生集合之上提供链式条件构造、故障保护、指标采集 与链路追踪;BeforeCreate、BeforeUpdate 负责在写入前完成结构体到 BSON 文档的转换与 _id 生成。
Index ¶
- func BeforeCreate(document any) any
- func BeforeUpdate(document any) any
- func Caller(skip int) map[string]string
- func SetSlowThreshold(threshold time.Duration)
- type DecoratedCollection
- func (c *DecoratedCollection) Aggregate(ctx context.Context, pipeline any, result any) (err error)
- func (c *DecoratedCollection) Count(ctx context.Context) (result int64, err error)
- func (c *DecoratedCollection) CreateIndex(ctx context.Context, key bson.D, op *options.IndexOptions) (res string, err error)
- func (c *DecoratedCollection) Delete(ctx context.Context) (count int64, err error)
- func (c *DecoratedCollection) Drop(ctx context.Context) (err error)
- func (c *DecoratedCollection) DropIndex(ctx context.Context, name string, opts *options.DropIndexesOptions) (err error)
- func (c *DecoratedCollection) Fields(fields bson.M) *DecoratedCollection
- func (c *DecoratedCollection) FindMany(ctx context.Context, documents any) (err error)
- func (c *DecoratedCollection) FindOne(ctx context.Context, document any) (err error)
- func (c *DecoratedCollection) InsertMany(ctx context.Context, documents any) (val *mongo.InsertManyResult, err error)
- func (c *DecoratedCollection) InsertOne(ctx context.Context, document any) (val *mongo.InsertOneResult, err error)
- func (c *DecoratedCollection) Limit(n int64) *DecoratedCollection
- func (c *DecoratedCollection) ListIndexes(ctx context.Context, opts *options.ListIndexesOptions) (val []string, err error)
- func (c *DecoratedCollection) Skip(n int64) *DecoratedCollection
- func (c *DecoratedCollection) Sort(sorts bson.D) *DecoratedCollection
- func (c *DecoratedCollection) UpdateMany(ctx context.Context, document any) (val *mongo.UpdateResult, err error)
- func (c *DecoratedCollection) UpdateOne(ctx context.Context, document any) (val *mongo.UpdateResult, err error)
- func (c *DecoratedCollection) UpdateOneRaw(ctx context.Context, document any, opt ...*options.UpdateOptions) (val *mongo.UpdateResult, err error)
- func (c *DecoratedCollection) UpdateOrInsert(ctx context.Context, documents []any) (val *mongo.UpdateResult, err error)
- func (c *DecoratedCollection) Where(m bson.D) *DecoratedCollection
- type Model
- type MongoDB
- func (cs *MongoDB) Close() error
- func (m *MongoDB) MustNewCollection(collection string) *DecoratedCollection
- func (m *MongoDB) MustNewModel(collection string) *Model
- func (m *MongoDB) NewCollection(collection string) (*DecoratedCollection, error)
- func (m *MongoDB) NewModel(collection string) (*Model, error)
- func (m *MongoDB) Ping() error
- func (m *MongoDB) SetEnableMetric(disableMetric bool) *MongoDB
- func (m *MongoDB) SetEnableTrace(disableTrace bool) *MongoDB
- type Option
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func BeforeCreate ¶
BeforeCreate 在写入前将输入转换为 BSON 文档:指针自动解引用,数组/切片递归逐项转换, 结构体按 bson 标签转为 bson.M,并为 ObjectID 类型或空 Id 字段补充 _id。 输入类型与转换假设不匹配时会触发类型断言 panic,调用方须传入结构体、切片或 bson.M。
func BeforeUpdate ¶
BeforeUpdate 在更新前将输入转换为 BSON 文档:指针解引用、数组递归转换,结构体按 bson 标签提取字段;标记 over 标签的字段被跳过,不进入更新内容。
func SetSlowThreshold ¶ added in v3.4.4
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
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
func (c *DecoratedCollection) Limit(n int64) *DecoratedCollection
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
func (c *DecoratedCollection) Skip(n int64) *DecoratedCollection
Skip 设置跳过的记录条数,返回集合自身以便链式调用。
func (*DecoratedCollection) Sort ¶ added in v3.4.4
func (c *DecoratedCollection) Sort(sorts bson.D) *DecoratedCollection
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
func (c *DecoratedCollection) Where(m bson.D) *DecoratedCollection
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
NewMongoDBClient 依据 URI 创建并缓存 MongoDB 客户端。
同一 URI 复用已建立的连接;URI 缺少数据库名、URI 解析失败、连接或 Ping 失败时, 记录日志并 panic。建立连接的上下文超时为 5 秒,默认操作超时 3 秒,可由传入的 Option 覆盖。
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
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
NewModel 校验连通性后为指定集合创建 Model,继承当前客户端的指标与追踪开关; Ping 失败时返回错误。collection 为集合名称,调用方须保证非空。
func (*MongoDB) SetEnableMetric ¶ added in v3.8.21
SetEnableMetric 设置指标采集开关并返回客户端自身,便于链式调用。
func (*MongoDB) SetEnableTrace ¶ added in v3.8.21
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
WithMaxConnIdleTime 设置连接池中连接的最大空闲时长。
func WithMaxPoolSize ¶ added in v3.4.4
WithMaxPoolSize 设置连接池最大连接数。
func WithMinPoolSize ¶ added in v3.4.4
WithMinPoolSize 设置连接池最小保持的连接数。
func WithTimeout ¶ added in v3.4.4
WithTimeout 设置客户端单次操作超时时间。