南海呈森网

一个基于 Go 语言开发的二手市场电商平台后端系统

一个基于 Go 语言开发的二手市场电商平台后端系统

大家好，我是码农先森。

📋 项目简介

这是一个基于 Go 语言开发的二手市场电商平台后端系统，提供完整的 C2C 交易功能，包括用户管理、商品发布、交易订单、支付系统、评价系统、纠纷处理、即时通讯等核心功能。系统采用 RESTful API 设计，支持 JWT 认证。

项目地址：https://github.com/rrruan-zx/second-hand-market

核心特性

  • ✅ 完整的电商功能: 商品管理、交易流程、支付系统
  • ✅ 双重角色支持: 用户可同时作为买家和卖家
  • ✅ 安全认证: JWT Token 认证，支持权限控制
  • ✅ 管理后台: 完善的平台管理功能
  • ✅ 纠纷处理: 完整的交易纠纷申诉和仲裁机制
  • ✅ 即时通讯: 买卖双方在线沟通
  • ✅ 支付集成: 支持支付宝和微信支付
  • ✅ 评价系统: 双向评价，信用体系
  • ✅ 审计日志: 完整的操作审计追踪

🏗️ 系统架构

技术栈

组件
技术选型
说明
Web 框架
Gin v1.10.0
高性能 HTTP Web 框架
数据库
MySQL
关系型数据库
ORM
XORM v1.0.2
Go 语言 ORM 框架
认证
JWT (golang-jwt/jwt/v5)
JSON Web Token 认证
文档
Swagger (Swaggo)
API 文档自动生成
配置管理
godotenv
环境变量配置
密码加密
bcrypt (golang.org/x/crypto)
密码哈希加密
文件上传
本地存储
商品图片上传

项目结构

secondHand-market-backend/├── main.go                     # 应用入口，路由配置├── go.mod                      # Go 模块依赖├── .env.example                # 环境变量配置模板├── .gitignore                  # Git 忽略配置├── API 接口文档_前端对接.md     # 详细 API 文档├── README.md                   # 项目说明文档│├── api/                        # API 接入层（中间件、安全）│   └── api.go                  # CORS、限流、安全中间件│├── app/                        # 应用核心代码│   ├── controllers/            # 控制器层（处理 HTTP 请求）│   │   ├── user_controller.go│   │   ├── product_controller.go│   │   ├── transaction_controller.go│   │   ├── review_controller.go│   │   ├── dispute_controller.go│   │   ├── payment_controller.go│   │   ├── message_controller.go│   │   ├── address_controller.go│   │   ├── admin_controller.go│   │   └── admin_auth_controller.go│   ││   ├── services/               # 服务层（业务逻辑）│   │   ├── user_service.go│   │   ├── product_service.go│   │   ├── transaction_service.go│   │   ├── review_service.go│   │   ├── dispute_service.go│   │   ├── payment_service.go│   │   ├── message_service.go│   │   └── address_service.go│   ││   ├── repository/             # 数据访问层（数据库操作）│   │   ├── user_repository.go│   │   ├── product_repository.go│   │   ├── transaction_repository.go│   │   ├── review_repository.go│   │   ├── dispute_repository.go│   │   ├── payment_repository.go│   │   ├── message_repository.go│   │   └── address_repository.go│   ││   ├── models/                 # 数据模型│   │   ├── user.go│   │   ├── product.go│   │   ├── transaction.go│   │   ├── review.go│   │   ├── dispute.go│   │   ├── payment.go│   │   ├── message.go│   │   └── address.go│   ││   ├── middleware/             # 中间件│   │   ├── auth.go             # JWT 认证中间件│   │   ├── admin_auth.go       # 管理员认证中间件│   │   ├── response.go         # 统一响应处理│   │   ├── validator.go        # 请求验证│   │   └── logger.go           # 日志中间件│   ││   ├── routes/                 # 路由配置│   │   ├── routes.go           # 用户端路由│   │   └── admin_routes.go     # 管理端路由│   ││   └── docs/                   # 文档│       └── admin_swagger.go    # 管理端 Swagger 文档│├── config/                     # 配置文件│   └── config.go               # 配置加载│├── utils/                      # 工具函数│   ├── database.go             # 数据库连接│   ├── db_init.go              # 数据库初始化│   ├── jwt.go                  # JWT 工具│   ├── email.go                # 邮件发送│   ├── audit.go                # 审计日志│   ├── response.go             # 统一响应│   └── security.go             # 安全工具│├── public/                     # 静态资源│   └── admin.html              # 管理后台前端│└── uploads/                    # 上传文件    └── products/               # 商品图片

🚀 快速开始

环境要求

  • Go: >= 1.22
  • MySQL: >= 5.7

安装步骤

1. 克隆项目

git clone <repository-url>cd secondHand-market-backend

2. 安装依赖

go mod download

3. 配置环境变量

复制环境变量模板并修改配置：

cp .env.example .env

编辑 .env 文件：

# 数据库配置DB_HOST=localhostDB_PORT=3306DB_USER=rootDB_PASSWORD=your_passwordDB_NAME=secondhand_marketDB_MAX_OPEN_CONNS=100DB_MAX_IDLE_CONNS=10DB_CONN_MAX_LIFETIME=3600# 服务器配置PORT=8080# JWT 配置JWT_SECRET=your-very-secure-secret-key-at-least-32-characters# 上传配置UPLOAD_PATH=./uploadsUPLOAD_URL=/uploads# 邮件配置（SMTP）EMAIL_HOST=smtp.qq.comEMAIL_PORT=587EMAIL_USER=your-qq@qq.comEMAIL_PASSWORD=your-auth-codeEMAIL_FROM=your-qq@qq.com# 审计日志配置AUDIT_LOG_PATH=./logs/audit.log

4. 初始化数据库

创建数据库：

CREATEDATABASE secondhand_market CHARACTERSET utf8mb4 COLLATE utf8mb4_unicode_ci;

5. 运行服务

go run main.go

服务启动后，访问：

  • API 服务: http://localhost:8080
  • Swagger 文档: http://localhost:8080/swagger/index.html
  • 管理后台: http://localhost:8080/admin.html

📡 API 接口

接口分类

系统提供 74 个 API 接口，分为以下几类：

1. 公共接口（15 个）- 无需认证

  • 用户注册、登录
  • 密码找回
  • 商品浏览、搜索
  • 评价查询
  • 支付回调

2. 用户接口（36 个）- 需要登录

用户管理 (4 个):

  • 获取/更新个人信息
  • 修改密码
  • 刷新 Token

商品管理 (10 个):

  • 发布商品、上传图片
  • 更新/删除商品
  • 上架/下架商品
  • 获取商品列表和详情

交易管理 (5 个):

  • 创建交易订单
  • 查询交易详情
  • 确认收货
  • 更新交易状态

评价系统 (1 个):

  • 创建交易评价

纠纷处理 (3 个):

  • 创建纠纷
  • 查询纠纷列表和详情

支付系统 (6 个):

  • 创建支付订单
  • 查询支付状态
  • 退款、取消支付

消息系统 (4 个):

  • 获取会话列表
  • 发送/接收消息
  • 标记消息已读

地址管理 (7 个):

  • 增删改查收货地址
  • 设置默认地址

3. 管理员接口（23 个）- 需要管理员权限

管理认证 (2 个):

  • 管理员登录
  • 获取管理员信息

平台管理 (16 个):

  • 仪表盘数据统计
  • 用户管理（查询、角色修改、封禁、解封、删除）
  • 商品管理（查询、删除、状态调整）
  • 交易管理（查询、取消、完成）
  • 纠纷处理（查询、解决、拒绝）

API 管理 (7 个):

  • 遗留的管理接口路径（兼容旧版）

认证方式

所有需要认证的接口需要在请求头中携带 JWT Token：

Authorization: Bearer <token>

响应格式

成功响应:

{"code": 200,"message": "success","data": {}}

错误响应:

{"error": "错误信息"}

🔐 核心功能说明

1. 用户系统

  • 角色设计: 平台不固定区分买家/卖家角色，用户根据交易关系动态获得身份
    • 发布商品时成为”卖家”
    • 购买商品时成为”买家”
    • 同一用户可同时拥有在售商品和进行中的购买
  • 管理员: 特殊角色，拥有平台管理权限
  • 封禁机制: 支持封禁违规用户（role = “banned”）

2. 商品管理

  • 商品状态: available（在售）、disabled（禁用）、sold（已售出）
  • 图片上传: 支持多图上传，存储在 uploads/products/ 目录
  • 搜索功能: 支持关键词搜索、分类筛选、价格区间筛选
  • 上下架: 卖家可随时上下架商品

3. 交易流程

买家下单 → 创建交易 → 支付 → 卖家发货 → 买家确认收货 → 交易完成

交易状态:

  • pending: 待支付
  • paid: 已支付
  • shipped: 已发货
  • completed: 已完成
  • cancelled: 已取消

4. 支付系统

  • 支付方式: 支持支付宝和微信支付
  • 支付回调: 异步通知处理
  • 退款功能: 支持部分或全额退款
  • 支付安全: 交易金额与订单金额校验

5. 评价系统

  • 双向评价: 买卖双方互评
  • 评分机制: 1-5 星评分
  • 平均评分: 计算用户平均评分，构建信用体系
  • 评价关联: 评价与交易绑定，防止虚假评价

6. 纠纷处理

纠纷类型:

  • product: 商品问题
  • payment: 支付问题
  • shipping: 物流问题
  • quality: 质量问题
  • other: 其他

处理流程:

用户发起纠纷 → 管理员受理 → 调查核实 → 解决/拒绝 → 执行处理

7. 即时通讯

  • 交易限制: 只有存在交易关系的用户才能发送消息
  • 会话管理: 按用户聚合消息
  • 未读计数: 支持未读消息统计
  • 防骚扰: 发送频率限制（1 分钟 10 条）

8. 地址管理

  • 收货地址的增删改查
  • 默认地址设置
  • 地址验证

🛡️ 安全机制

1. 认证与授权

  • JWT Token: 24 小时有效期
  • 密码加密: bcrypt 哈希存储
  • 权限控制: 管理员接口独立认证
  • Token 刷新: 支持 Token 续期

2. 数据安全

  • SQL 注入防护: 使用 ORM 参数化查询
  • XSS 防护: 输入验证和转义
  • 文件上传限制: 仅允许图片格式
  • 敏感信息脱敏: 日志中不记录敏感数据

3. 审计日志

  • 操作记录: 记录所有关键操作
  • 日志路径: logs/audit.log
  • 日志轮转: 支持日志文件大小限制和归档

📊 数据库设计

核心数据表

  1. users – 用户表
  2. products – 商品表
  3. transactions – 交易表
  4. reviews – 评价表
  5. disputes – 纠纷表
  6. payments – 支付表
  7. messages – 消息表
  8. addresses – 地址表

详见 [API 接口文档_前端对接.md](API 接口文档_前端对接.md) 中的数据模型章节

🔧 开发指南

添加新接口

  1. 在 app/models/ 定义数据模型
  2. 在 app/repository/ 实现数据访问
  3. 在 app/services/ 实现业务逻辑
  4. 在 app/controllers/ 实现 HTTP 处理
  5. 在 app/routes/routes.go 注册路由

中间件开发

中间件位于 app/middleware/ 目录：

  • auth.go: JWT 认证
  • admin_auth.go: 管理员认证
  • response.go: 统一响应格式化
  • validator.go: 请求参数验证
  • logger.go: 请求日志

📝 测试

运行测试

go test ./...

API 测试

使用 Postman 或 cURL 测试接口：

# 用户注册curl -X POST http://localhost:8080/api/register \  -H "Content-Type: application/json" \  -d '{    "username": "testuser",    "password": "123456",    "email": "test@example.com",    "phone": "13800138000"  }'# 用户登录curl -X POST http://localhost:8080/api/login \  -H "Content-Type: application/json" \  -d '{    "username": "testuser",    "password": "123456"  }'

📦 部署

编译二进制

go build -o main.exe

生产环境配置

  1. 修改 .env 中的配置
  2. 设置强密码和 JWT 密钥
  3. 配置 HTTPS（使用反向代理如 Nginx）
  4. 配置数据库连接池
  5. 启用日志轮转

使用 Docker 部署（可选）

docker build -t secondhand-market .docker run -p 8080:8080 secondhand-market

🐛 常见问题

1. 数据库连接失败

检查 MySQL 服务是否启动，用户名密码是否正确。

3. 文件上传失败

确保 uploads/ 目录存在且有写权限。

4. 邮件发送失败

检查 SMTP 配置，QQ 邮箱需使用授权码而非登录密码。

📈 项目统计

  • 总接口数: 74 个
  • 代码行数: 约 10,000+ 行
  • Go 版本: 1.22
  • 依赖包: 100+

🔄 更新日志

v1.10 (2026-04-29)

  • ✅ 新增：获取卖家商品列表接口
  • ✅ 修复：文档版本更新
  • ✅ 说明：添加管理员接口路径说明

v1.9 (2026-04-29)

  • ✅ 新增：管理员封禁/解封用户接口
  • ✅ 新增：管理员删除用户接口
  • ✅ 修复：用户角色更新功能

v1.8 (2026-04-24)

  • ✅ 初始版本发布

📚 参考资料

  • Gin 框架文档
  • Swagger 文档
  • JWT 规范
  • MySQL 文档

感谢大家阅读，个人观点仅供参考，欢迎在评论区发表不同观点。

欢迎关注、分享、点赞、收藏、在看，我是微信公众号「码农先森」作者。

chengsenw