Order System API — Go + PostgreSQL 学习项目

一个面向小型电商的订单管理系统 API，覆盖完整的 SQL 查询场景，适合学习 Go 语言后端开发和 PostgreSQL 数据库查询。

技术栈

技术	用途
Go 1.26	后端语言
Chi router	HTTP 路由
pgx v5	PostgreSQL 驱动（手写 SQL，无 ORM）
PostgreSQL 17	数据库
Docker Compose	部署方案

项目结构

order-system/
├── cmd/server/main.go        # 入口，Chi 路由 + 优雅关闭
├── internal/
│   ├── config/config.go      # 环境变量配置（DATABASE_URL, PORT）
│   ├── database/
│   │   ├── postgres.go       # pgx 连接池管理
│   │   └── migrate.go        # SQL 迁移引擎
│   ├── model/                # 5 个数据模型
│   ├── repository/           # SQL 查询层（主要学习目标）
│   │   ├── user_repo.go     # 基础 CRUD + 分页
│   │   ├── product_repo.go  # 条件查询 + 防删除保护
│   │   ├── order_repo.go    # JOIN 查询 + 事务下单
│   │   ├── payment_repo.go  # 支付记录
│   │   └── report_repo.go   # 聚合统计 + 窗口函数
│   ├── service/              # 业务逻辑层
│   ├── handler/              # HTTP 接口层
│   └── middleware/           # 日志 + CORS + 错误恢复
├── migrations/               # 6 个 SQL 文件（建表 + 种子数据）
├── Dockerfile
└── docker-compose.yml        # PostgreSQL + pgAdmin

快速启动

方式一：Docker Compose（推荐）

# 启动 PostgreSQL 和 pgAdmin
docker compose -f docker-compose.yml up -d

# 本地启动 Go 服务（需要在终端另外开一个窗口）
export DATABASE_URL="postgres://postgres:postgres@localhost:5432/order_system?sslmode=disable"
go run ./cmd/server

启动后访问：

服务	地址
API 服务	http://localhost:8080
pgAdmin	http://localhost:5050

pgAdmin 登录：admin@order-system.com / admin

在 pgAdmin 中添加服务器连接：

• 名称：order-system-db
• 主机：localhost
• 端口：5432
• 用户名：postgres
• 密码：postgres
• 数据库：order_system

方式二：纯本地开发

# 确保本地安装了 PostgreSQL 并创建了 order_system 数据库
export DATABASE_URL="postgres://postgres:postgres@localhost:5432/order_system?sslmode=disable"
go run ./cmd/server

API 接口

商品管理

方法	路径	说明
GET	/api/products	商品列表（支持 ?category=&search=&page=&page_size=）
GET	/api/products/{id}	商品详情
POST	/api/products	创建商品
PUT	/api/products/{id}	更新商品
DELETE	/api/products/{id}	删除商品（有订单引用时禁止删除）

订单管理

方法	路径	说明
GET	/api/orders	订单列表（支持 ?status=&user_id=&start_date=&end_date=）
GET	/api/orders/{id}	订单详情（含用户和商品明细）
POST	/api/orders	创建订单（事务：插入订单 + 明细 + 扣库存）
PUT	/api/orders/{id}/status	更新订单状态

统计报表

方法	路径	说明
GET	/api/reports/sales/daily	每日销售额统计
GET	/api/reports/products/top	畅销商品排行（RANK 窗口函数）
GET	/api/reports/customers/spending	客户消费排行

数据库设计

5 张核心表

表	说明	SQL 学习重点
users	客户表（姓名、手机、地址）	单表 CRUD、分页
products	商品表（名称、分类、价格、库存）	条件查询、ILIKE 搜索
orders	订单主表（用户ID、总金额、状态、时间）	日期范围、状态过滤
order_items	订单明细表（订单ID、商品ID、数量、单价）	多表 JOIN、子查询
payments	支付记录表（订单ID、金额、方式、状态）	事务、聚合统计

种子数据

启动时自动导入 5 个用户、10 个商品、15 个订单及其明细和支付记录，开箱即用。

SQL 学习路线

按以下顺序阅读 internal/repository/ 中的代码，由浅入深：

1. 基础 CRUD：user_repo.go — SELECT / INSERT / UPDATE / DELETE + RETURNING
2. 条件查询：product_repo.go — ILIKE 模糊搜索、WHERE 条件组合、EXISTS 子查询
3. 多表 JOIN：order_repo.go — JOIN 查询订单+用户+商品信息
4. 事务：order_repo.go — CreateOrder() 方法，下单=插入订单+明细+扣库存
5. 聚合统计：report_repo.go — GROUP BY、SUM、COUNT、COALESCE
6. 窗口函数：report_repo.go — RANK() OVER 窗口函数
7. LEFT JOIN：report_repo.go — LEFT JOIN 防止用户无订单时不显示

curl 测试示例

# 健康检查
curl http://localhost:8080/health

# 商品列表
curl "http://localhost:8080/api/products?page=1&page_size=5"

# 搜索商品
curl "http://localhost:8080/api/products?search=ThinkPad"

# 按分类筛选
curl "http://localhost:8080/api/products?category=外设"

# 订单详情（含 JOIN 查询）
curl http://localhost:8080/api/orders/1

# 创建订单（事务）
curl -X POST http://localhost:8080/api/orders \
  -H "Content-Type: application/json" \
  -d '{"user_id":1,"items":[{"product_id":1,"quantity":1}]}'

# 每日销售额报表
curl "http://localhost:8080/api/reports/sales/daily?start_date=2026-06-01&end_date=2026-06-15"

# 畅销商品排行（RANK 窗口函数）
curl "http://localhost:8080/api/reports/products/top?limit=10"

# 客户消费排行
curl "http://localhost:8080/api/reports/customers/spending?limit=10"

Go 代码说明

为什么选这些库？

• pgx：PostgreSQL 官方推荐的高性能驱动，支持连接池、事务、NamedArgs 等特性
• Chi：轻量级 HTTP 路由，完全兼容标准库 net/http
• 手写 SQL：不引入 ORM，目的是学习 SQL 本身

代码层级

handler → service → repository → PostgreSQL

• handler：HTTP 请求/响应，参数解析、JSON 序列化
• service：业务逻辑，参数校验、数据组装
• repository：SQL 查询，手写 SQL、使用 pgx 执行

License

MIT