# Go Monorepo 目录结构设计
适配小团队开发，满足**业务独立部署、发布互不影响**，基于`docker compose`实现一键发布，遵循**轻量设计、无过度封装**原则，整体结构兼顾可维护性和开发效率，各业务模块解耦且资源可复用。

## 核心设计思路
1. **单仓库多业务**：所有代码归拢在一个monorepo，团队协作更便捷；
2. **业务模块独立**：每个业务单独放在`services/`下，拥有独立的Go代码、配置、Dockerfile、docker-compose子配置，做到独立构建/部署/发布；
3. **公共资源复用**：抽离公共库、工具、中间件配置，避免重复开发，公共代码变更需做兼容性保证（不影响各业务）；
4. **根目录一键部署**：通过根目录`docker-compose.yml`聚合所有业务，支持**全局启动**或**单独启动某一个业务**，满足团队开发/生产不同场景。

---

# 最终目录结构
```
go-monorepo/
├── Makefile                  # 全局快捷命令（构建、启动、停止、日志等，简化团队操作）
├── docker-compose.yml        # 根级compose，聚合所有业务，支持独立启动单个服务
├── .env                      # 全局环境变量（数据库、Redis等公共中间件地址，团队统一配置）
├── .gitignore                # git忽略规则（go编译产物、docker日志、.env等）
├── go.work                   # Go 1.18+ 工作区文件，管理多模块，实现monorepo依赖管理
├── go.work.sum               # 工作区依赖校验文件
├── common/                   # 公共复用模块（所有业务均可依赖，团队统一维护，保证通用性）
│   ├── go.mod                # 公共模块的mod文件（模块名：go-monorepo/common）
│   ├── go.sum
│   ├── db/                   # 公共数据库封装（PostgresSQL连接、基础CRUD，轻量无过度封装）
│   │   ├── postgres.go
│   │   └── options.go
│   ├── redis/                # 公共Redis封装（连接池、基础操作）
│   │   └── redis.go
│   ├── logger/               # 公共日志（zap轻量封装，统一日志格式）
│   │   └── logger.go
│   ├── utils/                # 公共工具函数（加密、时间、字符串等）
│   │   └── common.go
│   └── middleware/           # 公共中间件（HTTP跨域、限流、日志，Gin适配）
│       └── cors.go
├── services/                 # 业务服务根目录（每个子目录是一个独立业务，可单独部署）
│   ├── user/                 # 业务1：用户服务（示例，团队可按业务拆分，如order/pay/user）
│   │   ├── go.mod            # 独立mod文件（依赖根目录common，模块名：go-monorepo/services/user）
│   │   ├── go.sum
│   │   ├── main.go           # 服务入口（Gin/GRPC均可，示例用Gin）
│   │   ├── conf/             # 业务独立配置（可覆盖全局.env，支持多环境）
│   │   │   └── config.go
│   │   ├── api/              # 接口层（HTTP路由、请求响应体）
│   │   │   └── user_api.go
│   │   ├── service/          # 业务逻辑层
│   │   │   └── user_service.go
│   │   ├── dao/              # 数据访问层（操作PostgresSQL，依赖common/db）
│   │   │   └── user_dao.go
│   │   ├── model/            # 数据模型（数据库表结构、结构体）
│   │   │   └── user_model.go
│   │   ├── Dockerfile        # 业务独立Dockerfile（单独构建镜像，不影响其他业务）
│   │   └── docker-compose.yml # 业务独立compose（单独部署时使用，仅包含自身+依赖的中间件）
│   ├── order/                # 业务2：订单服务（和user服务结构完全一致，独立部署）
│   │   ├── [结构同user服务]
│   └── pay/                  # 业务3：支付服务（团队可一人负责一个核心业务，完美适配）
│       ├── [结构同user服务]
├── deploy/                   # 部署相关资源（非必须，可放公共配置、初始化脚本）
│   ├── postgres/             # PostgresSQL初始化（建库、建表、初始化数据脚本）
│   │   └── init.sql
│   └── redis/                # Redis初始化（可选，配置文件、持久化脚本）
│       └── redis.conf
└── logs/                     # 全局日志目录（docker挂载，所有服务日志统一存放，便于排查）
    └── .gitkeep
```

---

# 关键文件说明（核心实现，保证独立部署+复用）
## 1. Go工作区文件 `go.work`（monorepo核心）
Go 1.18+ 引入的**工作区模式**是实现monorepo的关键，无需将common发布到私服，本地即可实现多模块依赖，且每个业务模块独立管理自身依赖。  
**go.work 内容**：
```go
go 1.21  // 建议使用稳定版Go，团队统一版本

// 加入公共模块
use ./common

// 加入所有业务服务模块（新增业务时只需追加一行）
use ./services/user
use ./services/order
use ./services/pay
```
**作用**：所有模块在同一个工作区，业务服务可直接通过`import "go-monorepo/common/xxx"`依赖公共库，本地开发无需手动`go mod replace`，团队协作无依赖问题。

## 2. 公共模块 `common/go.mod`（轻量封装，无过度设计）
仅声明公共依赖，暴露简单接口，不做复杂业务封装，示例：
```go
module go-monorepo/common

go 1.21

require (
	github.com/gin-gonic/gin v1.9.1
	github.com/jmoiron/sqlx v1.3.5
	github.com/redis/go-redis/v9 v9.3.0
	go.uber.org/zap v1.26.0
	github.com/lib/pq v1.10.9 // PostgresSQL驱动
)

require (
	// 间接依赖（go mod tidy 自动生成）
)
```

## 3. 业务模块 `services/user/go.mod`（独立依赖，发布不影响其他业务）
业务模块仅依赖自身需要的包+公共模块，**每个业务的mod独立管理**，升级依赖/修改代码不会影响其他业务，示例：
```go
module go-monorepo/services/user

go 1.21

// 依赖本地公共模块（工作区模式下，无需指定版本）
require go-monorepo/common v0.0.0-00010101000000-000000000000

// 业务自身的依赖（仅引入当前业务需要的，按需添加）
require (
	github.com/gin-gonic/gin v1.9.1
	github.com/joho/godotenv v1.5.1 // 环境变量解析
)

// 工作区模式下的本地依赖映射（go work sync 自动生成，无需手动修改）
replace go-monorepo/common => ../../common
```
**关键**：新增/升级业务依赖仅修改当前业务的`go.mod`，其他业务不受影响，实现**发布隔离**。

## 4. 业务独立Dockerfile（`services/user/Dockerfile`）
轻量多阶段构建，仅构建当前业务，镜像体积小，独立构建不影响其他业务，**所有业务的Dockerfile格式统一**（团队规范），示例：
```dockerfile
# 构建阶段
FROM golang:1.21-alpine AS builder
WORKDIR /app
# 复制当前业务的代码（仅复制user目录，不涉及其他业务）
COPY . .
# 设置Go代理，加速构建
ENV GOPROXY=https://goproxy.cn,direct
# 编译（静态编译，无系统依赖）
RUN go build -ldflags="-s -w" -o user-server main.go

# 运行阶段（使用alpine基础镜，体积仅数MB）
FROM alpine:3.19
WORKDIR /app
# 从构建阶段复制编译产物
COPY --from=builder /app/user-server .
# 复制业务配置（可选）
COPY --from=builder /app/conf ./conf
# 暴露业务端口（user服务示例用8080，order可8081，pay可8082，互不冲突）
EXPOSE 8080
# 启动命令
CMD ["./user-server"]
```
**特点**：每个业务单独构建镜像，镜像名区分（如`go-monorepo-user:latest`），发布时仅推送当前业务的镜像即可。

## 5. 根目录`docker-compose.yml`（聚合所有业务，支持独立启动）
核心满足**全局启动所有服务**/**单独启动某一个业务**，所有中间件（PostgresSQL/Redis）全局共享（团队无需为每个业务单独部署中间件），通过`depends_on`控制依赖关系，**业务服务之间通过服务名访问**（如user服务访问order服务：`http://order:8081`）。  
**核心内容**：
```yaml
version: '3.8' # 兼容主流Docker版本
services:
  # 公共中间件：PostgresSQL（所有业务共享，团队统一管理）
  postgres:
    image: postgres:16-alpine
    container_name: monorepo-postgres
    environment:
      POSTGRES_USER: ${PG_USER:-root}
      POSTGRES_PASSWORD: ${PG_PWD:-123456}
      POSTGRES_DB: ${PG_DB:-monorepo}
    ports:
      - "${PG_PORT:-5432}:5432"
    volumes:
      - ./deploy/postgres/init.sql:/docker-entrypoint-initdb.d/init.sql # 初始化脚本
      - pg_data:/var/lib/postgresql/data # 数据持久化
    networks:
      - monorepo-net
    restart: always

  # 公共中间件：Redis（所有业务共享）
  redis:
    image: redis:7-alpine
    container_name: monorepo-redis
    ports:
      - "${REDIS_PORT:-6379}:6379"
    volumes:
      - ./deploy/redis/redis.conf:/etc/redis/redis.conf
      - redis_data:/data
    command: redis-server /etc/redis/redis.conf
    networks:
      - monorepo-net
    restart: always

  # 业务服务1：用户服务
  user:
    build:
      context: ./services/user # 仅构建user目录，独立构建
      dockerfile: Dockerfile
    container_name: monorepo-user
    environment:
      - GIN_MODE=release
      - PG_ADDR=postgres:5432 # 访问公共PG，通过服务名
      - REDIS_ADDR=redis:6379 # 访问公共Redis
    ports:
      - "8080:8080"
    volumes:
      - ./logs/user:/app/logs # 日志挂载到本地
    networks:
      - monorepo-net
    restart: always
    depends_on:
      - postgres
      - redis
    # 可选：限制资源（团队开发/测试环境，避免单个服务占满资源）
    deploy:
      resources:
        limits:
          cpus: "0.5"
          memory: "512M"

  # 业务服务2：订单服务（和user服务结构一致，独立部署）
  order:
    build:
      context: ./services/order
      dockerfile: Dockerfile
    container_name: monorepo-order
    environment:
      - GIN_MODE=release
      - PG_ADDR=postgres:5432
      - REDIS_ADDR=redis:6379
    ports:
      - "8081:8081"
    volumes:
      - ./logs/order:/app/logs
    networks:
      - monorepo-net
    restart: always
    depends_on:
      - postgres
      - redis
    deploy:
      resources:
        limits:
          cpus: "0.5"
          memory: "512M"

  # 业务服务3：支付服务（独立部署）
  pay:
    build:
      context: ./services/pay
      dockerfile: Dockerfile
    container_name: monorepo-pay
    environment:
      - GIN_MODE=release
      - PG_ADDR=postgres:5432
      - REDIS_ADDR=redis:6379
    ports:
      - "8082:8082"
    volumes:
      - ./logs/pay:/app/logs
    networks:
      - monorepo-net
    restart: always
    depends_on:
      - postgres
      - redis
    deploy:
      resources:
        limits:
          cpus: "0.5"
          memory: "512M"

# 全局网络：所有服务在同一个网络，通过服务名互通
networks:
  monorepo-net:
    driver: bridge

# 全局数据卷：中间件数据持久化，不会随容器删除
volumes:
  pg_data:
  redis_data:
```

## 6. 业务独立`docker-compose.yml`（`services/user/docker-compose.yml`）
满足**单独部署某一个业务**的场景（如仅修改了user服务，只需发布user，无需启动其他业务），仅包含当前业务+必要的中间件（也可连接外部已有的中间件），示例：
```yaml
version: '3.8'
services:
  user:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: standalone-user
    environment:
      - GIN_MODE=release
      - PG_ADDR=192.168.1.100:5432 # 可连接外部PG/Redis，无需启动本地中间件
      - REDIS_ADDR=192.168.1.100:6379
    ports:
      - "8080:8080"
    volumes:
      - ../../logs/user:/app/logs
    restart: always
networks:
  default:
    driver: bridge
```

## 7. 全局Makefile（简化团队操作，避免记复杂命令）
团队统一使用Makefile命令，降低操作成本，**所有命令支持全局/单独业务执行**，示例：
```makefile
# 全局启动所有服务（中间件+所有业务）
up:
	docker compose up -d

# 单独启动某一个业务（如user，make up-svc svc=user）
up-svc:
	docker compose up -d $(svc)

# 全局停止所有服务
down:
	docker compose down

# 单独停止某一个业务
down-svc:
	docker compose stop $(svc)

# 构建所有业务镜像
build:
	docker compose build

# 单独构建某一个业务镜像（核心：发布时仅构建当前业务）
build-svc:
	docker compose build $(svc)

# 查看所有服务日志
logs:
	docker compose logs -f

# 查看某一个业务日志
logs-svc:
	docker compose logs -f $(svc)

# 重新启动某一个业务（修改代码后，一键重启）
restart-svc:
	docker compose restart $(svc)

# 清理无用镜像/容器（团队开发环境，定期清理）
clean:
	docker system prune -f

# 初始化Go工作区（新成员拉取代码后，一键执行）
go-init:
	go work init
	go work use ./common
	go work use ./services/user
	go work use ./services/order
	go work use ./services/pay
	go mod tidy
```
**团队使用示例**：
- 新成员拉取代码：`make go-init`（初始化Go工作区，解决依赖）
- 开发用户服务：`make build-svc svc=user && make up-svc svc=user`（仅构建+启动user服务）
- 发布订单服务：`make build-svc svc=order && make restart-svc svc=order`（仅构建+重启order服务，不影响user/pay）
- 全局启动所有服务（测试环境）：`make up`

---

# 团队开发&发布流程（适配团队）
## 开发流程（一人负责一个核心业务，互不干扰）
1. 拉取monorepo代码：`git clone <仓库地址> && cd go-monorepo && make go-init`；
2. 开发各自业务（如A开发user，B开发order，C开发pay），仅修改`services/[自己的业务]`目录下的代码；
3. 公共代码修改（如common/logger）：需团队沟通，保证兼容性（不修改现有接口，仅新增），避免影响其他业务；
4. 本地测试：使用`make build-svc svc=xxx && make up-svc svc=xxx`仅启动自己的业务，快速验证。

## 发布流程（业务独立发布，不影响其他服务）
### 生产/测试环境发布单个业务（核心需求）
```bash
# 1. 拉取最新代码（仅拉取，不影响运行中的服务）
git pull origin main

# 2. 仅构建当前业务的镜像（如发布pay服务）
make build-svc svc=pay

# 3. 仅重启当前业务容器（秒级重启，不影响其他服务）
make restart-svc svc=pay
```
### 首次部署/全局发布（如测试环境初始化）
```bash
make go-init && make build && make up
```

---

# 关键满足点验证
1. ✅ **无需过度封装**：common仅做轻量基础封装，无业务逻辑，业务模块结构简单（api/service/dao/model四层，团队易理解）；
2. ✅ **业务独立部署**：每个业务有独立Dockerfile、compose，支持`make up-svc svc=xxx`单独启动，也可通过业务目录下的compose单独部署；
3. ✅ **发布互不影响**：发布时仅构建/重启当前业务镜像，其他业务容器正常运行，公共代码变更做兼容性保证；
4. ✅ **docker compose发布**：根目录compose聚合所有服务，支持全局/单独发布，Makefile封装所有命令，团队使用便捷；
5. ✅ **团队适配**：一人一个核心业务，目录结构清晰，公共代码统一维护，开发/发布命令简化，无复杂配置。

---

# 扩展建议（团队可按需添加，不影响现有结构）
1. **新增业务**：在`services/`下新建业务目录，复制user服务的基础结构（go.mod、Dockerfile、目录分层），在`go.work`和根`docker-compose.yml`中追加一行，即可实现独立部署；
2. **多环境配置**：在各业务`conf/`下添加`dev/ prod/ test`目录，通过环境变量`ENV=prod`指定配置文件，根`.env`区分不同环境的变量；
3. **接口文档**：在各业务`api/`下添加`swagger/`目录，使用`swag init`生成接口文档，独立访问（如user服务：`http://localhost:8080/swagger/index.html`）；
4. **监控告警**：根`docker-compose.yml`中新增Prometheus+Grafana服务，所有业务暴露metrics接口，统一监控（轻量配置，团队易维护）；
5. **代码规范**：添加`golangci-lint`配置文件（.golangci.yml），团队提交代码前执行`golangci-lint run`，保证代码风格统一。

### 总结
本次设计的Go Monorepo核心围绕**小团队高效开发**和**业务独立部署发布**，通过Go工作区实现monorepo依赖管理，以`services/`为业务隔离边界，结合Docker和docker compose实现**独立构建、独立发布、全局聚合**，同时通过Makefile封装所有操作，降低团队协作成本。整体结构轻量、可扩展，无需过度设计，完全匹配任务要求。