matex 文档

matex 是一套约定：一个部署单元长什么样、基础设施怎么进来、错误怎么表达、日志怎么带 trace id。文档分四段——先理解它为什么这样设计，再跑起来，然后按能力读，最后查参考。

介绍 定位与取舍：为什么不引 ORM、不引路由库、不做服务发现，以及"配了才建"到底意味着什么。 5 分钟 快速开始 三条命令：零依赖起步、带 SQLite 库起步、带真依赖起步。每条都能立刻 curl 验证。 3 分钟 架构总览 verticle.Run 的启动序列、分层依赖方向、以及由 depguard 强制的一致性守卫。 10 分钟

核心概念

写业务代码前该知道的五件事。

服务与生命周期 verticle.Service / Env / 后台任务 / 优雅退出 / 配置热更。 配置 tag 语义、${VAR} 展开、未知键告警、热更回调。 HTTP 与路由 handler 约定、响应封套、中间件两个槽、默认安全头与 CORS。 错误模型 errs.Kind → HTTP 状态、业务 code、Wrap 不泄露内部细节。 可观测性 结构化日志、trace id、指标、跨进程链路追踪。

数据与集成

数据库 三驱动统一入口、占位符重写、泛型扫描、事务、Querier、迁移。 缓存模式 cache-aside、并发 miss 合并（防击穿）、TTL 抖动（防雪崩）。 Kafka 消息 同步/异步生产、at-least-once 消费、死信队列与提交顺序。 gRPC 与 rpcx 注册接口、内置健康服务、reflection、追踪自动传播。

生产治理

稳定性防护 限流、幂等、熔断（两种模型）、退避重试，以及"防护故障时放行"。 认证与安全 HMAC/JWKS 验签、分级授权、默认安全响应头与 CORS 策略。 开关与审计 功能开关的四层优先级；审计事件的字段与可插拔 sink。 定时任务 固定周期 / cron 表达式 / 一次性，多副本下的 redis 选主。 LLM 客户端 四种协议互转、流式事件、可选重试、Jev 决策问答。

参考

离线测试 dbtest / redistest / kfake / 进程内 gRPC·rpcx：不装 Docker 也能跑全量。 pkg/core 速查 26 个包的一页表：用途、是否 opt-in、关键 API。 目录与约定 每个目录的职责，以及四条被工具强制的约定。 命令与部署 Makefile 目标、CI 门禁、Docker 镜像与配置挂载。 AI Skills 15 个 skill 的用途与触发语，以及与 AGENTS.md 的关系。 示例索引 20 个可离线运行的示例，每个都有测试。

另一条路：直接读代码

文档是导览，事实源始终是代码。examples/ 下每个能力都有可运行示例， docs/design.md 记录了完整的设计取舍， AGENTS.md 是给 AI 与新人看的规范入口。