零散脚本整合成系统的核心是建立模块边界与依赖契约，而非简单合并代码；必须执行 go mod init（在空目录、用合法域名路径）、拆分 internal/pkg/cmd 目录、为本地包配置 replace 与独立 go.mod，并规范构建输出。
零散脚本整合成系统，核心不是“合并代码”，而是建立模块边界与依赖契约。没做 go mod init、没拆 internal 和 pkg、没处理本地包引用，强行合并不但不会变“健全”，反而放大耦合和构建失败风险。
go mod init 必须在空目录执行，且模块路径不能是 ./ 或纯名
很多人直接在已有脚本目录下跑 go mod init myapp，结果 go build 报 no required module provides package。这不是命令错了，是 Go 拒绝把当前目录当模块根——它只认 go.mod 所在位置为模块起点，且路径必须像域名一样合法。
- 新建空目录：
mkdir -p ~/projects/order-system && cd ~/projects/order-system - 初始化时用真实或模拟域名：
go mod init example.com/order（别用go mod init ./order或go mod init order） - 检查生成的
go.mod：首行必须是module example.com/order，不是module ./order，否则所有import都会解析失败
本地脚本拆成 internal/pkg/cmd 三类，权限和复用性立刻分明
把原来十几个 .go 文件全塞进一个目录，go mod tidy 会报错、CI 构建会失败、别人不敢改——因为没人知道哪个函数能被外部调用，哪个只是临时胶水代码。
初始化并管理阿里云SDK Go 客户端，涵盖 sync.Once 单例、goroutine 安全、endpoint 与 region 配置、VPC 端点及调试。
-
cmd/下放入口：比如cmd/importer/main.go，只负责 flag 解析和顶层调度，不写业务逻辑 -
internal/存私有逻辑：比如internal/parser/、internal/validator/，其他模块无法 import，防止被误用 -
pkg/放可复用工具：比如pkg/xlsx/、pkg/httpclient/，对外暴露 clean 接口，带单元测试 - 每个子目录若需独立版本或被其他项目引用，必须有自己的
go.mod（哪怕只有module example.com/order/pkg/xlsx一行）
跨目录引用必须用 replace，且被引用目录也要有 go.mod
想让 cmd/importer 调 internal/parser，直接写 import "internal/parser" 会报 unknown import path。Go 不支持相对路径导入，也不认文件系统层级，只认模块路径。
- 在主模块（
example.com/order）的go.mod中加：replace internal/parser => ./internal/parser -
./internal/parser目录下必须有go.mod，内容为：module example.com/order/internal/parser - 删掉
replace后忘了go mod tidy？构建时仍会走旧缓存，得手动go clean -modcache再试 - 绝对路径
replace internal/parser => /home/user/project/internal/parser看似可行，但go mod vendor会失败，必须用相对路径
构建输出名必须显式加 .exe（Windows）或统一用 GOOS
脚本时代习惯 go run main.go，一上系统就得打包发布。但 go build -o bin/app main.go 在 Windows 下生成的是 bin/app（无后缀），双击打不开，cmd 里也执行失败——这不是 bug，是 Windows 的可执行文件识别机制决定的。
- 开发时就约定输出名：
go build -o bin/app.exe cmd/importer/main.go（Windows）或go build -o bin/app cmd/importer/main.go（Linux/macOS） - CI/CD 中统一用交叉编译：
GOOS=windows go build -o bin/app.exe cmd/importer/main.go，避免依赖本地环境 - 别再用
go install：模块模式下它只装已发布版本（如v1.2.0），本地开发迭代必须靠go build
真正卡住团队协作的，从来不是语法或命令，而是 go.mod 里残留的 replace、没清理的 indirect 依赖、以及 internal 包被意外 export 到外部模块——这些细节不盯紧，系统越“大”越容易崩。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
