在线书店微服务实战项目

一个完整的 Go 微服务学习项目，从零开始构建生产级微服务系统。

📋 项目简介

本项目是一个渐进式的在线书店系统，通过 7 个章节循序渐进地构建完整的微服务架构：

• Chapter 1: 环境搭建与项目初始化
• Chapter 2: 架构设计与 Proto 定义
• Chapter 3: Book Service - 图书服务实现
• Chapter 4: User Service - 用户服务与认证
• Chapter 5: API Gateway - 统一网关实现
• Chapter 6: 服务集成与测试
• Chapter 7: Docker 部署与优化

🎯 学习目标

完成本教程后，你将掌握：

核心技能

• gRPC 微服务开发 - 从 Proto 定义到完整实现
• API Gateway 模式 - HTTP 到 gRPC 的转换
• JWT 认证授权 - 完整的用户认证流程
• 服务间通信 - gRPC 客户端/服务端开发
• 数据库设计 - SQLite 数据模型和操作
• 错误处理 - 统一的错误码和错误处理
• 日志记录 - 结构化日志最佳实践

进阶技能

• 项目结构 - 清晰的代码组织方式
• 中间件模式 - 认证、日志、CORS 等中间件
• RESTful API - 标准的 REST 接口设计
• 容器化部署 - Docker 和 Docker Compose
• 服务编排 - 多服务启动和管理

🏗️ 系统架构

整体架构图

┌─────────────────────────────────────────────────────────────┐
│                     客户端应用层                              │
│              (Web 浏览器 / 移动 App / 第三方)                  │
└───────────────────────────┬─────────────────────────────────┘
                            │ HTTP/HTTPS (REST API)
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                    API Gateway :8080                         │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ 核心功能                                              │   │
│  │  • HTTP → gRPC 协议转换                              │   │
│  │  • JWT Token 验证                                    │   │
│  │  • 请求路由与转发                                     │   │
│  │  • CORS 跨域处理                                     │   │
│  │  • 统一错误处理                                       │   │
│  │  • 请求日志记录                                       │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────┬───────────────────────┬───────────────────────┘
              │ gRPC                  │ gRPC
              ▼                       ▼
┌──────────────────────────┐  ┌──────────────────────────┐
│  User Service :50052     │  │  Book Service :50051     │
│  ┌────────────────────┐  │  │  ┌────────────────────┐  │
│  │ 业务功能            │  │  │  │ 业务功能            │  │
│  │ • 用户注册          │  │  │  │ • 图书 CRUD         │  │
│  │ • 用户登录          │  │  │  │ • 图书搜索          │  │
│  │ • Token 生成        │  │  │  │ • 库存管理          │  │
│  │ • Token 验证        │  │  │  │ • 分页查询          │  │
│  │ • 用户信息管理      │  │  │  │ • 示例数据          │  │
│  └────────────────────┘  │  │  └────────────────────┘  │
│  ┌────────────────────┐  │  │  ┌────────────────────┐  │
│  │ SQLite Database    │  │  │  │ SQLite Database    │  │
│  │ • users 表         │  │  │  │ • books 表         │  │
│  └────────────────────┘  │  │  └────────────────────┘  │
└──────────────────────────┘  └──────────────────────────┘

技术栈

层级	技术选型	说明
通信协议	gRPC + Protocol Buffers	高性能 RPC 框架
API 网关	Gin Framework	高性能 HTTP 框架
认证授权	JWT (golang-jwt/jwt)	Token 认证
数据库	SQLite	轻量级嵌入式数据库
密码加密	bcrypt	安全的密码哈希
容器化	Docker + Docker Compose	容器编排
开发语言	Go 1.21+	-

📚 教程章节

Chapter 1: 环境搭建

⏱️ 预计时间: 30 分钟

学习内容:

• 安装 Go、protoc 和相关工具
• 初始化项目结构
• 配置 Go Modules
• 验证开发环境

Chapter 2: 架构设计

⏱️ 预计时间: 1 小时

学习内容:

• 领域建模和服务拆分
• Proto 文件定义（book.proto、user.proto）
• 数据库表设计
• API 接口规划
• 生成 gRPC 代码

Chapter 3: Book Service

⏱️ 预计时间: 3-4 小时

学习内容:

• SQLite 数据库初始化
• 实现图书 CRUD 操作
• 实现搜索和分页功能
• gRPC 服务端开发
• 错误处理和日志
• 单元测试

Chapter 4: User Service

⏱️ 预计时间: 3-4 小时

学习内容:

• 用户数据模型设计
• 用户注册（bcrypt 密码加密）
• 用户登录（JWT Token 生成）
• Token 验证服务
• 用户信息管理
• 安全最佳实践

Chapter 5: API Gateway

⏱️ 预计时间: 4-5 小时

学习内容:

• Gin 框架基础
• HTTP 到 gRPC 的转换
• JWT 认证中间件
• CORS 配置
• 路由设计
• 统一错误处理
• RESTful API 实现

Chapter 6: 服务集成与测试

⏱️ 预计时间: 2-3 小时

学习内容:

• 服务启动脚本
• 集成测试
• API 测试（curl、Postman）
• 常见问题排查
• 性能测试基础

Chapter 7: Docker 部署

⏱️ 预计时间: 2-3 小时

学习内容:

• 编写 Dockerfile
• Docker Compose 配置
• 多服务编排
• 健康检查
• 日志收集
• 生产环境优化建议

🎓 学习路径

初级开发者（0-1年经验）

推荐学习顺序：

1. 先完成前置课程：

   • gRPC 基础
   • Protocol Buffers
   • Gin 框架

2. 按章节顺序学习本教程（1→2→3→4→5→6→7）

3. 每章完成后：

   • 运行代码验证功能
   • 修改代码加深理解
   • 完成章节练习题

中级开发者（1-3年经验）

推荐学习方式：

1. 快速浏览 Chapter 1-2（环境和架构）
2. 重点学习 Chapter 3-5（服务实现）
3. 扩展练习：
   • 添加订单服务（Order Service）
   • 集成 Redis 缓存
   • 实现服务发现

高级开发者（3年+经验）

推荐实践：

1. 直接 Clone 代码，理解架构
2. 改进建议：
   • 添加 Kubernetes 部署
   • 集成 Istio 服务网格
   • 实现分布式追踪（Jaeger）
   • 添加 Prometheus 监控
   • 实现 SAGA 分布式事务

🆚 对比：电商项目 vs 书店项目

维度	电商微服务	书店微服务（本项目）
复杂度	⭐⭐⭐⭐ 高	⭐⭐⭐ 中等
服务数量	4 个服务	3 个服务
代码量	~3000 行	~1500 行
学习曲线	陡峭	平缓
文档详细度	中等	详细
代码注释	部分	完整
适合人群	有微服务经验	微服务初学者
完成时间	3-4 周	2-3 周

书店项目的优势：

• ✅ 更详细的分步教程
• ✅ 每一行代码都有注释说明
• ✅ 完整的测试用例
• ✅ 清晰的学习路径
• ✅ 适合作为第一个微服务项目

🚀 快速体验

如果你想先快速体验完整系统，可以直接运行：

# 克隆代码
cd examples/microservices/10-bookstore-project

# 生成 Proto 代码
bash scripts/gen-proto.sh

# 启动所有服务
bash scripts/run-all.sh

# 测试 API（另一个终端）
curl -X POST http://localhost:8080/api/users/register \
  -H "Content-Type: application/json" \
  -d '{"username":"alice","email":"alice@example.com","password":"password123"}'

完整的快速开始指南请查看仓库中的 QUICKSTART.md

💡 核心亮点

1. 渐进式学习

• 从简单到复杂，逐步构建
• 每章独立完整，可单独学习
• 代码可运行，即时验证

2. 生产级代码

• 完整的错误处理
• 结构化日志
• 安全最佳实践
• 性能优化考虑

3. 真实业务场景

• 用户注册/登录流程
• 图书管理系统
• JWT 认证授权
• RESTful API 设计

4. 可扩展架构

• 易于添加新服务
• 支持水平扩展
• 配置化管理
• 容器化部署

📖 相关资源

前置知识

• gRPC 基础 - gRPC 核心概念
• gRPC 流式通信 - 四种 RPC 模式
• Protocol Buffers - Proto3 语法
• Gin 框架基础 - HTTP 服务开发

进阶学习

• 服务发现 - Consul/etcd
• 负载均衡 - 多种负载均衡算法
• 分布式追踪 - OpenTelemetry
• 微服务测试指南 - 完整测试策略

生产实践

• Docker 容器化 - 容器化最佳实践
• Kubernetes 编排 - K8s 部署
• 监控告警 - Prometheus + Grafana

⏭️ 开始学习

准备好了吗？让我们从第一章开始：

👉 Chapter 1: 环境搭建

---

💬 获取帮助

如果在学习过程中遇到问题：

1. 查看每章的"常见问题"部分
2. 参考完整代码：GitHub 仓库
3. 阅读 微服务测试指南

🎉 祝学习愉快！