Go 语言中，当测试文件位于独立包（如 api_client_tests）而非被测包（如 api_client）内时，go test -cover 默认仅统计测试包自身的覆盖率；需配合 -coverpkg 参数显式指定被测包，才能正确计算目标包的语句覆盖情况。
go 语言中，当测试文件位于独立包（如 `api_client_tests`）而非被测包（如 `api_client`）内时，`go test -cover` 默认仅统计测试包自身的覆盖率；需配合 `-coverpkg` 参数显式指定被测包，才能正确计算目标包的语句覆盖情况。
在 Go 工程实践中，将测试代码与生产代码物理分离（如置于不同目录甚至不同模块）虽有助于逻辑解耦或满足特定项目规范，但Go 官方推荐的惯用方式仍是将 _test.go 文件保留在被测包内（即同包不同文件），以自然享有包级访问权限并简化工具链支持。
不过，若确需实现“黑盒测试”——即严格限制测试仅通过导出的公共 API 交互（不访问包内未导出符号），同时又希望保持测试文件物理隔离，可采用以下合规方案：
✅ 正确做法：测试文件仍在 api_client 包内，但目录结构可分层管理
例如：
api_client/
├── Client.go
├── ArtistService.go
├── api_client_test.go # package api_client
└── tests/
├── ArtistService.Events_test.go # package api_client
└── ArtistService.Info_test.go # package api_client
所有测试文件均声明 package api_client，go test ./api_client/... -cover 即可天然覆盖全部源码。
⚠️ 若坚持使用独立测试包（如 api_client_tests），则必须显式启用跨包覆盖率分析：
go test -cover -coverpkg="bandsintown-api/api_client" ./api_client_tests/...
- -coverpkg 后接被测包的完整导入路径（非目录路径）；
- 测试包需正确导入 bandsintown-api/api_client 并调用其导出函数；
- 覆盖率结果反映的是 api_client 包中被实际执行的语句，而非测试包自身。
? 验证与调试建议：
- 使用 go tool cover -func=cover.out 查看各函数覆盖率明细；
- 生成 HTML 报告：go tool cover -html=cover.out -o coverage.html；
- 注意：-coverpkg 不支持通配符，多包需逗号分隔，如 -coverpkg=pkg1,pkg2。
? 总结：Go 的测试机制设计以“同包测试”为最佳实践，既保障封装性（通过仅调用导出符号实现黑盒），又避免工具链复杂化。物理隔离可通过目录组织达成，无需牺牲包结构一致性。强行拆分包将增加构建配置负担，且易引发覆盖率误判——优先选用 -coverpkg 作为过渡方案，长期仍建议回归 Go 原生模式。
