# specific-service

**Repository Path**: yanhplayground/specific-service

## Basic Information

- **Project Name**: specific-service
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-03
- **Last Updated**: 2026-03-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Specific-Service 微服务项目

基于 Spring Cloud Alibaba + Nacos + APISIX 的微服务架构系统，包含用户认证、订单管理、库存管理、支付管理和实时 WebSocket 通信等服务。

## 架构概览

```
                         ┌──────────────────────┐
                         │   APISIX Gateway     │
                         │   (端口 9080)         │
                         │   JWT 认证 + 路由     │
                         └──────────┬───────────┘
                                    │
            ┌───────────┬───────────┼───────────┬───────────┐
            │           │           │           │           │
            ▼           ▼           ▼           ▼           ▼
     ┌───────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐
     │  user     │ │  order   │ │  stock   │ │ payment  │ │  websocket   │
     │  service  │ │  service │ │  service │ │ service  │ │  service     │
     │  :8080    │ │  :8084   │ │  :8082   │ │  :8083   │ │  :9899 (ws)  │
     └───────────┘ └────┬─────┘ └──────────┘ └──────────┘ └──────────────┘
                        │           ▲              ▲
                        │     Feign │        Feign │
                        └───────────┴──────────────┘
```

## 技术栈

| 类别 | 技术 | 版本 |
|------|------|------|
| 语言 | Java | 17 |
| 框架 | Spring Boot | 3.1.8 |
| 微服务 | Spring Cloud | 2022.0.4 |
| 服务注册/配置 | Spring Cloud Alibaba + Nacos | 2023.0.1.0 |
| API 网关 | APISIX | 3.8.0 |
| WebSocket | Netty | 4.1.108.Final |
| 认证 | JWT (jjwt) | 0.12.5 |
| 数据库 | MySQL + MyBatis Plus | 8.0.33 / 3.5.5 |
| 缓存 | Redis + Redisson | 3.23.5 |
| 连接池 | Druid | 1.2.20 |
| 服务间调用 | OpenFeign + LoadBalancer | - |
| JSON | Fastjson2 | 2.0.47 |
| 接口文档 | Knife4j | 4.5.0 |
| 监控 | Prometheus + Grafana | - |
| 工具 | Lombok, Hutool | 1.18.32 / 5.8.27 |

## 项目结构

```
specific-service/
├── api/                      # 公共 API 定义（Feign Client、DTO）
├── common-service/           # 公共组件（JWT、安全、异常、工具类）
├── gateway/                  # Spring Cloud Gateway（已被 APISIX 替代）
├── user-service/             # 用户认证服务
├── order-service/            # 订单服务
├── stock-service/            # 库存服务
├── payment-service/          # 支付服务
├── websocket-service/        # WebSocket 实时通信服务（Netty）
├── qc-api-service/           # 巨量千川广告 API 集成
├── nacosconfig/              # Nacos 共享配置文件
└── sql/                      # 数据库初始化脚本

docker/apisix/                # APISIX 网关部署配置
├── docker-compose.yaml       # Docker 编排
├── config.yaml               # APISIX 核心配置
├── init-routes.sh            # 路由初始化脚本
├── plugins/
│   └── jwt-gateway-auth.lua  # 自定义 JWT 认证插件
└── ...
```

## 服务模块

### user-service（用户认证服务）

| 端口 | 接口 | 说明 |
|------|------|------|
| 8080 | `POST /auth/token` | 登录，返回 accessToken + refreshToken |
| | `GET /auth/refresh` | 刷新 Token |
| | `POST /auth/logout?userId=` | 登出，清除 Redis 缓存 |
| | `GET /auth/info?userId=` | 查询用户信息 |
| | `GET /userinfo` | 获取当前登录用户信息 |

### order-service（订单服务）

| 端口 | 接口 | 说明 |
|------|------|------|
| 8084 | `GET /order/list` | 查询订单列表 |
| | `POST /order/create` | 创建订单（Feign 调用 stock + payment） |

### stock-service（库存服务）

| 端口 | 接口 | 说明 |
|------|------|------|
| 8082 | `GET /stock/list` | 查询库存 |
| | `POST /stock/deduct` | 扣减库存 |

### payment-service（支付服务）

| 端口 | 接口 | 说明 |
|------|------|------|
| 8083 | `GET /payment/balance/{userId}` | 查询余额 |
| | `POST /payment/reserve` | 预留余额 |

### websocket-service（实时通信服务）

| 端口 | 说明 |
|------|------|
| 9898 | HTTP 管理端口（Spring Boot Tomcat，用于 Nacos 注册和健康检查） |
| 9899 | WebSocket 端口（Netty，对外提供 ws:// 连接） |

**连接地址**：`ws://localhost:9899/ws`（直连）或 `ws://localhost:9080/ws`（通过 APISIX）

**认证方式**：WebSocket 握手时通过 `Authorization: Bearer <token>` Header 认证

**消息协议**（JSON）：

```json
// 心跳
{"cmd": "ping", "msgId": "1"}
// 响应 → {"cmd": "pong", "onlineCount": 3}

// 单聊
{"cmd": "message", "msgId": "2", "receiverId": "10002", "receiverType": "user", "content": "你好", "msgType": "text"}

// 广播
{"cmd": "message", "msgId": "3", "receiverId": "all", "receiverType": "group", "content": "大家好", "msgType": "text"}
```

**Netty Pipeline**：

```
HttpServerCodec → HttpObjectAggregator
  → HttpRequestHandler（JWT 认证）
  → WebSocketServerProtocolHandler（握手）
  → WebSocketServerCompressionHandler（压缩）
  → IdleStateHandler → IdleStateCheckHandler（心跳检测）
  → WebSocketFrameEncoder（POJO → TextWebSocketFrame）
  → WebSocketHandler（命令路由）
  → WebSocketLifecycleHandler（连接生命周期）
```

## 认证体系

### JWT Token 结构

| Claim | 说明 | 示例 |
|-------|------|------|
| `User-Id` | 用户 ID | `1176` |
| `User-Name` | 用户名 | `yanh` |
| `Client-Area` | 租户区域 | `fz` |
| `sub` | 主题 | `subject` |
| `iss` | 签发者 | `issue` |
| `exp` | 过期时间 | UNIX 时间戳 |

### 认证流程

```
客户端 → POST /auth/token（用户名+密码）
       ← accessToken + refreshToken（存入 Redis）

客户端 → GET /order/list + Authorization: Bearer <accessToken>
       → APISIX jwt-gateway-auth 插件验签
       → 注入 User-Id / User-Name / Client-Area 到请求头
       → 转发到 order-service
       → UserInfoInterceptor 从请求头读取用户信息存入 UserContext
```

### 统一错误码（ResultCode）

采用 6 位分段编码 `AABBCC`（AA=模块, BB=子类, CC=序号）：

| 范围 | 模块 | 示例 |
|------|------|------|
| `0` | 成功 | `0` = 成功 |
| `10xxxx` | 通用错误 | `100001` = 未知错误, `100101` = 参数不合法, `100201` = 限流 |
| `11xxxx` | 认证/Token | `110001` = token 缺失, `110002` = token 无效, `110004` = token 过期 |
| `12xxxx` | 用户/登录 | `120001` = 密码错误, `120003` = 用户禁用 |
| `500` | 服务器异常 | 内部错误 |

统一响应格式：

```json
{"code": 0, "msg": "成功", "data": {...}}
{"code": 110002, "msg": "token 已过期或验证不正确", "data": null}
```

## APISIX 网关

替代原 Spring Cloud Gateway，提供路由、认证、限流等功能。

### 路由映射

| 路径 | 后端服务 | 说明 |
|------|---------|------|
| `/auth/*` | user-service:8080 | 认证相关（限流 60次/分钟） |
| `/userinfo`, `/userinfo/*` | user-service:8080 | 用户信息 |
| `/order/*` | order-service:8084 | 订单管理 |
| `/stock/*` | stock-service:8082 | 库存管理 |
| `/payment/*` | payment-service:8083 | 支付管理 |
| `/ws` | websocket-service:9899 | WebSocket（enable_websocket, 超时 600s） |

### 白名单（免认证路径）

`/auth/**`, `/userinfo`, `/actuator/**`, `/doc.html`, `/swagger-ui/**`, `/webjars/**`, `/v3/api-docs/**`

### 自定义插件 jwt-gateway-auth

完全等价于 Java 端的 `TokenValidationGlobalFilter`：
- 白名单路径放行
- 从 `Authorization: Bearer <token>` 提取并验证 JWT
- 注入 `User-Id` / `User-Name` / `Client-Area` 到下游请求头
- 移除 `From-Source` 请求头
- 错误响应与 Java 端 `Result` 结构体一致

## Nacos 共享配置

| 配置文件 | 说明 |
|---------|------|
| `shared-jwt.yaml` | JWT 密钥、过期时间 |
| `shared-security.yaml` | 认证白名单 |
| `shared-redis.yaml` | Redis 连接配置 |
| `shared-jdbc.yaml` | MySQL 数据源 |
| `shared-gw.yaml` | Gateway 路由（legacy） |
| `shared-websocket.yaml` | WebSocket 端口、心跳、压缩配置 |
| `shared-constans.yaml` | 数据库名称等常量 |
| `shared-log.yaml` | 日志级别和格式 |
| `shared-feign.yaml` | Feign OkHttp 配置 |
| `shared-swagger.yaml` | Knife4j 接口文档 |

## 数据库

| 数据库 | 主要表 | 说明 |
|--------|-------|------|
| user_db | `sys_user` | 用户表 |
| order_db | `t_order` | 订单表 |
| stock_db | `t_product_stock` | 商品库存表 |
| payment_db | `t_user_balance` | 用户余额表 |

## 快速开始

### 前置条件

- JDK 17+
- Maven 3.8+
- MySQL 8.0+
- Redis 6+
- Nacos 2.x（端口 8848）
- Docker & Docker Compose（APISIX 部署）

### 1. 初始化数据库

```bash
# 执行 sql/ 目录下的建表脚本
mysql -u root -p < sql/stock-db.sql
mysql -u root -p < sql/order-db.sql
mysql -u root -p < sql/payment-db.sql
```

### 2. 导入 Nacos 配置

将 `nacosconfig/` 目录下的 yaml 文件逐一导入到 Nacos 配置中心：
- 命名空间：`public`
- 分组：`DEFAULT_GROUP`
- Data ID：文件名（如 `shared-jwt.yaml`）

### 3. 启动微服务

```bash
# 按顺序启动各服务
cd user-service && mvn spring-boot:run
cd order-service && mvn spring-boot:run
cd stock-service && mvn spring-boot:run
cd payment-service && mvn spring-boot:run
cd websocket-service && mvn spring-boot:run
```

### 4. 启动 APISIX 网关

```bash
cd docker/apisix
docker-compose up -d

# 等待 APISIX 完全启动后，初始化路由
./init-routes.sh
```

### 5. 验证

```bash
# 登录获取 Token
curl -X POST http://localhost:9080/auth/token \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "123456"}'

# 使用 Token 访问服务
curl http://localhost:9080/userinfo \
  -H "Authorization: Bearer <your_token>"
```

## 端口汇总

| 端口 | 服务 | 说明 |
|------|------|------|
| 8080 | user-service | 用户认证 |
| 8082 | stock-service | 库存管理 |
| 8083 | payment-service | 支付管理 |
| 8084 | order-service | 订单管理 |
| 9898 | websocket-service | HTTP 管理端口 |
| 9899 | websocket-service | WebSocket 端口 |
| 9080 | APISIX | 代理入口（对外统一入口） |
| 9180 | APISIX Admin | 管理 API |
| 9000 | APISIX Dashboard | 可视化管理界面 |
| 8848 | Nacos | 服务注册/配置中心 |
| 2379 | etcd | APISIX 配置存储 |
| 9090 | Prometheus | 指标采集 |
| 3000 | Grafana | 监控面板 |