**偏企业级/中大型服务端的 Go 代码架构蓝图（目录 + 分层原则 + 关键组件样板 + 工程化配套）。它综合了 Go 社区常用的 project-layout、Go 官方模块组织建议、Clean Architecture 思想，以及 Uber Go 风格/工程实践。你可以按需裁剪，但建议先按“全量骨架”搭起来再删。**

---

## 1. 设计目标（企业级要解决什么）

1. **边界清晰**：业务与基础设施解耦，避免“框架入侵”。
2. **可测试性强**：业务核心可纯单测，外部依赖可替换 Mock。
3. **易扩展**：新业务是新增模块，而不是改一堆旧代码。
4. **工程化完备**：lint / test / build / deploy / observability 一条龙。

---

## 2. 推荐目录结构（骨架）

基于 golang-standards/project-layout 的骨架，再融合 Clean Architecture 的“领域/用例/适配器/基础设施”分层。

```text
my-service/
├── cmd/                        # 每个可执行程序一个子目录
│   └── api/
│       └── main.go
├── internal/                   # 私有代码（强边界）
│   ├── app/                    # 应用装配/启动
│   │   └── wiring.go
│   ├── domain/                 # 领域层：实体/值对象/领域服务/领域事件
│   │   └── user/
│   │       ├── entity.go
│   │       ├── repository.go   # 领域层定义接口
│   │       └── service.go
│   ├── usecase/                # 用例层：业务编排（依赖 domain 接口）
│   │   └── user_uc.go
│   ├── adapter/                # 适配器层：入口/出口
│   │   ├── http/               # HTTP handler / router
│   │   ├── grpc/               # gRPC handler
│   │   └── mq/                 # 消息队列消费者/生产者
│   ├── infra/                  # 基础设施层：DB/Cache/第三方/配置等实现
│   │   ├── persistence/        # repository 实现
│   │   ├── redis/
│   │   ├── clients/            # 外部服务 client
│   │   └── observability/
│   └── pkg/                    # internal 可复用工具（非对外）
│       ├── logger/
│       ├── config/
│       ├── errors/
│       └── middleware/
├── pkg/                        # 对外可复用库（如你要开源/给别的服务用）
│   └── ...
├── api/                        # Protobuf / OpenAPI 定义
│   ├── proto/
│   └── openapi/
├── configs/                    # 配置模板/默认配置
│   ├── config.yaml
│   └── config.dev.yaml
├── deployments/                # k8s/helm/terraform 等交付物
│   ├── helm/
│   └── k8s/
├── scripts/                    # 运维脚本/代码生成脚本
├── test/                       # 集成测试/契约测试资源
├── docs/                       # 架构/ADR/使用文档
├── .golangci.yml               # lint 聚合配置
├── Makefile                    # 统一工程入口
├── go.mod
└── go.sum
```

**关键点：**

- `cmd/` 只做启动、装配、优雅退出；别放业务。
- 业务核心统一在 `internal/domain + internal/usecase`。
- 外部世界（HTTP/DB/三方）都放 `adapter/infra`，并通过接口向内依赖。
- `internal/` 强制私有边界，让大项目不会“包满天飞”。

---

## 3. 分层职责与依赖方向

Clean Architecture 的依赖规则：  
**adapter / infra → usecase → domain**（只允许向内依赖）。

### 3.1 Domain（领域层）

- **纯业务模型**：Entity / Value Object / Domain Service
- **定义接口，不实现**：Repository、外部能力的 Ports
- 不依赖框架、数据库、网络库。

### 3.2 Usecase（用例层）

- 业务流程编排（事务、跨聚合协作、调用 repo 接口）。
- 依赖 Domain 接口，为 adapter 提供可调用的“应用服务”。

### 3.3 Adapter（适配器层）

- **输入适配器**：HTTP/gRPC/MQ/CLI
- 负责 DTO/VO 转换、参数校验、错误映射、鉴权等。

### 3.4 Infra（基础设施层）

- 实现 Domain 定义的 Repository、外部 Client
- 负责 DB/Cache/消息/第三方 SDK 初始化与封装。

---

## 4. 样板代码（最小可运行）

下面用“用户创建”串起来（只给骨架，真实项目继续扩充）。

### 4.1 domain/user/entity.go

```go
package user

import "time"

type UserID string

type User struct {
	ID        UserID
	Name      string
	Email     string
	CreatedAt time.Time
}

func New(name, email string) *User {
	return &User{
		ID:        UserID(generateID()),
		Name:      name,
		Email:     email,
		CreatedAt: time.Now(),
	}
}
```

### 4.2 domain/user/repository.go（领域层接口）

```go
package user

import "context"

type Repository interface {
	Create(ctx context.Context, u *User) error
	FindByEmail(ctx context.Context, email string) (*User, error)
}
```

### 4.3 usecase/user_uc.go

```go
package usecase

import (
	"context"
	"my-service/internal/domain/user"
)

type UserUsecase struct {
	repo user.Repository
}

func NewUserUsecase(repo user.Repository) *UserUsecase {
	return &UserUsecase{repo: repo}
}

func (uc *UserUsecase) CreateUser(ctx context.Context, name, email string) (*user.User, error) {
	if exist, _ := uc.repo.FindByEmail(ctx, email); exist != nil {
		return nil, ErrEmailTaken
	}
	u := user.New(name, email)
	if err := uc.repo.Create(ctx, u); err != nil {
		return nil, err
	}
	return u, nil
}
```

### 4.4 infra/persistence/user_repo_mysql.go（实现接口）

```go
package persistence

import (
	"context"
	"database/sql"
	"my-service/internal/domain/user"
)

type UserRepoMySQL struct {
	db *sql.DB
}

func NewUserRepoMySQL(db *sql.DB) *UserRepoMySQL {
	return &UserRepoMySQL{db: db}
}

func (r *UserRepoMySQL) Create(ctx context.Context, u *user.User) error {
	_, err := r.db.ExecContext(ctx,
		"INSERT INTO users(id,name,email,created_at) VALUES (?,?,?,?)",
		u.ID, u.Name, u.Email, u.CreatedAt,
	)
	return err
}

func (r *UserRepoMySQL) FindByEmail(ctx context.Context, email string) (*user.User, error) {
	row := r.db.QueryRowContext(ctx, "SELECT id,name,email,created_at FROM users WHERE email=?", email)
	var u user.User
	if err := row.Scan(&u.ID, &u.Name, &u.Email, &u.CreatedAt); err != nil {
		return nil, err
	}
	return &u, nil
}
```

### 4.5 adapter/http/user_handler.go

```go
package http

import (
	"net/http"
	"my-service/internal/usecase"

	"github.com/gin-gonic/gin"
)

type UserHandler struct {
	uc *usecase.UserUsecase
}

func NewUserHandler(uc *usecase.UserUsecase) *UserHandler {
	return &UserHandler{uc: uc}
}

func (h *UserHandler) Create(c *gin.Context) {
	var req struct {
		Name  string `json:"name" binding:"required"`
		Email string `json:"email" binding:"required,email"`
	}
	if err := c.ShouldBindJSON(&req); err != nil {
		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
		return
	}
	u, err := h.uc.CreateUser(c.Request.Context(), req.Name, req.Email)
	if err != nil {
		c.JSON(mapErr(err)) // 统一错误映射
		return
	}
	c.JSON(http.StatusCreated, u)
}
```

### 4.6 cmd/api/main.go（装配）

```go
package main

import (
	"my-service/internal/adapter/http"
	"my-service/internal/app"
)

func main() {
	c := app.BuildContainer()         // 依赖注入/装配
	server := app.BuildHTTPServer(c)  // router + middleware
	server.Run()
}
```

---

## 5. 工程化配套（企业级“真正拉开差距”的地方）

### 5.1 统一构建入口：Makefile

```makefile
.PHONY: lint test build run gen

lint:
	golangci-lint run ./...

test:
	go test ./... -race -coverprofile=coverage.out

build:
	CGO_ENABLED=0 go build -o bin/api ./cmd/api

run:
	go run ./cmd/api

gen:
	buf generate api/proto
```

### 5.2 Lint / 规范

- 使用 `golangci-lint` 聚合常见静态检查。
- 代码风格追随 Uber Go Style Guide（错误处理、receiver 命名、减少嵌套、表驱动测试、显式依赖注入等）。 ([GitHub](https://github.com/uber-go/guide?utm_source=chatgpt.com "The Uber Go Style Guide. - GitHub"))

### 5.3 配置与环境

- `configs/` 放模板，实际运行时通过 ENV 覆盖（12-factor 思路）。
- 内部提供 `pkg/config` 统一加载 + 校验。

### 5.4 日志、指标、链路

- `pkg/logger` 统一结构化日志（zap/zerolog）。
- `infra/observability` 里封装 Prometheus metrics + OpenTelemetry tracing。
- 中间件负责注入 traceID/requestID。

### 5.5 CI/CD

- CI：lint → unit test → build → security scan → dockerize
- CD：helm/k8s 渐进发布 + 健康检查/回滚。
- 交付物放 `deployments/`。

---

## 6. 常见演进路线（你可以按阶段落地）

1. **单体服务阶段**：先按这套目录跑起来。
2. **多入口阶段**：新增 `cmd/worker`、`adapter/mq`。
3. **多模块阶段**：`domain/<bounded-context>` 拆聚合、用例拆包。
4. **服务化阶段**：`pkg/` 抽公共库，多 repo 或 mono-repo 都能适配。

---

## 7. 你可以直接复制的“企业级模板清单”

如果你想更快开干，建议在骨架里再补这几件事：

- `internal/pkg/errors`：统一错误码/错误栈
- `internal/pkg/middleware`：auth、rate limit、recover、trace
- `test/contract`：gRPC/HTTP 契约测试
- `docs/adr`：架构决策记录（ADR）
- `scripts/dev.sh`：本地一键启动依赖（db/redis/mq）

---
