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

引言：为什么需要 Plumego？

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

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

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

它强调三件事：

• 显式优于隐式
• 结构优于技巧
• 可读性优于魔法

如果你认同这些价值观，那么 Plumego 值得你花 10 分钟了解。

Plumego 的核心理念

1. 显式（Explicit by Design）

在 Plumego 中：

• 路由如何注册，一目了然
• 中间件如何生效，顺序明确
• Context 中有什么数据，来源清楚

Plumego 刻意避免：

• 隐式注入
• 全局魔法状态
• 难以追踪的 hook / lifecycle

你看到的代码，就是系统真实的运行方式。

2. 分层而不过度抽象

Plumego 推荐但不强制的基本分层模型：

HTTP
└── Handler
└── Usecase
└── Domain / Service
└── Repository (optional)

每一层都有明确职责：

没有“为了分层而分层”，也没有“所有逻辑都塞进 Controller”。

3. 基于标准库，克制依赖

Plumego 优先使用 Go 标准库：

• net/http
• context
• encoding/json
• time

只有在 显著降低复杂度 的情况下，才引入第三方依赖。

这意味着：

• 升级 Go 版本风险极低
• 调试体验接近原生
• 不被生态波动绑架

快速开始：最小可运行示例

1. 安装

go get github.com/spcent/plumego

2. 项目结构示例

.
├── main.go
├── app/
│   ├── http/
│   │   ├── router.go
│   │   └── handlers/
│   │       └── health_handler.go
│   └── usecase/
│       └── health_usecase.go

这是一个可长期扩展的最小结构，而不是 demo-only 的目录。

3. main.go

package main

import (
	"log"
	"net/http"

	"github.com/spcent/plumego"
	"yourapp/app/http"
)

func main() {
	app := plumego.New()

	http.RegisterRoutes(app)

	log.Println("server started at :8080")
	log.Fatal(http.ListenAndServe(":8080", app))
}

注意几点：

• Plumego 本身实现了 http.Handler
• 没有隐藏的 server lifecycle
• 启动逻辑完全可控

4. 路由注册

package http

import (
	"github.com/spcent/plumego"
	"yourapp/app/http/handlers"
)

func RegisterRoutes(app *plumego.App) {
	app.GET("/health", handlers.Health)
}

路由集中、显式、可搜索。

5. Handler

package handlers

import (
	"net/http"

	"github.com/spcent/plumego"
)

func Health(ctx *plumego.Context) {
	ctx.JSON(http.StatusOK, map[string]string{
		"status": "ok",
	})
}

Handler 只关心：

• 请求
• 响应
• HTTP 语义

Context：克制但足够

Plumego 的 Context 不是“万能对象”。

它只提供：

• Request / ResponseWriter
• JSON / Text / Status helpers
• Context-aware 生命周期控制

你不会在这里看到：

• ORM Session
• 全局配置
• 业务状态缓存

这是一种刻意的约束。

中间件：顺序即语义

app.Use(Logger())
app.Use(Recover())
app.Use(Auth())

在 Plumego 中：

• 注册顺序 = 执行顺序
• 没有隐式优先级
• 没有注解驱动

这让系统行为可预测、可推理、可调试。

什么时候适合使用 Plumego？

Plumego 非常适合：

• 内部服务 / 中台服务
• 长期维护的业务系统
• 强调代码审查与工程规范的团队
• 希望“代码即文档”的项目

它不追求：

• 最少代码行数
• 极致开发速度
• All-in-one 生态

Birdor 视角下的总结

在 Birdor 看来，Plumego 更像是：

一套工程纪律，而不是一个炫技框架。

如果你正在寻找：

• 一个不会替你“做决定”的 Go 框架
• 一个能陪你走完整个项目生命周期的基础层
• 一个让新人快速理解、让老代码不失控的结构

那么，Plumego 是一个值得认真考虑的选择。

下一步

• 阅读：Why Explicit?
• 理解：Usecase 与 Handler 的边界
• 实践：为你的真实业务写第一个 Usecase

当你不再需要“框架帮你想”，
而是希望“框架不妨碍你思考”，
Plumego 才真正开始发挥价值。