fish/trading_assistant
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

add

Browse Source
This commit is contained in:
vipg
2026-02-06 15:23:41 +08:00
parent bd9d561426
commit 7c911595b3
1 changed files with 405 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

406
README.md
View File

@@ -1,2 +1,406 @@
# trading_assistant
# 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封装所有操作，降低团队协作成本。整体结构轻量、可扩展，无需过度设计，完全匹配任务要求。