Plumego Roadmap

状态说明

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