Plumego Roadmap

By Birdor Engineering

状态说明

Plumego 的定位：完全基于 Go 标准库、零外部依赖、强调简单优雅与可组合。
本文为一份“可执行”的路线图提案，面向：

  • 核心贡献者：明确优先级、版本节奏、退出/回滚策略
  • 使用者：明确当前适用边界、未来能力方向、升级成本预期
  • 生态建设：示例工程、文档、规范与工具链的逐步完善

路线图原则（Birdor 风格）

  1. 稳定优先：先把现有 API 固定，再扩展能力；避免频繁破坏性变更。
  2. 最小抽象：只抽象“不可避免的变化点”（store、auth、ws、codec、logger）。
  3. 显式组合：中间件、组件、模块装配应尽量显式，便于审计与调试。
  4. 性能与观测内建：默认提供 request-id/trace、结构化日志、recover。
  5. 示例驱动：每个核心能力必须配套“真实业务示例”（例如 user center）。

版本策略

  • v0.x：快速迭代期，允许小范围破坏性调整（但必须提供迁移说明）。
  • v1.0：API 稳定承诺（SemVer），破坏性变更进入 v2.0。
  • 发布节奏：每 6–10 周一个 minor，每 2–4 周一个 patch（视缺陷密度）。

Roadmap 总览（2026）

下面按季度给出里程碑；后期将映射到 GitHub Milestones / Projects。

2026 Q1 — 稳定化与“可观测默认值”

目标：把 Plumego 从“能用”推进到“稳定、可排障、可维护”。

  • R1. Router 稳定化

    • 路由匹配与参数提取 API 固化（Param()/PathParam() 等命名定稿）
    • 统一 404/405 行为与方法回退策略
    • 路由树性能基准 + 回归测试（含并发与极端 path case）

  • R2. Middleware 规范化

    • 标准 middleware 链模型（顺序、短路、错误传播）
    • 内置中间件：Recovery / RequestID / AccessLog / CORS / Timeout / RateLimit(基础版)
    • 中间件可测试性：提供 httptest helper（构造 App、注入 ctx、断言 response）

  • R3. 统一响应与错误模型（推荐实践）

    • 官方文档给出：统一 Envelope、错误码规范、错误分类（4xx vs 5xx）
    • errors 子包（可选）提供 AppError 与错误映射建议

交付物

  • docs/best-practices/*
  • examples/user-center（User/Auth/Project）
  • benchmarks/router_*
  • CHANGELOG.md

2026 Q2 — WebSocket / PubSub / 实时能力成型

目标：提供“够用、可靠、可组合”的实时通信基座（而不是“大而全 IM 框架”）。

  • R4. WebSocket 基础设施

    • 标准库 x/net/websocket 不引入外部依赖的前提下：提供稳定的 WS 抽象层（连接管理、读写循环、关闭语义）
    • Backpressure 策略（写队列、丢弃策略、慢连接处理）
    • 心跳与超时（ping/pong、idle timeout）
    • 可插拔 codec（text/json/binary）

  • R5. 进程内 Pub-Sub

    • topic / fanout / backpressure
    • 与 WS 的桥接示例（房间广播、在线人数）
    • 可替换接口：为未来接 NATS/Redis/Kafka 预留 adapter 形态（不引入依赖）

  • R6. SSE（可选）

    • 如果定位需要“更轻量实时推送”，提供 SSE helper（完全基于 net/http）

交付物

  • examples/ws-chat（房间/广播）
  • examples/pubsub（topic + worker）
  • 压测脚本与指标建议（QPS、连接数、99p 延迟）

2026 Q3 — Auth / Security / 多租户扩展点

目标：把“安全默认值”补齐，让用户中心、后台系统、API 平台都能用。

  • R7. Auth 能力（可替换）

    • 官方推荐的 auth boundary：Authenticator / TokenService / SessionStore
    • JWT：作为 可选模块，提供“兼容 JWT 结构的最小实现”
    • RefreshToken / Token Revocation（黑名单、签名版本强制下线）
    • RBAC（最小可用）：policy 接口 + middleware 示例

  • R8. 安全加固

    • 统一安全 header（HSTS、X-Content-Type-Options、CSP 建议）
    • CSRF（可选，面向 cookie session）
    • 输入大小限制 / body limit / multipart 限制
    • 路由参数与 query 的安全建议（注入、防止 panic）

交付物

  • docs/security/*
  • examples/auth-rbac
  • “生产部署检查清单”（反向代理、超时、日志、限流）

2026 Q4 — Local DB / Store 统一抽象与工具链

目标：让 Plumego 在“小到中型项目”具备完整闭环：存储、迁移、测试。

  • R9. Local DB（内置存储）

    • 目标不是“替代 MySQL/Postgres”，而是提供：
      • 轻量 KV（内存 + 可选持久化）
      • 简单 query/scan 能力（面向工具型项目）
    • 数据一致性语义：事务/批处理（最小实现）
    • 备份/导出（jsonl / snapshot）

  • R10. Store/Repo 抽象（推荐层）

    • Repo 接口风格建议：避免泛滥 interface，保持明确边界
    • 测试工具：in-memory store、fixture、时间注入、fake clock

  • R11. 工具链

    • plumego new（脚手架，生成标准目录结构与示例）
    • plumego doctor（检查常见错误：超时、日志、CORS、反代 header 等）

交付物

  • examples/localdb
  • cmd/plumego（可选 CLI）
  • 一份“从 0 到上线”的参考部署文档（Caddy/Nginx）

v1.0 进入条件（Definition of Done）

只有在满足以下条件后，才建议发布 v1.0：

  1. Router / Middleware / Context 的 API 一年内无破坏性变更计划
  2. 官方示例覆盖：REST + Auth + WebSocket + PubSub + 本地存储
  3. 基准测试与回归测试齐备，至少包含：
    • 路由性能基线
    • 中间件链开销
    • WS 连接读写稳定性
  4. 文档闭环：Getting Started / Best Practices / Security / Deployment / FAQ

Issue / PR 标签体系（建议）

  • kind/bug kind/feature kind/docs kind/refactor
  • area/router area/middleware area/context area/ws area/auth area/store
  • prio/p0 prio/p1 prio/p2
  • breaking
  • good-first-issue

贡献路径（最小摩擦）

  1. 先从 docs 与 examples 开始：让“最佳实践”先站住。
  2. 再做 Router/Middleware 的稳定化：补齐测试与基准。
  3. 然后推进 WS/PubSub：以示例驱动确定 API 形态。
  4. 最后进入 Auth/Store：确保抽象可替换、避免绑死实现。

附：建议的 Roadmap 页面结构

  • roadmap/_index.md
  • roadmap/2026-q1-stabilization.md
  • roadmap/2026-q2-realtime.md
  • roadmap/2026-q3-security.md
  • roadmap/2026-q4-localdb-tooling.md