开始使用

两分钟跑起来

克隆仓库并运行参考服务，验证 Plumego 在你的环境中可以工作：

git clone https://github.com/spcent/plumego
cd plumego/reference/standard-service
go run .

验证：

curl http://localhost:8080/healthz
# {"data":{"status":"ok","service":"plumego-reference","timestamp":"2026-06-08T00:00:00Z"}}

curl 'http://localhost:8080/api/v1/greet?name=Alice'
# {"data":{"message":"hello, Alice"}}

参考服务展示了完整的应用布局（详见下方）。

最快起步 — 直接添加到任意 Go 项目

环境要求：Go 1.26+ 和一个现有的 Go module（go.mod）。

go mod init myservice        # 已有 module 可跳过
go get github.com/spcent/plumego@latest

创建 main.go：

package main

import (
    "net/http"

    "github.com/spcent/plumego/contract"
    "github.com/spcent/plumego/core"
    plog "github.com/spcent/plumego/log"
)

func main() {
    app := core.New(core.DefaultConfig(),
        core.AppDependencies{Logger: plog.NewLogger()})

    _ = app.Get("/ping", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        _ = contract.WriteResponse(w, r, http.StatusOK,
            map[string]string{"status": "ok"}, nil)
    }))

    app.Run() // combined prepare + listen on :8080
}

运行并验证：

go run .
curl http://localhost:8080/ping
# {"data":{"status":"ok"}}

两种生命周期模式： app.Run() 是合并路径——在一次调用中完成 prepare、wiring 和启动。如果需要在启动前检查或包装 *http.Server（自定义 TLS、连接追踪或测试嵌入），可以改用 app.Prepare() + app.Server()。完整 API 见 core 模块手册。

这段代码证明了什么

信号	说明
`contract.WriteResponse` 包装了 map	成功响应使用稳定传输合约
`app.Get(path, http.HandlerFunc(...))`	路由注册显式，没有隐藏的 `init()`
`app.Run()` 一次调用	生命周期显式且可组合——服务在你看到的位置启动

想看完整的 canonical 服务形态？

参考应用覆盖完整目录布局——包括配置加载、健康检查端点、handler 分层和 constructor-based 依赖注入。

四个文件覆盖了完整的服务形态：

文件	该看什么
`reference/standard-service/main.go`	启动顺序
`reference/standard-service/internal/app/app.go`	显式依赖注入
`reference/standard-service/internal/app/routes.go`	路由归属集中在一处
`reference/standard-service/internal/handler/api.go`	Handler 形态：标准库兼容

选择下一个模块

基础示例跑通之后，保持 reference/standard-service 的应用布局，只按需添加对应的能力家族：

目标	从这里开始
标准 JSON API，显式 handler	稳定根：`core`、`router`、`contract`、`middleware`
可复用 CRUD 与资源规范	`x/rest`
租户解析、策略、配额与隔离	`x/tenant`
反向代理、重写、负载均衡与 edge 传输	`x/gateway`，仅在需要动态后端查找时再加 `x/gateway/discovery`
WebSocket 传输	`x/websocket`
消息编排工作流	`x/messaging`
入站 webhook 验证或出站 webhook 投递	`x/messaging/webhook`，当任务比传输机制更宽泛时从 `x/messaging` 开始
文件上传、下载与临时 URL 传输	`x/fileapi`，存储与元数据实现在 `x/data/file`
可复用熔断器或限流原语	`x/resilience`
AI provider、session、streaming 与工具	`x/ai/provider`、`x/ai/session`、`x/ai/streaming`、`x/ai/tool`
可观测性导出、受保护诊断或本地调试端点	`x/observability`、`x/observability/ops` 或 `x/observability/devtools`，按需选择
gRPC + HTTP 服务托管或出站 RPC 客户端连接池	`x/rpc`
从已注册路由生成 OpenAPI 3.1 文档	`x/openapi`
显式 JSON 绑定与调用方自有请求验证	`x/validate`

不要从 x/* 包开始一个新的应用布局。扩展是对 reference/standard-service canonical 接线的显式补充。

什么时候离开这页

下一个问题	去哪里
应该从哪些文件复制结构？	参考应用
请求路径如何工作？	请求流程
应该打开哪个稳定根或 `x/*` 家族？	模块总览
能不能长期依赖某个包？	发布策略
常见问题（认证、数据库、与 Gin 的对比）	常见问题