食友 ShiYou

校园美食评价平台 — 后端服务

一个专注于校园美食发现与评价的社交平台后端，基于 Go + Gin 构建

特性 · 架构 · 快速开始 · API 接口 · 开发

---

特性

模块	功能
🔐 认证系统	手机号/邮箱注册登录、JWT 双 Token、图形/短信/邮件验证码
🏪 店铺管理	店铺 CRUD、待审核店铺、热度指数、评分统计
⭐ 评价系统	多维度评分、图片上传、点赞/评论/举报、审核流程
🏆 排行榜	学校/区域多维度排行、定时刷新、快照存储
👥 管理后台	RBAC 权限、操作日志、系统设置、评价审核
🔔 实时通知	WebSocket 推送、Redis Stream 消息队列
📍 地理位置	学校 GEO 定位、校门检测、距离计算

架构

┌─────────────────────────────────────────────────────────────┐
│                        Nginx                                │
│                   (反向代理 / SSL)                           │
└─────────────┬─────────────────┬─────────────────┬───────────┘
              │                 │                 │
              ▼                 ▼                 ▼
┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐
│   Web (Next.js)  │  │  Admin (Static)  │  │  API (Go:9090)   │
│      SSR         │  │                  │  │                  │
└──────────────────┘  └──────────────────┘  └────────┬─────────┘
                                                      │
                    ┌─────────────────────────────────┼─────────────┐
                    │                                 │             │
                    ▼                                 ▼             ▼
           ┌──────────────┐                 ┌──────────────┐ ┌──────────┐
           │   MySQL 8.0  │                 │   Redis 7.4  │ │  MinIO   │
           │  (主数据库)   │                 │  (缓存/MQ)   │ │ (对象存储)│
           └──────────────┘                 └──────────────┘ └──────────┘

项目结构

shiyou-server/
├── cmd/server/              # 服务入口
├── internal/
│   ├── api/v1/              # API 路由与控制器 (26 个模块)
│   ├── app/                 # 应用初始化 & 依赖装配
│   ├── jobs/                # 定时任务 (排行榜/注销/封禁)
│   ├── middleware/          # 中间件 (Auth/RBAC/CORS/Logger)
│   ├── model/               # 数据模型 (entity + dto)
│   ├── repository/          # 数据访问层 (MySQL + Redis)
│   └── service/             # 业务逻辑层
├── pkg/                     # 公共工具包
│   ├── bcrypt/              # 密码加密
│   ├── captcha/             # 验证码 (图形/短信/邮件)
│   ├── config/              # Viper 配置加载
│   ├── database/            # MySQL + Redis 连接
│   ├── errors/              # 统一错误处理
│   ├── jwt/                 # JWT Token 管理
│   ├── logger/              # Zap 结构化日志
│   ├── minio/               # MinIO 客户端
│   ├── mq/                  # Redis Stream 消息队列
│   ├── nearest/             # 地理位置计算
│   ├── response/            # 统一响应格式
│   ├── validator/           # 自定义校验器
│   └── websocket/           # WebSocket 管理
├── deploy/                  # 部署配置
├── Dockerfile               # 多阶段 Docker 构建
└── docker-compose.yml       # 服务编排

快速开始

环境要求

• Go 1.25+
• MySQL 8.0
• Redis 7.0+
• MinIO
• Docker & Docker Compose (可选)

方式一：本地开发

# 1. 克隆项目
git clone <your-repo-url>
cd shiyou-server

# 2. 配置环境变量
cp .env.example .env
# 编辑 .env 填写实际配置

# 3. 启动依赖服务
docker-compose up -d mysql redis minio

# 4. 启动服务
go run cmd/server/main.go

服务默认运行在 http://localhost:9090

方式二：Docker 部署

# 构建镜像
docker build -t shiyou-server:latest .

# 启动所有服务
docker-compose up -d

服务端口

服务	端口	说明
API 服务	9090	后端 API
MySQL	3306	数据库
Redis	6379	缓存
MinIO API	9000	对象存储
MinIO Console	9001	管理控制台
Nginx	80	HTTP 入口

⚙️ 配置

配置文件

配置文件位于 deploy/server/config.yaml：

server:
  addr: "0.0.0.0:9090"

app:
  name: "shiyou-server"
  version: "1.0.0"
  mode: "release"  # debug / release

database:
  mysql:
    host: "mysql"
    port: 3306
    database: "shiyou"
  redis:
    host: "redis"
    port: 6379
    db: 7

环境变量

通过 .env 文件配置敏感信息：

变量	说明
SHIYOU_DATABASE_MYSQL_PASSWORD	MySQL 密码
SHIYOU_JWT_ACCESS_TOKEN_SECRET	Access Token 密钥
SHIYOU_JWT_REFRESH_TOKEN_SECRET	Refresh Token 密钥
SHIYOU_MINIO_ACCESS_KEY	MinIO 访问密钥
SHIYOU_MINIO_SECRET_KEY	MinIO 密钥
SHIYOU_ALIYUN_ACCESS_KEY_ID	阿里云 AccessKey
SHIYOU_ALIYUN_ACCESS_KEY_SECRET	阿里云 Secret
SHIYOU_EMAIL_USERNAME	邮箱 SMTP 用户名
SHIYOU_EMAIL_PASSWORD	邮箱 SMTP 密码
SHIYOU_AMAP_KEY	高德地图 API Key

📡 API 接口

基础路径：/api/v1

公开接口

Method	Path	说明
GET	/health	健康检查
POST	/auth/register	用户注册
POST	/auth/login	用户登录
GET	/graph/captcha	获取图形验证码
POST	/sms/captcha	发送短信验证码
POST	/email/captcha	发送邮件验证码

用户接口 (需登录)

Method	Path	说明
GET	/user/profile	获取用户信息
PUT	/user/profile	更新用户信息
GET	/shops	获取店铺列表
GET	/shops/:id	获取店铺详情
POST	/reviews	发布评价
GET	/reviews	获取评价列表
GET	/ranking	获取排行榜

管理后台接口 (需管理员认证)

Method	Path	说明
POST	/admin/auth/login	管理员登录
GET	/admin/users	用户管理
GET	/admin/shops	店铺管理
GET	/admin/reviews	评价管理
POST	/admin/reviews/:id/audit	评价审核

完整 API 文档请参考代码中的路由定义

⏰ 定时任务

任务	间隔	说明
热度分刷新	30 分钟	刷新评价热度分
店铺统计刷新	30 分钟	刷新热度指数和评分
用户注销清理	5 分钟	处理注销用户数据
封禁解封检查	5 分钟	自动解封到期用户
排行榜刷新	可配置	定时刷新排行榜快照

🧪 测试

# 运行所有测试
go test ./...

# 运行特定模块测试
go test ./internal/repository/...

# 运行测试并显示覆盖率
go test ./... -cover

🛠️ 开发

代码规范

• 使用 gofmt 格式化代码
• 提交前运行 go vet ./...
• 遵循 Go 标准代码规范

数据库迁移

启动时自动执行 GORM AutoMigrate，新增字段会自动同步。

贡献指南

1. Fork 本仓库
2. 创建你的特性分支 (git checkout -b feature/AmazingFeature)
3. 提交你的更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 打开一个 Pull Request

📄 License

MIT License © ShiYou Team

---

如果觉得有用，请给个 ⭐ Star 支持一下！