很多人第一次写 Go Web 服务，往往是从一个 main.go 开始：注册路由、写处理函数、启动监听，几十行代码就能把接口跑起来。这种方式很适合入门，但项目一旦稍微变大，所有逻辑都堆在入口文件里，就会很快失控。

服务骨架的意义，不是为了显得“架构高级”，而是为了让代码从一开始就具备清晰入口、明确边界和可持续扩展的能力。

为什么服务骨架必须尽早建立

因为 HTTP 服务天然会不断长大。

最开始可能只有一个健康检查接口，后来会增加配置加载、路由分组、鉴权中间件、日志链路、数据库连接、缓存客户端、外部依赖，再往后还会出现不同业务模块。如果这些内容从一开始就全部堆在 main.go，后面几乎一定会越改越乱。

所以服务骨架不是“大项目才需要”，而是“只要你预计它会继续长，就应该尽早建立”。

一个最小服务通常需要哪些层次

从最基础的角度看，一个可扩展的 Go HTTP 服务，至少应该区分下面几类职责。

main 负责程序入口和启动流程。

router 负责路由注册和中间件装配。

handler 负责接收 HTTP 请求、解析参数、调用业务层并返回响应。

service 负责业务逻辑。

repo 或 dao 负责数据访问。

你不一定一开始就把所有目录都拆出来，但脑子里最好已经有这几层边界。因为这样你在写代码时，就不会把数据库访问、参数校验和业务判断全部混在同一个处理函数里。

main 函数应该关注什么

main 最重要的职责，是把应用启动起来，而不是承载业务细节。

它通常只需要做几件事：加载配置、初始化依赖、构建路由、创建 HTTP Server、监听退出信号并优雅关闭。

如果 main 里开始出现大量业务逻辑、SQL 语句、复杂参数判断，那往往说明服务骨架已经被破坏了。

handler 为什么不要写太重

很多初学者最容易把所有逻辑都塞进 handler。因为请求就是从这里进来的，看起来最顺手。

但 handler 最适合做的，其实是“控制层”工作。

  • 接收请求
  • 解析参数
  • 做基础校验
  • 调用业务层
  • 统一封装响应

一旦你在 handler 里直接写大量业务分支、数据库查询和外部调用，它很快就会变成最难测试、最难复用、最难维护的一层。

服务骨架和工程化能力有什么关系

服务骨架并不只是代码风格问题，它和后面的工程化能力几乎全部相关。

如果入口清晰，你更容易插入配置初始化和日志初始化；如果路由和中间件组织合理，你更容易统一做超时控制和恢复逻辑；如果业务层和数据访问层分离，你更容易写测试和替换实现。

也就是说，后面很多工程化能力能否自然接入，很大程度取决于你一开始的骨架是不是干净。

一个很常见的反例

下面这种结构在入门阶段非常常见，但扩展性很差。

1
2
3
4
5
6
7
8
func main() {
    http.HandleFunc("/users", func(w http.ResponseWriter, r *http.Request) {
        db, _ := sql.Open("mysql", dsn)
        rows, _ := db.Query("select id, name from users")
        // 解析、拼装、返回
    })
    http.ListenAndServe(":8080", nil)
}

这段代码不是“不能跑”，而是职责几乎全部耦合在一起了。入口、路由、数据访问、响应输出都混在一个闭包里，后面任何一个维度要扩展都会痛苦。

更合理的思路是什么

更合理的思路，是让每一层只做自己该做的事。

main 负责启动。

router 负责挂接口。

handler 负责请求和响应。

service 负责业务判断。

repo 负责访问数据。

这样做的收益不是“代码显得整齐”，而是后续你要加中间件、做测试、换数据源、加日志时，改动范围都更可控。

一个值得自己做的小练习

你可以自己搭一个最小项目，只做两个接口。

  • /healthz 返回服务状态。
  • /users/:id 返回一个模拟用户信息。

但要求你不要把所有逻辑写在 main.go 里，而是至少拆出路由和处理器两层。等你写完以后再回头看，就会很清楚地感受到：代码不是因为“更多目录”才更复杂，而是因为“职责不清”才更复杂。

小结

一个 Go HTTP 服务的骨架，看起来只是目录和函数组织方式，实际上它决定了后面所有工程化能力能否顺利落地。你越早把入口、路由、处理器和业务边界理清楚，后面做配置、日志、错误处理、中间件和测试时就越轻松。服务骨架不是形式问题，它本质上是后端项目可维护性的起点。