本文介绍如何利用 goimports 的 -local 参数配合自定义配置，实现符合企业规范的四层 import 分组（标准库、当前项目、公司内部模块、第三方依赖），无需额外工具即可精准控制导入顺序。
本文介绍如何利用 `goimports` 的 `-local` 参数配合自定义配置，实现符合企业规范的四层 import 分组（标准库、当前项目、公司内部模块、第三方依赖），无需额外工具即可精准控制导入顺序。
Go 官方工具链中的 goimports 不仅能自动增删 imports，还支持通过 -local 标志对导入路径进行语义分组。该标志指定一个或多个“本地”导入前缀（以逗号分隔），goimports 会将匹配这些前缀的包归入独立分组，并置于标准库之后、第三方包之前——这正是实现四层分组的关键机制。
要达成如下理想分组结构：
import (
// 标准库
"fmt"
"net/http"
// 当前项目（如 github.com/yourorg/yourproject）
"github.com/yourorg/yourproject/internal/util"
"github.com/yourorg/yourproject/pkg/config"
// 公司内部模块（如 github.com/yourorg/common, gitlab.company.com/platform/*）
"github.com/yourorg/common/log"
"gitlab.company.com/platform/auth"
// 所有其他第三方依赖
"github.com/gin-gonic/gin"
"golang.org/x/sync/errgroup"
)需在 goimports 命令中组合多个 -local 前缀（注意：v0.13.0+ 支持多前缀，用逗号分隔）：
goimports -local "github.com/yourorg/yourproject,github.com/yourorg/common,gitlab.company.com/platform" -w .
执行后，goimports 将按以下优先级生成分组：
- 标准库（无前缀，自动识别）
- -local 中声明的前缀匹配项（按声明顺序合并为一个逻辑组，但实际输出中仍统一置于第二位）
- 其余所有非标准库、非 -local 的导入（即第三方包）
⚠️ 注意事项：
- goimports 默认只生成 三个逻辑分组（std / local / others）。若需严格区分「当前项目」与「公司模块」为两个独立组，需借助编辑器插件（如 VS Code 的 gopls 配置）或自定义 wrapper 脚本做二次处理；
- 确保 goimports 版本 ≥ v0.13.0（可通过 goimports -version 检查），旧版本不支持多 -local 前缀；
- 推荐将命令集成至 pre-commit 或 golangci-lint 的 run 阶段，保证团队一致性；
- 若使用 gopls，可在 settings.json 中配置：
"gopls": { "build.experimentalUseInvalidFiles": true, "formatting.gofumpt": false, "formatting.goimportsLocal": "github.com/yourorg/yourproject,github.com/yourorg/common,gitlab.company.com/platform" }
总结：goimports -local 是官方推荐、轻量可靠且开箱即用的解决方案。虽然原生仅支持三层分组，但通过合理设计前缀策略（例如将「当前项目」设为最高优先级前缀），再辅以团队约定与 CI 检查，完全可满足四层分组的工程化落地需求。
