目录与约定

布局不是审美问题：它决定了新代码该写在哪、依赖往哪个方向走、以及哪些规则可以交给 工具去拦。这页是目录表与四条硬约定的索引。

目录布局

依赖方向

flowchart TD
    CMD["cmd/<service>
main：只调 verticle.Run"]
    APP["internal/app/
实现 verticle.Service
装配 domain"]
    DOM["internal/domain/<name>/
handler · service · dao"]
    CORE["pkg/core/*
唯一的基础设施入口"]
    DRV["第三方驱动
pgx · go-sql-driver · modernc-sqlite
go-redis · gomemcache · franz-go · grpc · rpcx"]
    CMD --> APP
    APP --> DOM
    APP --> CORE
    DOM --> CORE
    CORE -.-> DRV
    DOM -. "禁止（depguard 拦截）" .-> DRV
    classDef core fill:#fdf6f0,stroke:#c8641f,color:#2b2722
    class CORE core
    classDef bad fill:#fff,stroke:#999,stroke-dasharray: 4 3,color:#777
    class DRV bad
				

四条强制约定

"约定"意味着违反时应该有东西报错。下面四条分别由 .golangci.yml、 类型签名与 make ci 承担。

1. 业务代码不 import 驱动库

单一基础设施入口。业务要用数据库就经 pkg/core/db，要 Redis 就经 pkg/core/redis——换驱动只改 pkg/core，业务一行不动。 business-no-drivers 规则覆盖 **/internal/**， examples-no-drivers 覆盖示例（示例要示范正确写法）：

business-no-drivers:
  files:
    - "**/internal/**"
  deny:
    - pkg: github.com/jackc/pgx
      desc: use pkg/core/db
    - pkg: github.com/go-sql-driver/mysql
      desc: use pkg/core/db
    - pkg: modernc.org/sqlite
      desc: use pkg/core/db
    - pkg: github.com/redis/go-redis
      desc: use pkg/core/redis
    - pkg: github.com/bradfitz/gomemcache
      desc: use pkg/core/memcache
    - pkg: github.com/twmb/franz-go
      desc: use pkg/core/kafka

2. 不用 Web 框架

路由与中间件用标准库：Go 1.22 的 ServeMux 原生支持方法路由与路径参数， pkg/core/httpx 补齐统一封套、超时、trace、访问日志、指标与错误映射。 再引一个第三方路由只会多一份依赖面和一套分叉语义。no-web-framework 规则对 所有 Go 文件生效：

no-web-framework:
  files:
    - "**/*.go"
  deny:
    - pkg: github.com/gin-gonic/gin
      desc: matex uses net/http via pkg/core/httpx
    - pkg: github.com/labstack/echo
      desc: matex uses net/http via pkg/core/httpx
    - pkg: github.com/gofiber/fiber
      desc: matex uses net/http via pkg/core/httpx
    - pkg: github.com/go-chi/chi
      desc: matex uses net/http via pkg/core/httpx
    - pkg: github.com/gorilla/mux
      desc: matex uses net/http via pkg/core/httpx

3. handler 签名固定

func(ctx context.Context, r *http.Request) (any, error)

handler 不碰 http.ResponseWriter：返回 nil 即 204， 返回 errs.* 即对应状态码加 {code,msg,data} 封套。 签名固定换来三件事：handler 能直接单测（不需要构造响应记录器以外的任何东西）、 能被中间件统一包装、能统一加超时与日志。 需要原生控制（流式、自定义状态码、SSE、文件下载）时走 HandleRaw， 它是唯一的逃生口，且不经过封套。细节见 HTTP 与路由。

4. 每个能力都有离线可跑的示例

examples/<feature>/ 一个目录一个能力，必须能go run、 必须有测试，且离线可跑：SQLite 用纯 Go 驱动（modernc.org/sqlite， 无 cgo）、Redis 用 redistest（miniredis）、Kafka 用 kfake、gRPC/rpcx 用进程内 server。所以 make ci 就能验证全部示例，不需要 Docker、不需要网络。

make example NAME=http        # 等价于 go run ./examples/http
make test-short               # 含 sqlite / miniredis / kfake / 进程内 RPC 用例
make ci                       # vet + test-short + build，示例一并被验证

一个部署单元 = 一个 cmd 二进制

verticle.Service 是部署单元的边界，而 cmd/<service>/ 是它的落地形态：一个 main 包对应一个 Name()、一个进程、 一份配置段、一套日志与指标标签。要加第二个部署单元，复制 cmd/demo 与 internal/app 改名即可——Name() 决定去配置文件的哪一段 取自己的配置，框架段（http、db…）与它无关。

// cmd/demo/main.go —— main 的全部内容
func main() {
    conf := flag.String("conf", "", "config file (default configs/config.yaml or $CONFIG_FILE)")
    flag.Parse()

    if err := verticle.Run(context.Background(), &app.DemoService{}, verticle.WithConf(*conf)); err != nil {
        fmt.Fprintln(os.Stderr, "fatal:", err)
        os.Exit(1)
    }
}

由此推出两条经常被问到的推论：不要在一个进程里塞两个服务（配置段、日志标签、 指标前缀都会打架，生命周期也会互相拖累）；不要给不同环境准备不同的 main—— 依赖是否存在是部署事实，删掉配置里那一段即可，代码不用改。

新代码放哪

下一步

• 命令与部署：Makefile 目标、CI 任务、Docker 镜像与本地依赖。
• pkg/core 速查：每个包的用途与开关。
• examples/http：按这套布局写出来的最小服务。