Engineering on PlumePHP

Plumego Best Practices · 一个真实业务（用户中心）的完整示例

Mon, 29 Dec 2025 12:30:00 +0800

0. 这份示例解决什么问题

你已经有了 Plumego，但真正把它用进“用户中心”这种业务时，通常会卡在三件事：

模块边界：User / Auth / Project 怎么拆，拆完怎么组装，才不会越写越乱。
请求与错误模型：统一 JSON 输出、统一错误码、统一 trace/request id，把“可观察性”内建进骨架。
鉴权：最小可用、可扩展、可替换（未来可接 JWT / OAuth / SSO），但现在就能跑通。

Plumego 的定位是“标准库内的 Go HTTP 工具箱”，用 core.App 组合能力，而不是把你锁死在某种框架范式里。
你会看到本文的写法更接近 Birdor 的工程风格：少魔法、强边界、可演进。

一个真实业务（用户中心）的完整 Plumego 示例

Mon, 29 Dec 2025 12:00:00 +0800

目标与边界

你将得到一个可运行的用户中心（User Center）最小实现，覆盖：

注册：POST /api/auth/register
登录：POST /api/auth/login
刷新：POST /api/auth/refresh
当前用户：GET /api/me
更新资料：PUT /api/me
管理端用户：GET /api/admin/users（RBAC：admin 角色）

实现策略（Birdor 风格）：

Plumego Roadmap

Mon, 29 Dec 2025 11:30:00 +0800

状态说明

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

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

路线图原则（Birdor 风格）

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

版本策略

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

Roadmap 总览（2026）

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

Plumego Docs 信息架构（IA）总览

Mon, 29 Dec 2025 11:00:00 +0800

定位：工程级框架文档，而不是教程集合

docs/
├── _index.md
├── intro/
├── getting-started/
├── concepts/
├── architecture/
├── core/
├── guides/
├── patterns/
├── advanced/
├── reference/
├── faq/
├── roadmap/
└── contributing/

下面逐层解释每一部分为什么存在、解决什么问题。

Plumego Best Practices

Mon, 29 Dec 2025 10:30:00 +0800

写在前面：这不是“技巧合集”

这份文档不是：

API 参数的穷举说明
所有功能的使用手册
为了“写得高级”而复杂化的套路

它是一份 工程级 Best Practices，核心目标只有一个：

让一个 Plumego 项目在 1～3 年后依然清晰、可控、可演进。

Plumego 入门：一个克制而清晰的 Go 服务框架

Mon, 29 Dec 2025 10:00:01 +0800

引言：为什么需要 Plumego？

在 Birdor 的工程实践中，我们反复遇到同一个问题：

当项目从“能跑”进入“要长期维护”阶段，Go Web 框架往往开始成为负担，而不是助力。

Plumego 的目标并不是“更快写完第一个接口”，而是帮助你在 6 个月、12 个月甚至 3 年后，依然能够清晰地理解、演进和重构你的服务。

什么时候不该使用 Plumego

Sun, 28 Dec 2025 07:30:00 +0800

引言：一个负责任的框架，必须明确“不适用场景”

任何一个认真对待工程质量的框架，都必须敢于回答一个问题：

在什么情况下，你不应该使用我？

如果一个框架声称：

适合所有团队
适合所有阶段
适合所有业务

那么它几乎可以确定是不可信的。

Plumego vs 常见 Go 框架：设计取舍说明

Sun, 28 Dec 2025 00:36:00 +0800

引言：框架对比，本质是在对比价值观

在技术社区中，“A 框架 vs B 框架”的讨论几乎从未停止。

但真正成熟的工程师往往知道：

框架之争，很少是技术对错，更多是价值取舍。

Plumego 并不是在一个“空白市场”中诞生的。
相反，它是在 Go 生态已经非常繁荣 的前提下，刻意选择了一条看起来“不讨巧”的道路。

Plumego：一个回归 Go 本质的极简服务框架

Sun, 28 Dec 2025 00:28:00 +0800

前言：为什么还要再做一个 Go 框架

在 Go 生态已经高度成熟的今天，“再做一个 Go Web 框架” 看起来既多余，又无趣。

我们已经有了：

功能极其完备、社区庞大的全栈式框架
极致性能导向、偏底层的 HTTP / RPC 框架
面向云原生、与 Kubernetes 深度绑定的应用运行时
为微服务量身定制的一整套工程体系

Plumego 并不是要和它们竞争。