Plumego Docs 信息架构（IA）总览

By Birdor Engineering

December 29, 2025

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

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

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

0. Docs Root

docs/_index.md

目的：
不是介绍 API，而是回答一个问题：

我该不该继续读这套文档？

内容建议：

Plumego 是什么 / 不是什么
适合谁 / 不适合谁（链接到专题）
文档阅读路径推荐（不同角色）

1. Intro（价值与边界）

docs/intro/
├── _index.md
├── what-is-plumego.md
├── design-philosophy.md
├── tradeoffs.md
├── when-not-to-use.md
└── plumego-and-birdor.md

目标读者：正在做技术选型的人

设计原则：

不教代码
不讲 API
只讲判断

这是 Plumego 最重要的一层文档。

2. Getting Started（最低可运行路径）

docs/getting-started/
├── _index.md
├── installation.md
├── minimal-server.md
├── project-layout.md
└── first-request.md

目标读者：已决定“试用 Plumego”的工程师

关键原则：

只解决“跑起来”
不引入复杂概念
不提前谈最佳实践

3. Concepts（核心抽象说明）

docs/concepts/
├── _index.md
├── request-lifecycle.md
├── context.md
├── handler.md
├── middleware.md
├── router.md
└── error-model.md

这是 Plumego 的“理论核心”。

目标：

解释 Plumego 为什么这样设计
让读者形成稳定心智模型

重要原则：

Concepts 文档 ≠ API 文档
Concepts 文档 ≠ 教程

4. Architecture（工程结构与边界）

docs/architecture/
├── _index.md
├── layering.md
├── boundary-definition.md
├── domain-and-usecase.md
├── dependency-direction.md
└── monolith-to-services.md

目标读者：正在做架构设计的工程师

重点回答：

Handler 到 Domain 的边界
哪些代码“永远不该依赖 Plumego”
如何避免框架侵入业务

5. Core（核心模块说明）

docs/core/
├── _index.md
├── http-server.md
├── router.md
├── middleware.md
├── context.md
├── response.md
└── lifecycle.md

这是“工程说明书”，不是教程。

原则：

精确
不夸张
不隐藏限制

每一章都应回答：

做了什么
没做什么
为什么不做

6. Guides（实战指导）

docs/guides/
├── _index.md
├── logging-and-traceid.md
├── panic-recovery.md
├── auth-and-jwt.md
├── request-validation.md
├── webhook-server.md
├── websocket.md
└── graceful-shutdown.md

目标：

把 Plumego 用在真实系统里
不引入“框架魔法”

风格：

示例驱动
不追求“最优解”
明确说明 tradeoff

7. Patterns（推荐模式）

docs/patterns/
├── _index.md
├── handler-thin.md
├── usecase-centric.md
├── middleware-composition.md
├── error-propagation.md
├── config-management.md
└── testing-strategy.md

这是 Plumego 的“经验层”。

回答的问题是：

在 Plumego 里，什么写法更安全？

⚠️ 明确说明：

这是推荐
不是强制
不是规范

8. Advanced（高级与扩展）

docs/advanced/
├── _index.md
├── performance.md
├── custom-router.md
├── replacing-components.md
├── embedding-plumego.md
└── multi-service-setup.md

目标读者：已深度使用 Plumego 的团队

原则：

不提前暴露
不制造复杂度焦虑
明确风险点

9. Reference（参考手册）

docs/reference/
├── _index.md
├── public-apis.md
├── config-options.md
├── middleware-signatures.md
└── error-codes.md

这是唯一“偏手册”的区域。

特点：

无叙事
可查阅
不讲故事

10. FAQ（决策辅助）

docs/faq/
├── _index.md
├── plumego-vs-gin.md
├── plumego-vs-echo.md
├── why-not-framework-x.md
├── can-i-use-with-xxx.md
└── common-mistakes.md

目标：

减少重复问题
防止错误使用方式扩散

11. Roadmap（演进说明）

docs/roadmap/
├── _index.md
├── design-principles.md
├── planned-features.md
├── non-goals.md
└── versioning.md

非常重要的一点：明确 Non-goals，防止社区期待失控。

12. Contributing（贡献与治理）

docs/contributing/
├── _index.md
├── philosophy.md
├── code-structure.md
├── decision-process.md
├── pull-request-guide.md
└── documentation-guide.md

Plumego 的贡献文档，必须是“工程治理文档”，而不是“如何提 PR”。