249 lines
6.7 KiB
Markdown
249 lines
6.7 KiB
Markdown
# 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. 环境变量配置 ⚠️
|
||
|
||
**本项目有两套互相独立的配置文件,设计上是"二选一"关系,不要混用:**
|
||
|
||
| 文件 | 用途 | 何时生效 |
|
||
| --- | --- | --- |
|
||
| `backend/.env` | **Dev(本机开发)** 配置 | `./backend/dev.sh` 自动 source |
|
||
| `backend/deploy/envs/*.env` | **生产多机部署** 配置(每个服务一份) | 仅在目标服务器上由 systemd / docker / 部署脚本 source |
|
||
|
||
**为什么不能混用** — 同一个变量在两套里值不同,后者会覆盖前者:
|
||
|
||
| 变量 | `backend/.env`(dev) | `deploy/envs/gateway.env`(生产) | 混用后果 |
|
||
| --- | --- | --- | --- |
|
||
| `JWT_SECRET` | `topfans-secret-key-please-change-in-production` | `your_secure_jwt_secret_here` | 所有 token 校验失败,需要登录的接口 401 |
|
||
| `DUBBO_GALLERY_SERVICE_URL` | `tri://127.0.0.1:20004` | `tri://localhost:20001` | 调用 gallery 服务的接口连接失败 |
|
||
| `DUBBO_ACTIVITY_SERVICE_URL` | `tri://127.0.0.1:20005` | `tri://localhost:20004` | 调用 activity 服务的接口连接失败 |
|
||
| `OSS_ACCESS_KEY_ID` | `LTAI5t99tafzfyrzbbEbjryH` | `LTAI5t6QcdJHpYbCPxM8SXYE` | OSS 上传/下载 403 |
|
||
| `DB_USER` / `DB_PASSWORD` | `postgres` / `123456` | `haihuizhu` / `admin` | 启动期就连不上 DB |
|
||
| `ENV` | `development` | `production` | 日志格式、限流策略等会按生产行为跑 |
|
||
|
||
**dev.sh 当前的加载规则**(见 `dev.sh:load_service_env`):
|
||
|
||
- `dev.sh` 启动时**只** source `backend/.env`
|
||
- 启动每个服务前,按服务名(去掉 `Service` 后缀)source 对应的 `deploy/envs/<name>.env`,**但仅对 `userService`** 生效
|
||
- `userService` 之所以特殊:它的 `deploy/envs/user.env` 里有 `SMS_ACCESS_KEY_ID` / `SMS_ACCESS_KEY_SECRET` 等 `backend/.env` 没有的变量,需要叠加
|
||
- **其他服务不再 source `deploy/envs/`** — 否则会被生产端口/密钥覆盖 dev 端口/密钥,导致接口大面积失败(典型症状:token 401、Dubbo 调用超时、OSS 403)
|
||
|
||
**生产部署时**(由部署脚本负责,与 dev.sh 无关):
|
||
|
||
- 把对应服务的 `deploy/envs/<name>.env` 放到目标服务器的 `/etc/topfans/<name>.env`
|
||
- systemd unit / docker-compose 引用该文件
|
||
- **不要** source `backend/.env`
|
||
|
||
**新增配置项时的纪律:**
|
||
|
||
1. 如果是 dev 和生产都需要的(如 `DB_*`、Dubbo URL 模板),在 `backend/.env` 改 + 在 `deploy/envs/*.env` 同步改
|
||
2. 如果仅生产需要(如 `SMS_*`、OSS 角色),只改 `deploy/envs/<name>.env`
|
||
3. 如果仅 dev 需要(如本地 mock 开关),只改 `backend/.env`
|
||
4. 改完后,在 dev 环境跑一次 `./dev.sh` 验证没有端口/密钥错乱
|
||
|
||
---
|
||
|
||
### 5. 生成代码
|
||
|
||
```bash
|
||
# 生成 gRPC 代码
|
||
make proto
|
||
|
||
# 生成 REST API 代码和 Swagger 文档
|
||
make swagger
|
||
|
||
# 生成所有代码
|
||
make all
|
||
```
|
||
|
||
### 6. 启动服务
|
||
|
||
```bash
|
||
# 一键启动所有服务(带文件热更新)
|
||
./dev.sh
|
||
|
||
# 或者只跑某个服务(略)
|
||
# 详见 dev.sh 注释
|
||
```
|
||
|
||
启动后会监听:
|
||
|
||
- Gateway: http://localhost:8080
|
||
- UserService: tri://localhost:20000
|
||
- Swagger UI: http://localhost:8080/swagger/index.html
|
||
|
||
> ⚠️ 启动前确认 `backend/.env` 里的 `DB_HOST/REDIS_HOST` 在本机能通(默认 `localhost`)。如果用远程 DB/Redis,改 `backend/.env` 而不是 `deploy/envs/*.env`。
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
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 版本
|
||
```
|
||
|
||
## 许可证
|
||
|
||
[添加许可证信息]
|
||
|