跳转到内容
PLUMEGO Go 服务显式 wiring 工具包，stdlib 优先。
中文

模块总览

模块总览

Section titled “模块总览”

Plumego 把长期稳定的公开包放在仓库根部，把可选能力与快速演进功能放在 x/*。这个拆分是有意的：它让稳定表面保持收敛，也让归属更容易判断，并避免默认学习路径被扩展能力重新定义。

成熟度速查

Section titled “成熟度速查”
层级数量采用建议
稳定（GA）9 个包生产可用。v1 兼容性承诺适用。
Beta7 个家族API 在连续次版本 release ref 之间冻结。可在生产中安全使用，升级前查看发布说明。
实验性7 个主入口家族API 可能在无缓冲期的情况下变更。在稳定服务路径中使用前，建议用 app-local 接口包装依赖。

完整成熟度证据、扩展单包看板与发布矩阵：状态总览 →

同步模块清单

Section titled “同步模块清单”

从 `specs/repo.yaml` 同步

稳定根 9

  • contract
  • core
  • router
  • middleware
  • security
  • store
  • health
  • log
  • metrics

从 `specs/task-routing.yaml` 同步

主扩展家族 14

  • x/tenant
  • x/fileapi
  • x/messaging
  • x/gateway
  • x/rest
  • x/websocket
  • x/frontend
  • x/observability
  • x/openapi
  • x/resilience
  • x/rpc
  • x/data
  • x/ai
  • x/validate

这些列表由构建前同步脚本生成，而不是手工重复维护。

仓库层级地图

Section titled “仓库层级地图”
1

默认服务路径

内核、路由、合约、中间件

2

可运行形态

启动、路由接入、handler

3

能力工作

可选家族，先从主入口开始

4

控制面

意图、机器规则、执行范围

稳定根
  core router contract middleware security store health log metrics


x/* families
  可选能力和协议表面


控制面
  reference docs specs tasks module.yaml

分类矩阵

Section titled “分类矩阵”
工作类型从哪里开始原因
内核、生命周期、路由结构、传输合约 或稳定中间件稳定根这是每个服务都应该理解的默认路径
能力、协议、租户、网关、数据拓扑或观测适配器工作x/* 家族可选能力工作不应该扩张稳定根
应用本地启动和服务接线参考应用规范服务形态不属于运行时包归属问题
归属规则、routing taxonomy、import boundary 或执行范围仓库边界这些属于 docs/specs/tasks 控制面问题

扩展入口规则

Section titled “扩展入口规则”
如果工作围绕先从这里开始什么时候再下钻
messaging、queue、pubsub、scheduler 或 webhookx/messaging任务已经明确属于 scheduler、webhook、pubsub 或 mq
边缘传输、反向代理或负载均衡x/gateway任务已经明确属于 discovery 或 ipc
可复用 resource-interface 工作x/rest已进入具体 CRUD/resource controller 问题
更高层观测适配器x/observability任务已经明确属于 ops 或 devtools
数据拓扑、sharding、durable KV 或读写分离x/data任务已经明确属于 cache

接下来应该打开哪些模块 primer

Section titled “接下来应该打开哪些模块 primer”

当顶层问题已经明确后，就不要停留在总览页，而应该继续进入对应模块 primer。

稳定根 — ga

Section titled “稳定根 — ga”

这些模块承载 v1 稳定根兼容性承诺，是推荐的第一个生产评估范围。

如果问题主要围绕下一步打开的 primer为什么应该先读这里
应用构造、lifecycle 与 路由挂载Core Primer · 稳定core 拥有 HTTP 应用内核与规范生命周期路径
HTTP 传输包装层、request ID、追踪、限流与访问日志Middleware Primer · 稳定middleware 负责保持顺序敏感的 HTTP 行为窄且显式
路由匹配、路径参数、route group 与反向路由Router Primer · 稳定router 拥有基于 trie 的路由匹配表面
请求/响应合约、错误模型、上下文助手与追踪元数据Contract Primer · 稳定contract 定义每个 handler 都使用的规范错误与响应形态
认证基础元语、JWT、密码助手、security header 与输入验证Security Primer · 稳定security 提供 fail-closed 认证与验证基础元语
存储合约、文件抽象、cache primitive 与 幂等合约Store Primer · 稳定store 定义了进入拓扑型数据问题之前的稳定持久化层
存活和就绪模型类型与健康聚合Health Primer · 稳定health 拥有组件检查器合约与就绪状态模型
基础日志合约与结构化 logger 接线Log Primer · 稳定log 定义扩展包与稳定根共享的日志表面
基础指标合约与 collector 注册Metrics Primer · 稳定metrics 定义指标表面，不拥有导出器或适配器行为

扩展家族

Section titled “扩展家族”

先从主家族入口进入，不要直接下钻到下级包。以成熟度层级作为采用信号。

Beta

Section titled “Beta”

API 在连续次版本 release ref 之间保持冻结。可在生产中安全使用；升级前查看发布说明。

如果问题主要围绕下一步打开的 primer晋升版本下级包
可复用 CRUD 传输与资源路由标准化x/rest Primerv0.2.0—
实时 WebSocket 连接生命周期、hub 管理或认证x/websocket Primerv0.2.0—
反向代理、gateway 路由、负载均衡或边缘传输x/gateway Primerv0.2.0x/gateway/discovery · x/gateway/ipc（实验性）
Prometheus 导出器、OTel 接线、记录缓冲或 DB 分析x/observability Primerv0.2.0x/observability/ops · x/observability/devtools（实验性）
多租户解析、策略、配额、限流或 sessionx/tenant Primerv1.1.0resolve、policy、quota、ratelimit、session、store
静态资源服务、嵌入式 FS 或 SPA fallback 路由x/frontend Primerv1.1.0—
应用侧 queue、pubsub、scheduler 或 webhook 编排x/messaging Primerv1.1.0（应用层）scheduler · webhook · pubsub · mq（下级原语仍为实验性）

实验性家族中的 Beta 表面

Section titled “实验性家族中的 Beta 表面”

父家族根仍为实验性，但这些子包在 v1.1.0 时获得了 release 背书的 API 稳定性。

Beta 表面父家族 primer说明
x/ai/provider · x/ai/session · x/ai/streaming · x/ai/toolx/ai Primer用这些子包做稳定的 AI 工作；其余子包和根家族仍为实验性
x/data/file · x/data/idempotencyx/data Primer用这些子包做稳定的文件存储和幂等性工作；拓扑表面和 x/data/cache 仍为实验性

实验性

Section titled “实验性”

API 兼容性未冻结。采用前请先评估；在稳定服务路径中使用时建议用 app-local 接口封装依赖。

如果问题主要围绕下一步打开的 primer下级包
AI provider 适配器、session、流式传输或 tool 调用x/ai Primerprovider、session、streaming、tool 为 Beta 表面（见上方）；orchestration、semanticcache、distributed、resilience 仍为实验性
读写分离、分片、持久化 KV 或幂等性拓扑x/data Primerx/data/cache；file 和 idempotency 为 Beta 表面（见上方）
文件上传、下载或流式传输的 HTTP 传输层x/fileapi Primer—
跨扩展共享的熔断器、重试封装或弹性适配器x/resilience Primer—
gRPC + HTTP 服务托管或出站 RPC 客户端池x/rpc Primer—
从已注册路由生成 OpenAPI 3.1 文档x/openapi Primer—
显式 JSON 绑定与调用方自有请求验证x/validate Primer—

这页希望你避免什么

Section titled “这页希望你避免什么”

当前仓库会主动避免把 ai、tenant、rest、pubsub、frontend、utils、validator 这类宽泛或含糊的名字继续长成顶层根目录。只要一个名字听起来更像 feature catalog 或模糊大桶，它大概率就不是正确起点。

下一步阅读

Section titled “下一步阅读”