Practical Paths

示例

Plumego 当前真正能站得住的示例路径：从 canonical 可运行服务，到围绕它展开的引导式示例。

一个 canonical 服务，加五条聚焦的 recipe 路径。

示例路径包含一个可运行的基线，以及五条引导式 recipe。先从 reference/standard-service 看默认服务形态，再按需选一条 recipe 回答具体问题——请求路径、模块归属、成熟度确认或仓库分层——然后再向更深的方向展开。

runnable

只有一个 canonical 可运行示例

reference/standard-service 是 Plumego 期望用户最先运行、也最先拿来对照新服务的示例。

guided

引导式示例解释它周围的仓库结构

请求路径、模块边界和发布姿态这些页面，本质上是教你如何读仓库，而不是再做一堆迷你应用。

honest scope

站点只推广仓库真正能支持的示例

这页会比传统框架 showcase 更窄，因为它优先强化 canonical path，而不是分散注意力。

先理解层级，再决定看哪一页

Plumego 的示例是刻意分层的：只有一个 canonical 可运行服务，其余是围绕它展开的引导式 recipes，用来解释如何读仓库，而不是假装每个问题都需要一套单独 demo。

canonical example

reference/standard-service

主示例是那个你可以 clone、运行、与自己仓库对照，并在采用决策仍未定型时持续回来的服务骨架。

bootstrap 和 server 构造保持可见
internal/app 拥有应用本地 wiring
在进入更深的 handler 或包家族之前，route 注册仍然清晰可读

reference/standard-service/

reference/standard-service/ ├── main.go ← bootstrap 与 server 启动 ├── internal/ │ ├── app/ │ │ ├── app.go ← 依赖 wiring │ │ └── routes.go ← route 注册 │ └── config/ │ └── config.go ← 类型化环境配置 └── go.mod

terminal

$ go run ./reference/standard-service # Server started at :8080

打开参考应用说明

guided recipes

Recipes 一次只回答一个仓库问题

它们不是并行迷你产品，而是帮助你理解请求路径、ownership、成熟度信号与仓库结构的可复用阅读模式。

在打开无关包家族之前，先跑通 reference app。
用 recipe 回答一个明确问题，而不是把它们当成并行的产品 demo。
一旦知道是哪条边界或能力拥有这项改动，就回到文档主路径继续。

现在就能跑的示例

如果你只准备跑一个示例，并把它当成自己服务的对照物，就先用 reference app。

canonical

reference/standard-service

默认应用布局，覆盖 bootstrap、route wiring 和 transport-only handler。

最适合作为新服务起点
展示默认目录结构
可以直接映射到文档与验证路径

打开参考应用说明

围绕采用问题组织的 recipe 轨道

Recipes 比 canonical example 更小，也比 docs overview 更具体。每条轨道都应该尽快回答一个明确问题，然后把读者重新送回默认路径，带着更清晰的分类继续往下读。

recipe 01

请求路径 recipe

当你需要不靠猜测地追一条 HTTP 请求，从 route 注册一直看到写回路径在哪里结束时，用这条路径。

先看 route 注册，再看 handlers
确认 public path 上的 middleware 顺序
在 transport ownership 结束处停下来

internal/app/routes.go

r := router.New()

r.Use(middleware.RequestID())
r.Use(middleware.Logger(a.log))

r.Get("/api/items",  a.items.List)
r.Get("/api/orders", a.orders.List)

追踪一条请求

recipe 02

模块归属 recipe

当真正的问题是这项工作应该落在稳定根、应用本地 wiring 还是扩展模块时，用这条路径。

在翻包前先判断归属
保护稳定根的兼容性承诺
把可选能力继续向外分层

import path check

// stable root — 稳定根候选，可先进入生产评估
import "github.com/spcent/plumego/router"
import "github.com/spcent/plumego/middleware"

// extension family — Experimental，采用前先评估
import "github.com/spcent/plumego/x/tenant"
import "github.com/spcent/plumego/x/ai"

判断改动归属

recipe 03

参考应用 recipe

当你想先确认 canonical 服务形态，并把自己的 bootstrap 与 route 布局拿来对照时，用这条路径。

先从 internal/app 的 ownership 看起
在增加抽象之前先对照目录形态
把 reference app 当成可复用基线

internal/app/app.go

type App struct {
    log    log.Logger
    db     *sql.DB
    items  *items.Handler
    orders *orders.Handler
}

func New(cfg *config.Config, deps AppDeps) *App {
    return &App{ /* explicit wiring */ }
}

阅读参考应用

recipe 04

成熟度检查 recipe

当采用决策取决于兼容性信号，而不是”仓库里有这个包所以默认可用”时，用这条路径。

扩展范围前先读稳定性承诺
把模块成熟度和路线图野心分开
让证据先于假设

maturity boundary

// 稳定根候选 — 长期 API 目标
core, router, contract, middleware
security, store, health, log, metrics

// Supported reference — 对齐 canonical path
reference/standard-service, cmd/plumego

// Experimental — 有价值，但 API 可能变化
x/ai, x/tenant, x/gateway, x/websocket

检查模块成熟度

recipe 05

仓库结构 recipe

当一个改动同时涉及文档、生成事实和实现代码，你需要先判断每一层分别拥有哪类职责时，用这条路径。

用 docs 承担学习路径
用 specs 与 generated facts 提供事实来源
保持 app-local 代码与扩展家族分离

repo layer map

docs/    ← 面向人的学习路径
specs/   ← 机器可读规则与归属
tasks/   ← 可执行工作卡
x/       ← 能力扩展家族

// app-local: 只属于你的服务仓库
internal/app/app.go
internal/app/routes.go

查看架构

引导式示例

这些示例不是额外的可运行应用，而是发布级 walkthrough，用来教你理解这套仓库的默认阅读路径和 ownership 规则。

request path

从 route 到写回路径读一遍请求

当你需要追踪 HTTP 工作从哪里开始、transport 责任在哪里结束时，就先看 request-flow 页面。

打开 Request Flow

module fit

在翻包前先判断改动归属

用 modules overview、stable roots 和 x/* family 页面先决定工作应该落在稳定表面还是扩展家族。

打开模块总览

maturity

先判断成熟度，再决定是否采用

用 release posture 和发布页保持兼容性假设显式，而不是默认它已经稳定。

打开发布姿态

进阶参考应用

这些参考应用演示了特定能力的服务形态，每一个都在 reference/standard-service 的基础上加入一个 x/* 家族。先读 canonical 参考应用，再根据你需要评估的具体能力选择进入哪一个。

ai service

reference/with-ai

带多 provider 抽象、streaming 响应和 tool 路由的 AI 服务。在稳定 HTTP 内核基础上加入 x/ai，不改变 canonical route 结构。

x/ai — 实验性

provider 抽象与 HTTP transport 分离
streaming 响应通过标准 net/http handler 处理
AI API 形态演进时，稳定根保持兼容

打开 x/ai 模块手册查看成熟度姿态

multi-tenant saas

reference/with-tenant

带 per-tenant 路由、配额执行和 JWT 策略评估的多租户服务。x/tenant 在 HTTP 内核之外承接租户层，稳定根不受租户逻辑演进影响。

x/tenant — Beta

租户身份来自 JWT 或 header，在传输层评估
per-tenant 配额与策略与 route wiring 分开
稳定根承担 HTTP 基线，x/tenant 承担租户层

打开 x/tenant 模块手册查看成熟度姿态

所有能力参考应用

每个参考应用都在 standard-service 的基础上加入一个 x/* 家族。先读 canonical 参考应用，再按你需要评估的能力选择进入。

参考应用 能力说明 成熟度

reference/with-ai x/ai 带 streaming 响应与 tool 路由的多 provider AI 服务实验性

reference/with-tenant x/tenant Per-tenant 路由、配额执行与 JWT 策略评估 Beta

reference/with-tenant-admin x/tenant 多租户管理平面：生命周期、配额管理与用量记录 Beta

reference/with-gateway x/gateway 边缘代理、负载均衡与路由重写 Beta

reference/with-rest x/rest CRUD 资源控制器与 REST 规范 Beta

reference/with-websocket x/websocket WebSocket 实时传输 Beta

reference/with-messaging x/messaging 异步消息发布与订阅接线 Beta

reference/with-events x/messaging 进程内 pubsub、幂等消费、延迟重试与 webhook 投递实验性

reference/with-rpc x/rpc 通过 x/rpc/server 托管 gRPC 服务并经 x/rpc/gateway 挂载 HTTP 端点实验性

reference/with-webhook x/messaging/webhook 带签名校验的 Webhook 接收器实验性

reference/with-observability x/observability Prometheus 指标与 OpenTelemetry 分布式追踪 Beta

reference/with-ops x/observability/ops 受保护的管理与运维表面实验性

reference/with-frontend x/frontend 静态与内嵌 SPA 服务，支持缓存头、SPA fallback 与 API 同挂载 Beta

reference/production-service stable roots 带完整生命周期、TLS 和测试的生产级加固变体受支持参考

生产规模参考：reference/workerfleet

reference/workerfleet 是一个完整深度的生产参考应用——分布式 worker 机队管理，包含领域模型、MongoDB 存储、Kubernetes Pod 发现、Prometheus 指标、告警引擎（带去重与阈值评估）以及飞书/webhook 通知。适合用来评估 Plumego 在超出教程级别时的能力深度。

生产参考 — 完整深度示例

reference/workerfleet

领域驱动设计：task、worker、pod、alert 和 event 模型
MongoDB 存储，含索引管理和集成测试
Kubernetes watch-based pod 同步与发现
Prometheus 指标，含自定义 collector 和 Grafana 看板
告警引擎，含去重、阈值规则和通知器（飞书、webhook）

阅读 workerfleet README

扩展前先确认模块成熟度

理解默认路径之后，在扩大采用范围前确认你关心的模块是否已经稳定。

项目状态与 v1 清单 → 详细稳定性分级 →

示例

先看参考服务，再进入聚焦 recipe

一个 canonical 服务，加五条聚焦的 recipe 路径。

只有一个 canonical 可运行示例

引导式示例解释它周围的仓库结构

站点只推广仓库真正能支持的示例

先理解层级，再决定看哪一页

reference/standard-service

Recipes 一次只回答一个仓库问题

现在就能跑的示例

reference/standard-service

围绕采用问题组织的 recipe 轨道

请求路径 recipe

模块归属 recipe

参考应用 recipe

成熟度检查 recipe

仓库结构 recipe

推荐阅读顺序

先跑通 canonical 服务

再用 recipe 回答一个具体问题

随后回到文档主路径

扩展之前先检查模块成熟度

引导式示例

从 route 到写回路径读一遍请求

在翻包前先判断改动归属

先判断成熟度，再决定是否采用

进阶参考应用

reference/with-ai

reference/with-tenant

所有能力参考应用

生产规模参考：reference/workerfleet

reference/workerfleet

扩展前先确认模块成熟度