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

x/* 家族

x/* 家族

Section titled “x/* 家族”

x/* 这一层的存在，是为了让可选能力和快速演进功能继续前进，而不重定义稳定根的默认学习路径。它们不是随手塞代码的溢出目录，而是那些真实存在、面向应用、确实有用，但又过于能力特定、不能进入默认窄路径的工作归属地。

同步扩展事实

Section titled “同步扩展事实”

从 `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

从 `specs/repo.yaml` 同步

全部扩展路径

默认归类意图: Change product capability, business feature, protocol adaptation, or extension behavior.

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

主入口家族和全部扩展路径被分开展示，避免把辅助路径误认成默认入口。

Beta 扩展家族

Section titled “Beta 扩展家族”

以下家族已达到 beta 状态：API 在 minor release ref 间冻结，有两个连续 release ref、导出 API 快照和负责人签字支撑。

家族状态晋升版本推荐入口
x/gatewaybetav0.2.0代理、重写、负载均衡、edge transport
x/observabilitybetav0.2.0exporter、tracer、collector、适配器接线
x/restbetav0.2.0资源控制器与 CRUD 路由规范
x/websocketbetav0.2.0WebSocket hub 与显式路由注册
x/tenantbetav1.1.0解析、策略、配额、限流、session
x/frontendbetav1.1.0静态与嵌入式资产服务
x/messagingbetav1.1.0（应用侧服务）应用侧 queue、pubsub、scheduler、webhook 服务

包含实验性家族内 beta surface 的完整成熟度看板，请参阅扩展成熟度。

什么时候应该从这里开始

Section titled “什么时候应该从这里开始”

当工作主要围绕可复用能力行为，而不是最小规范服务形态时，就应该从 x/* 家族开始。

通常这意味着任务带有下面这些特征之一：

  • 协议适配或 edge 行为
  • tenant、gateway、messaging、data-topology 或 observability 策略
  • 应保持可选属性的 app-facing 可复用能力表面
  • 一旦放进稳定根，就会迫使稳定层学习产品语义或家族语义的行为

如果任务仍然主要围绕默认启动路径、显式生命周期接线，或每个服务都应理解的 传输基础元语，那你大概率还没到该从 x/* 开始的时候。

一个更实用的归属判断测试

Section titled “一个更实用的归属判断测试”

在你选定扩展家族之前，先问自己三个问题。

  1. 这项改动是否明显属于某个能力家族，而不是最小可运行服务路径？
  2. 如果把它放进稳定根，是否会迫使稳定层学习家族策略、provider 选择或拓扑决策？
  3. 当前仓库里是否已经存在一个比窄子包更诚实的主家族入口？

只要答案是肯定的，x/* 往往就是更合理的起点。

当前仓库里的具体扩展家族案例

Section titled “当前仓库里的具体扩展家族案例”

当前仓库已经给出了几条很清楚的家族级入口规则。

扩展家族适合从这里开始的工作如果真正问题是这些，就不该从这里开始
x/rest可复用 CRUD 传输行为、query parsing、pagination rule 与 repository-backed resource wiring服务启动、gateway topology、business repository 归属或领域验证
x/messagingapp-facing 的 queue、pubsub、scheduler、webhook 编排，以及家族级消息入口最小可运行服务路径、稳定抽象，或一个已经明确只属于 x/messaging/mq / x/messaging/pubsub 的窄任务
x/observabilityexporter wiring、telemetry 适配器、buffered metrics inspection、rolling metrics helper 与更高层 diagnostics integrationrequest ID、tracing hook、access logging 这类传输层请求中间件原语
x/rpcRPC 服务器生命周期辅助工具、出站连接池，以及将 HTTP-over-RPC 处理器与标准路由并排转码后端服务发现（使用 x/gateway/discovery），或将具体 gRPC 运行时导入 x/rpc 本身
x/openapi从 router.RouteInfo 值和操作提示生成 OpenAPI 3.1 文档结构，无需外部依赖基于 handler 反射的模式推断、运行时 Swagger UI，或 YAML 解析
x/validate处理器中显式的 BindJSON/Bind 调用点，解码 JSON 并返回结构化 contract.APIError 响应中间件层预验证、基于标签的结构体验证框架，或全局验证器实例

这些例子的重要性在于：它们说明 x/* 不是单纯把代码从稳定根里挪走的地方。每个家族都应该成为一个可发现、可解释的主入口，并带着清晰 归属。

下一步打开正确的扩展 primer

Section titled “下一步打开正确的扩展 primer”

一旦你已经确认工作属于扩展家族，就不要继续停留在抽象层，而应跳到最诚实的家族入口 primer。

如果工作主要触及下一步打开的 primer为什么这里是更合适的下一跳
可复用 CRUD controller 行为、共享分页规则与资源路由标准化x/rest Primer它会把家族级规则继续落到应用本地接线、仓储代码与领域验证的具体拆分
app-facing queue、pubsub、scheduler 与 webhook 编排x/messaging Primer它会继续说明什么时候应该停留在家族入口，什么时候才适合下钻更窄 sibling
RPC 服务器生命周期、出站连接池或 HTTP-over-RPC 网关x/rpc Primer它说明哪些表面是调用方自有的，x/rpc 提供了哪些生命周期辅助工具
从已注册路由生成 OpenAPI 3.1 文档x/openapi Primer它解释路由驱动的生成模型，以及 CLI 集成的边界在哪里
处理器中的显式 JSON 绑定和调用方自有验证x/validate Primer它阐明何时使用 BindJSON vs Bind，错误如何映射到 contract.APIError，以及为什么验证要留在处理器中
那些看起来很像扩展，但其实仍可能属于稳定表面的改动稳定根当问题本质上仍然是默认路径归属时，这里才是正确回退页

更具体的路由判断例子

Section titled “更具体的路由判断例子”

几个来自当前仓库的例子，会让分流方式更落地。

  • 当任务是“标准化 CRUD 或资源接口形态”时，从 x/rest 开始。显式路由绑定 仍保留在 应用本地接线，repository 归属仍归 仓储层，领域验证 也不应塞进 x/rest。
  • 当任务是应用侧的消息编排时，从 x/messaging 开始。只有在任务已经明确窄化后，才继续下钻到 x/messaging/mq、x/messaging/pubsub、x/messaging/scheduler 或 x/messaging/webhook。
  • 当任务是 export wiring 或更高层的 telemetry integration 时，从 x/observability 开始；传输层请求观测原语仍保留在稳定 middleware/*。
  • 当问题是 proxy 或 边缘传输 行为，而不是可复用资源控制器行为时，应从 x/gateway 开始，而不是从 x/rest 开始。

需要避免的常见误判

Section titled “需要避免的常见误判”

当前仓库会主动阻止几种常见错误。

  • 不要把 x/* 当作隐藏不清晰归属的通用借口
  • 不要让扩展家族去重写规范reference path
  • 既然已有主家族入口，就不要一上来从从属包开始
  • 也不要因为实现看起来更“高级”，就把传输合约、lifecycle归属或最小启动路径 从稳定层随意迁走

x/* 的目的不是追求新奇，而是让能力特定工作在不扩张默认契约的前提下，保持显式、可发现、可维护。

这页怎样与稳定根配套阅读

Section titled “这页怎样与稳定根配套阅读”

一个好用的判断方法，是先看你试图回答的第一个问题是什么。

  • 如果问题是“规范 服务应该怎样启动、怎样路由请求”，就继续停留在 稳定根 和 参考应用。
  • 如果问题是“这段可选或快速演进行为该由哪个能力家族负责”，就从这里开始。

这才是默认路径归属与扩展家族归属之间真正的边界。

下一步阅读

Section titled “下一步阅读”