维护性差的微服务代码，90%问题出在包组织混乱、业务逻辑与http绑死、错误处理被忽略：包结构不按职责分层易成“意大利面”；handler塞业务逻辑导致测试难、复用差；忽略错误类型和传播路径使panic隐蔽、日志失真。
直接说结论：维护性差的微服务代码，90% 问题出在包组织混乱、业务逻辑与 HTTP 绑死、错误处理被忽略这三个地方。
包结构不按职责分层，迟早变成“意大利面”
很多人把所有代码塞进 main.go 或一个叫 pkg 的包里，等加到第 5 个接口时就发现改一个字段要翻 7 个文件。Clean Architecture 不是教条，但分层有实际约束力：
-
handler只负责解析请求、调用 service、写响应 —— 不做校验、不查数据库、不拼字符串 -
service包含纯业务逻辑（比如“扣库存前先检查余额”），它不依赖http或database/sql，只依赖model和自己的接口定义 -
model是数据载体，带 JSON tag，但不含方法；repository（如有）才封装 DB 操作，且返回model类型 - 别用
utils包收容所有“暂时没地方放”的函数 —— 它会迅速膨胀成不可测的黑盒
HTTP handler 里写业务逻辑，等于给未来埋雷
常见写法：AddHandler 函数里直接连 DB、做计算、拼错误信息。后果是：单元测试只能走 HTTP 请求，mock 成本高；换 gRPC 就得重写全部 handler；加个缓存逻辑要动 3 层。
正确做法是让 handler 只做三件事：
- 从
r.URL.Query()或json.NewDecoder(r.Body)提取参数 → 转成service层能用的结构体 - 调用
service.DoSomething(req)，接收resp, err - 根据
err写对应 HTTP 状态码（http.StatusBadRequest/http.StatusInternalServerError），把resp序列化输出
例如：GetUserByID handler 不该包含 SQL 查询语句，只该调用 userSvc.GetUser(id) —— 这样 service 层才能被 CLI 工具或定时任务复用。
忽略错误类型和传播路径，会让 panic 隐蔽爆发
Go 的 error 不是装饰品。写成 if err != nil { log.Fatal(err) } 看似省事，实则切断了错误上下文。微服务里更常见的是：
Go语言（Golang）1.26.0版本提供 Go 官方 Windows amd64 MSI 安装包下载入口，版本号 1.26.0，可用于旧项目维护、兼容性测试和指定版本开发环境配置。
- 底层 DB 错误（
sql.ErrNoRows）被粗暴转成http.StatusNotFound，但中间层没透传原错误，导致日志里只剩 “user not found”，查不出是超时还是连接断开 - 用
fmt.Errorf("failed to get user: %w", err)包装错误，但 handler 层没做类型断言，统一返回 500，掩盖了可重试的 transient error - goroutine 里 panic 没 recover，整个服务进程退出 —— 因为
http.ServeMux默认不捕获子 goroutine panic
建议：所有 service 方法返回 error，handler 中用 errors.Is(err, xxxErr) 判断并映射状态码；关键 goroutine 加 defer func() { if r := recover(); r != nil { log.Printf("panic: %v", r) } }()。
依赖注入不做显式传递，测试和替换就必然卡壳
硬编码 db := sql.Open(...) 在 handler 或 service 里，会导致：
- 无法在测试中注入 mock DB
- 不同环境（dev/staging/prod）要用 build tag 或全局变量切换配置，极易出错
- 启动时 DB 连接失败，整个服务起不来，但其实部分 API（如健康检查）本可降级可用
最简方案：main 函数里初始化依赖（DB、cache、logger），通过构造函数传入 handler 或 service：
svc := &UserService{DB: db, Cache: redisClient}
h := &UserHandler{Service: svc}
不需要引入复杂 DI 框架 —— Go 的接口 + 构造函数已足够清晰。关键是：所有外部依赖必须作为字段显式声明，不能藏在包级变量或闭包里。
真正难的不是写功能，而是让下一个人（或三个月后的你）能快速定位某次 400 错误来自哪个校验环节、哪行 SQL、哪个中间件。包结构、错误传播、依赖注入这三处，改起来不难，但漏掉任何一处，维护成本都会指数级上升。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
