ARCHITECTURE.md 10 KB
系统架构设计
🏗️ 整体架构
┌─────────────────────────────────────────────────────────────┐
│ Browser (Vue Web) │
│ http://localhost:5173 │
└────────────────────────┬────────────────────────────────────┘
│
HTTP Requests
│
▼
┌─────────────────────────────────────────────────────────────┐
│ API Gateway (Spring Cloud) │
│ http://localhost:8080 (Port 8080) │
│ │
│ Functions: │
│ • Route requests to backend services │
│ • Record request entry point logs │
│ • Apply global interceptors │
└────────┬──────────────────────┬──────────────────────┬────────┘
│ │ │
/order/* /payment/* /health
│ │ │
▼ ▼ ▼
┌─────────────┐ ┌──────────────┐ ┌──────────────┐
│Order Service │ │Payment Service│ └──────────────┘
│(Port 8081) │ │(Port 8082) │
│ │ │ │
│ /order/ │ │ /payment/ │
│ ├─ create │ │ ├─ pay │
│ ├─ delete │ │ ├─ refund │
│ ├─ get │ │ └─ get │
│ └─ pay │ │ │
└─────────────┘ └──────────────┘
📦 模块设计
1. shop-recycle-common (公共模块)
职责: 提供日志、配置、DTO等公共能力
包含:
LoggingMdcInterceptor- 日志MDC拦截器Response<T>- 统一响应类WebConfig- Web配置（注册拦截器）
关键特性:
自动填充MDC字段:
✓ traceId (链路追踪ID)
✓ uri (原始请求路径)
✓ uri_group (规范化URI分组)
✓ event_class (事件分类)
✓ duration (请求耗时)
✓ status (HTTP状态)
✓ error (错误堆栈)
2. shop-recycle-gateway (API网关)
职责: 请求路由、负载均衡、协议转换
配置:
routes:
- id: order-service
uri: http://localhost:8081 # 本地开发
条件: Path=/api/order/**
- id: payment-service
uri: http://localhost:8082
条件: Path=/api/payment/**
日志链路:
浏览器请求 → Gateway (日志记录进入点)
→ 路由转发 → Order Service
→ 生成响应 → 返回浏览器
3. shop-recycle-order-service (订单服务)
职责: 订单CRUD操作
数据模型:
OrderResponse {
orderId // ORD-XXXXX (自动生成)
userId // 用户ID (来自请求头)
price // 订单金额
status // CREATED, PAID, CANCELLED
description // 订单描述
createdAt // 创建时间戳
}
业务逻辑:
✓ createOrder() - 创建订单 (校验价格>0)
✓ deleteOrder() - 删除订单 (已支付的不能删除)
✓ getOrder() - 查询订单
✓ updateOrderStatus() - 更新状态 (订单支付时调用)
日志埋点:
DEBUG: 订单创建逻辑开始
INFO: 订单已创建 orderId=ORD-XXXXX
WARN: 订单不存在 orderId=...
ERROR: 订单创建失败 (异常堆栈)
4. shop-recycle-payment-service (支付服务)
职责: 订单支付、退款
数据模型:
PaymentResponse {
paymentId // PAY-XXXXX (自动生成)
orderId // 关联的订单
amount // 支付金额
status // PENDING, SUCCESS, FAILED, REFUNDED
paymentMethod // CARD, WECHAT, ALIPAY
paidAt // 支付时间戳
}
业务逻辑:
✓ payOrder() - 支付订单 (模拟30%失败率)
✓ refund() - 退款 (仅成功支付可退,模拟10%失败率)
✓ getPayment() - 查询支付
日志埋点:
DEBUG: 订单支付逻辑开始
INFO: 订单支付成功 paymentId=PAY-XXXXX
WARN: 支付金额不合法
ERROR: 第三方支付失败 (异常堆栈)
5. shop-recycle-web (Vue前端)
职责: 提供Web UI，调用API生成测试流量
技术栈:
- Vue 3 (创意性组件框架)
- Vite (构建工具)
- Axios (HTTP客户端)
页面组件:
- OrderComponent - 订单管理界面
- PaymentComponent - 支付管理界面
代理配置 (vite.config.js):
proxy: {
'/api': {
target: 'http://localhost:8080', // API Gateway
changeOrigin: true
}
}
🔄 请求流程示例
完整的订单创建流程
Step 1: 用户提交表单
浏览器 → POST /api/order/create
↓
Step 2: Gateway接收请求
Gateway → LoggingMdcInterceptor (记录进入点)
├─ traceId = UUID生成
├─ uri = /api/order/create
├─ uri_group = /order/*
└─ event_class = order
↓
Step 3: 路由转发到Order Service
Gateway → Order Service (http://localhost:8081/api/order/create)
↓
Step 4: Order Service处理请求
Order Service → OrderController.createOrder()
→ OrderService.createOrder()
→ generate orderId
→ save to memory
→ MDC.put("status", "success")
└─ log.info("订单已创建")
↓
Step 5: 响应返回
Order Service → Response.success({orderId, userId, ...})
↓
Step 6: 前端接收响应
浏览器 ← {code: 0, msg: "success", data: {...}}
└─ Display success message
后端日志输出
[Gateway在处理请求时]
{
"ts":"2024-02-06T10:30:45.123Z",
"app":"shop-recycle-gateway",
"uri":"/api/order/create",
"uri_group":"/order/*",
"traceId":"550e8400-e29b-41d4-a716-446655440000"
}
[Order Service处理业务逻辑时]
{
"ts":"2024-02-06T10:30:45.200Z",
"app":"shop-recycle-order-service",
"level":"INFO",
"msg":"订单已创建 orderId=ORD-A1B2C3D4",
"event_class":"order",
"status":"success",
"duration":"156", // 毫秒
"traceId":"550e8400-e29b-41d4-a716-446655440000"
}
📊 日志字段映射表
| MDC字段 | 来源 | 设置位置 | 备注 |
|---|---|---|---|
traceId |
请求头或生成 | Interceptor.preHandle() | X-B3-TraceId或UUID生成 |
uri |
HttpRequest | Interceptor.preHandle() | 原始请求路径 |
uri_group |
规范化逻辑 | normalizeUri() | /order/* /payment/* |
event_class |
规则匹配 | deriveEventClass() | order/payment/auth/api |
userId |
请求头 | Interceptor.preHandle() | X-User-Id头 |
start_time |
System.time | Interceptor.preHandle() | 用于后续计算duration |
duration |
计算得出 | Interceptor.afterCompletion() | 当前时间 - start_time |
error |
异常/状态码 | Interceptor.afterCompletion() | Exception.toString()或HTTP状态 |
status |
HTTP状态码 | Interceptor.afterCompletion() | success/client_error/server_error |
🔑 关键设计决策
1. 拦截器而不是过滤器
✓ 优点: 可以访问Handler和ModelMap
✓ 优点: 在业务方法执行前后进行处理
✓ 适合: 日志、权限、性能监控
2. 异步Appender
✓ 优点: 异步输出日志，不阻塞业务线程
✓ 优点: 可配置队列大小和丢弃策略
✓ 配置: AsyncAppender + queueSize=1024
3. JSON格式日志
✓ 优点: 可被Loki/ELK直接解析
✓ 优点: 支持结构化查询
✓ 工具: LogstashEncoder
4. MDC而不是参数传递
✓ 优点: 零侵入，业务代码无需改动
✓ 优点: 自动在线程本地存储
✓ 优点: 所有日志自动包含上下文
5. URI规范化
✓ 原始: /order/create /order/12345/delete /order/abc/pay
✓ 规范化: /order/* (减少基数)
✓ 好处: Prometheus label基数可控
🌐 环境配置
本地开发 (local)
Gateway:
order-service: http://localhost:8081
payment-service: http://localhost:8082
Frontend:
Vite proxy: http://localhost:8080
Docker容器 (docker)
Gateway:
order-service: http://order-service:8081 (DNS名称)
payment-service: http://payment-service:8082
Network:
All services connected via app-network bridge
生产环境 (prod - 示例)
Gateway:
order-service: http://order-service.default.svc.cluster.local:8081
payment-service: http://payment-service.default.svc.cluster.local:8082
Log aggregation:
Vector agent → Loki endpoint
Prometheus scrape: /actuator/prometheus
📈 可观测性支持
日志可观测 (Structured Logging)
✓ Fields: traceId, uri_group, event_class, duration, status
✓ Format: JSON (parseable)
✓ Tool: Loki/ELK for Log aggregation
指标可观测 (Metrics)
✓ Requests total (按uri_group分组)
✓ Requests errors
✓ Request duration (直方图)
✓ Order/Payment specific counters
Tool: Prometheus + Vector for export
链路可观测 (Tracing)
✓ traceId: 记录在每个日志中
✓ X-B3-TraceId: 支持Jaeger/Zipkin集成
✓ 可通过traceId查询完整链路
🔬 测试架构
单元测试
service层 → 业务逻辑 (MockOrderService)
集成测试
Controller → Service → 内存DB (实际执行)
端到端测试
Vue前端 → API Gateway → Order Service → Payment Service
(完整的HTTP链路)
使用QUICK_START.md中的测试脚本进行E2E测试。
相关文档:
- QUICK_START.md - 快速开始
- API.md - API详细文档
- README.md - 项目文档