组件手册

本章按职责介绍 Maltose 的公共组件。应用代码通常通过 frame/m 获取配置驱动的共享实例；库代码和测试可以直接使用组件构造函数。

请求与通信

组件	解决的问题	从这里开始
mhttp	HTTP Server、路由、参数绑定和中间件	Web Server
mclient	HTTP Client、中间件、限流和重试	HTTP 客户端

Web 相关主题：

• 路由与 Controller 绑定
• 中间件
• 标准响应与 HTTP 状态码

配置与基础设施

组件	解决的问题	实例策略
mcfg	文件、远程 Adapter、结构体映射和加载 Hook	m.Config() 或独立 Config
mlog	结构化日志、文件轮转、上下文和链路字段	m.Log() 或独立 Logger
mdb	GORM、连接池、事务、读写分离和慢 SQL	m.DB() 或独立 DB
mredis	Redis 命令、具名实例、日志与 Trace	m.Redis() 或独立 Redis
mcache	内存/Redis 缓存、过期和防击穿	包级默认缓存或独立 Cache
msync	SingleFlight、同键串行、并发限制和对象池	进程内独立工具

可观测性

Maltose 基于 OpenTelemetry 提供 Trace 和 Metric 封装。应用可以使用统一入口初始化两个信号，也可以分别控制底层 Provider。

• 可观测性背景
• 统一初始化 Trace 与 Metric
• 链路追踪 mtrace
• TraceID 注入与获取
• 指标监控 mmetric

如何选择入口

• 构建业务应用：优先使用 m.Server()、m.Config()、m.Log()、m.DB()、m.Redis()。
• 同进程多应用或隔离测试：使用 m.NewScope(config) 获取独立的 Server、DB、Redis 和 Logger 实例。
• 编写可复用库：优先显式接收依赖或配置，避免隐式读取应用全局实例。
• 编写单元测试：为业务依赖定义最小接口并注入 mock。
• 管理缓存：直接使用 mcache，框架没有在 m 门面中规定全局 Cache 实例。

组件装配方式的完整解释见设计哲学。