# HappyMall

**Repository Path**: monkeyPP/happy-mall

## Basic Information

- **Project Name**: HappyMall
- **Description**: 快乐商场
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-07-13
- **Last Updated**: 2025-08-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Happy Mall Monorepo

> 🛍️ 一个基于 Go 语言的现代化电商微服务系统

[![Go Version](https://img.shields.io/badge/Go-1.24+-blue.svg)](https://golang.org)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![CI](https://img.shields.io/badge/CI-GitHub%20Actions-blue.svg)](/.github/workflows)

## 🎯 项目简介

Happy Mall 是一个采用 **Monorepo + Go Workspace** 架构的微服务电商系统，包含用户服务、订单服务、产品服务等多个微服务。项目采用领域驱动设计（DDD）和清洁架构，支持 HTTP 和 gRPC 双协议通信。

### ✨ 特色亮点

- 🏗️ **Go Workspace 架构**：每个服务独立的 go.mod 模块，统一的开发体验
- 📦 **模块化设计**：清晰的模块边界，独立的依赖管理
- 🚀 **微服务友好**：支持独立构建、测试和部署
- 🛠️ **开发工具完善**：统一的 Makefile，自动化脚本

## 🏗️ 架构概览

### Go Workspace 模块结构

```
happy-mall/
├── go.work                    # Go workspace 配置
├── services/                  # 微服务模块
│   ├── userservice/
│   │   ├── go.mod            # 独立模块
│   │   ├── cmd/main.go       # 服务入口
│   │   └── internal/         # 服务实现
│   ├── orderservice/
│   │   ├── go.mod            # 独立模块
│   │   └── cmd/main.go
│   └── productservice/
│       ├── go.mod            # 独立模块
│       └── cmd/main.go
├── pkg/                      # 共享基础库模块
│   ├── go.mod
│   ├── config/              # 配置管理
│   ├── log/                 # 日志组件
│   └── middleware/          # 中间件
├── shared/                   # 共享业务代码模块
│   ├── go.mod
│   └── types/               # 通用类型
├── api/                      # API 定义模块
│   ├── go.mod
│   ├── userservice/proto/    # 用户服务 API
│   ├── orderservice/proto/   # 订单服务 API
│   └── productservice/proto/ # 产品服务 API
├── tools/                    # 开发工具
├── deployments/              # 部署配置
└── tests/                    # 集成测试
```

### 模块依赖关系

```mermaid
graph TD
    A[services/userservice] --> B[pkg]
    A --> C[shared]
    A --> D[api]
    E[services/orderservice] --> B
    E --> C
    E --> D
    F[services/productservice] --> B
    F --> C
    F --> D
    C --> B
```

## 🚀 快速开始

### 1. 环境准备

确保已安装以下工具：

- **Go 1.24+**
- **Docker & Docker Compose**
- **Git**

### 2. 克隆仓库

```bash
git clone https://github.com/your-org/happy-mall.git
cd happy-mall
```

### 3. 初始化 Go Workspace

```bash
# 安装开发工具
make install-tools

# 同步 workspace（如果需要）
go work sync

# 整理所有模块依赖
make tidy
```

这将自动安装所有必需的开发工具：

- golangci-lint (代码检查)
- buf (Protocol Buffers)
- migrate (数据库迁移)
- air (热重载)
- wire (依赖注入)

### 🔧 Go Workspace 说明

项目使用 Go 1.18+ 的 workspace 功能：
- 每个服务都有独立的 `go.mod` 文件
- 共享模块（pkg、shared、api）也有独立的 `go.mod`
- `go.work` 文件管理所有模块的协同开发
- 支持跨模块开发和调试

> 📚 详细的 workspace 使用指南请参考：[Go Workspace 使用指南](./docs/go-workspace-guide.md)

### 4. 启动开发环境

```bash
# 启动基础设施 (数据库、Redis、监控等)
make dev-compose

# 构建所有服务
make build

# 运行用户服务
make run-userservice
```

### 5. 验证服务

```bash
# 健康检查
curl http://localhost:8000/healthz

# gRPC 反射 (如果启用)
grpcurl -plaintext localhost:9000 list
```

## 🛠️ 开发指南

### 构建和测试

```bash
# 构建所有服务
make build

# 构建特定服务
make build-userservice

# 运行测试
make test

# 运行特定服务的测试
make test-userservice

# 代码格式化
make format

# 代码检查
make lint
```

### 代码生成

```bash
# 生成所有代码 (Proto, Swagger 等)
make generate

# 只生成 gRPC 代码
make proto-gen

# 只生成 Swagger 文档
make swagger-gen
```

### Docker 相关

```bash
# 构建所有服务的 Docker 镜像
make docker-build

# 构建特定服务的镜像
make docker-build-userservice

# 启动完整的开发环境
make dev-compose

# 停止开发环境
make dev-compose-down
```

## 📋 服务列表

| 服务           | HTTP 端口 | gRPC 端口 | 状态      | 描述         |
| -------------- | --------- | --------- | --------- | ------------ |
| userservice    | 8000      | 9000      | ✅ 已实现 | 用户管理服务 |
| orderservice   | 8001      | 9001      | 🚧 开发中 | 订单管理服务 |
| productservice | 8002      | 9002      | 🚧 开发中 | 产品管理服务 |

### 监控和工具

| 服务       | 端口 | 描述       |
| ---------- | ---- | ---------- |
| Prometheus | 9090 | 指标监控   |
| Grafana    | 3000 | 监控仪表板 |
| PostgreSQL | 5432 | 主数据库   |
| Redis      | 6379 | 缓存和会话 |

## 🔧 配置管理

每个服务都有自己的配置文件，位于 `services/{service}/configs/` 目录：

```yaml
# services/userservice/configs/config.yaml
server:
  http:
    port: 8000
  grpc:
    port: 9000
database:
  host: localhost
  port: 5432
  name: happy_mall_user
```

支持通过环境变量覆盖配置：

```bash
export DATABASE_HOST=prod-db.example.com
export REDIS_HOST=prod-redis.example.com
```

## 🧪 测试

### 单元测试

```bash
# 运行所有单元测试
make test

# 运行特定服务的测试
make test-userservice

# 生成测试覆盖率
go test ./services/userservice/... -coverprofile=coverage.out
```

### 集成测试

```bash
# 运行集成测试
make test-integration

# 运行端到端测试
make test-e2e
```

## 📊 数据库管理

```bash
# 运行数据库迁移
make migrate-up

# 回滚迁移
make migrate-down

# 创建新的迁移文件
migrate create -ext sql -dir migrations -seq create_users_table
```

## 🐳 容器化部署

### 本地开发

```bash
# 启动开发环境
make dev-compose

# 查看日志
docker-compose -f deployments/docker-compose/docker-compose.dev.yaml logs -f
```

### 生产部署

```bash
# 构建生产镜像
make docker-build

# 使用 Kubernetes 部署
kubectl apply -f deployments/kubernetes/
```

## 📈 监控和可观测性

### Prometheus 指标

访问 http://localhost:9090 查看 Prometheus 控制台

### Grafana 仪表板

- URL: http://localhost:3000
- 用户名: admin
- 密码: admin

### 链路追踪

项目支持 Jaeger 链路追踪，在配置中启用：

```yaml
tracing:
  enabled: true
  endpoint: "http://localhost:14268/api/traces"
```

## 🤝 贡献指南

1. Fork 项目
2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'Add some amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 开启 Pull Request

### 代码规范

- 使用 `gofmt` 格式化代码
- 遵循 `golangci-lint` 规则
- 编写有意义的提交信息
- 添加必要的测试

## 📝 API 文档

### REST API

各服务的 REST API 文档：

- [用户服务 API](./api/userservice/openapi/openapi.yaml)
- [订单服务 API](./api/orderservice/openapi/openapi.yaml)
- [产品服务 API](./api/productservice/openapi/openapi.yaml)

### gRPC API

gRPC 服务定义：

- [用户服务 Proto](./api/userservice/proto/user.proto)
- [订单服务 Proto](./api/orderservice/proto/order.proto)
- [产品服务 Proto](./api/productservice/proto/product.proto)

## 🔍 故障排除

### 常见问题

**问题**: 服务启动失败

```bash
# 检查端口是否被占用
netstat -tulpn | grep :8000

# 检查 Docker 容器状态
docker ps -a
```

**问题**: gRPC 连接失败

```bash
# 测试 gRPC 连接
grpcurl -plaintext localhost:9000 list

# 检查防火墙设置
```

**问题**: 数据库连接失败

```bash
# 检查数据库状态
make health-check

# 重置数据库
make dev-compose-down
make dev-compose
```

## 📚 学习资源

- [Go 微服务最佳实践](https://github.com/golang-standards/project-layout)
- [gRPC 官方文档](https://grpc.io/docs/)
- [领域驱动设计](https://domain-driven-design.org/)
- [Clean Architecture](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html)

## 📄 许可证

本项目采用 MIT 许可证。详见 [LICENSE](LICENSE) 文件。

## 🙏 致谢

感谢所有为此项目贡献代码和建议的开发者！

---

<div align="center">

**[🏠 返回顶部](#happy-mall-monorepo)**

Made with ❤️ by Happy Mall Team

</div>