# Top Fans Backend

微服务后端项目，使用 Go 1.25.5 和 gRPC。

## 项目架构

- **UserSocialService**: 用户与社交服务（用户、社交、展位、任务）
- **AssetChainService**: 资产与链服务
- **Gateway**: API 网关（REST API）

## 环境要求

- Go 1.25.5
- Protocol Buffers Compiler (protoc) 3.x+
- Make

## 快速开始

### 1. 安装 Go 环境

```bash
# 使用 Homebrew (macOS)
brew install go@1.25.5

# 或从官网下载
# https://go.dev/dl/
```

### 2. 配置环境

运行安装脚本：

```bash
chmod +x scripts/setup.sh
./scripts/setup.sh
```

或手动安装：

```bash
# 设置 Go 代理（可选，加速下载）
export GOPROXY=https://goproxy.cn,direct

# 下载依赖
go mod download
go mod tidy

# 安装 protoc 插件
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
go install github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-grpc-gateway@latest
go install github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv2@latest

# 安装 googleapis
go get github.com/googleapis/googleapis
```

### 3. 安装 Protocol Buffers

```bash
# macOS
brew install protobuf

# Linux (Ubuntu/Debian)
apt-get install protobuf-compiler

# Linux (CentOS/RHEL)
yum install protobuf-compiler
```

### 4. 生成代码

```bash
# 生成 gRPC 代码
make proto

# 生成 REST API 代码和 Swagger 文档
make swagger

# 生成所有代码
make all
```

## 项目结构

```
backend/
├── api/
│   └── gateway/          # 生成的 REST API Gateway 代码
├── pkg/
│   └── proto/            # 生成的 gRPC 代码
├── proto/                # Proto 定义文件
│   ├── common.proto
│   ├── user.proto
│   └── asset-chain.proto
├── swagger/              # Swagger 文档
├── scripts/              # 脚本文件
├── go.mod                # Go 模块定义
├── go.work               # Go 工作区配置
├── Makefile              # 构建脚本
└── README.md
```

## 开发工具

### 代码检查

项目使用 golangci-lint 进行代码检查：

```bash
# 安装 golangci-lint
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

# 运行检查
golangci-lint run
```

### 代码格式化

```bash
# 格式化代码
go fmt ./...

# 整理 imports
goimports -w .
```

## 依赖管理

主要依赖：

- `google.golang.org/protobuf`: Protocol Buffers Go 支持
- `google.golang.org/grpc`: gRPC 框架
- `github.com/grpc-ecosystem/grpc-gateway/v2`: gRPC 到 REST 的转换
- `github.com/gin-gonic/gin`: HTTP Web 框架
- `github.com/googleapis/googleapis`: Google API 定义

## Makefile 命令

```bash
make help          # 显示帮助信息
make proto         # 生成 gRPC 代码
make swagger       # 生成 REST API 代码和 Swagger 文档
make all           # 生成所有代码
make clean-proto   # 清理生成的 proto 代码
make clean-swagger # 清理生成的 gateway 代码和 swagger
make clean         # 清理所有生成的代码
```

## 版本管理

- Go 版本: 1.25.5 (在 `.go-version` 文件中指定)
- 使用 Go Workspace 模式管理多模块项目

## 注意事项

1. 生成的代码（`pkg/proto`、`api/gateway`）不要手动修改
2. 修改接口时，先更新 `.proto` 文件，再运行 `make all` 重新生成
3. 确保 `GOPATH/bin` 在 `PATH` 中，以便使用 protoc 插件

## 问题排查

### protoc 插件未找到

确保 `$GOPATH/bin` 或 `$HOME/go/bin` 在 PATH 中：

```bash
export PATH=$PATH:$(go env GOPATH)/bin
```

### googleapis 未找到

```bash
go get github.com/googleapis/googleapis
```

### 生成代码失败

检查 protoc 版本：

```bash
protoc --version  # 应该是 3.x 版本
```

## 许可证

[添加许可证信息]