400 lines
11 KiB
Markdown
400 lines
11 KiB
Markdown
|
# 天远 API 服务器 - 微服务架构文档
|
|||
|
|
|||
|
## 项目概述
|
|||
|
|
|||
|
天远 API 服务器是一个基于 `go-zero` 框架构建的微服务架构系统,主要提供数据加密传输、用户管理、产品管理、支付等核心业务功能。整个系统采用微服务架构模式,每个服务独立部署,通过 gRPC 和 HTTP 进行通信。
|
|||
|
|
|||
|
## 技术栈
|
|||
|
|
|||
|
- **微服务框架**: go-zero
|
|||
|
- **编程语言**: Go
|
|||
|
- **数据库**: MySQL
|
|||
|
- **缓存**: Redis
|
|||
|
- **消息队列**: Kafka (通过 kq)
|
|||
|
- **服务注册发现**: Etcd
|
|||
|
- **API 协议**: HTTP/REST + gRPC
|
|||
|
- **加密**: AES, MD5
|
|||
|
- **第三方服务**: 阿里云短信、七牛云存储、百度 AI、支付宝支付
|
|||
|
|
|||
|
## 整体架构图
|
|||
|
|
|||
|
```
|
|||
|
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
|
|||
|
│ 客户端应用 │ │ 管理端应用 │ │ 第三方系统 │
|
|||
|
└─────────────────┘ └─────────────────┘ └─────────────────┘
|
|||
|
│ │ │
|
|||
|
▼ ▼ ▼
|
|||
|
┌─────────────────────────────────────────────────────────────────┐
|
|||
|
│ API 网关层 │
|
|||
|
│ (gateway-api) │
|
|||
|
└─────────────────────────────────────────────────────────────────┘
|
|||
|
│
|
|||
|
▼
|
|||
|
┌─────────────────────────────────────────────────────────────────┐
|
|||
|
│ 微服务集群 │
|
|||
|
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
|||
|
│ │ API │ │ User │ │ Sentinel │ │ Admin │ │
|
|||
|
│ │ Service │ │ Service │ │ Service │ │ Service │ │
|
|||
|
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
|
|||
|
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
|||
|
│ │ MQS │ │ Index │ │ WestDex │ │ 共享包 │ │
|
|||
|
│ │ Service │ │ Service │ │ Module │ │ (pkg) │ │
|
|||
|
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
|
|||
|
└─────────────────────────────────────────────────────────────────┘
|
|||
|
│
|
|||
|
▼
|
|||
|
┌─────────────────────────────────────────────────────────────────┐
|
|||
|
│ 基础设施层 │
|
|||
|
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
|||
|
│ │ MySQL │ │ Redis │ │ Kafka │ │ Etcd │ │
|
|||
|
│ │ Database │ │ Cache │ │MessageQueue │ │Service Disc │ │
|
|||
|
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
|
|||
|
└─────────────────────────────────────────────────────────────────┘
|
|||
|
```
|
|||
|
|
|||
|
## 服务详细说明
|
|||
|
|
|||
|
### 1. Gateway Service (网关服务)
|
|||
|
|
|||
|
**路径**: `apps/gateway/`
|
|||
|
|
|||
|
**功能**:
|
|||
|
|
|||
|
- 统一入口网关,处理所有外部请求
|
|||
|
- 用户认证与授权
|
|||
|
- 企业认证管理
|
|||
|
- 产品信息查询
|
|||
|
- 用户产品管理
|
|||
|
- 充值管理
|
|||
|
- 白名单管理
|
|||
|
|
|||
|
**API 端点**:
|
|||
|
|
|||
|
- `/api/console/auth/*` - 认证相关(登录、注册、验证码)
|
|||
|
- `/api/console/user/*` - 用户管理(用户信息、企业认证)
|
|||
|
- `/api/console/product/*` - 产品管理
|
|||
|
- `/api/console/user-product/*` - 用户产品关联
|
|||
|
- `/api/console/topup/*` - 充值管理
|
|||
|
- `/api/console/whitelist/*` - 白名单管理
|
|||
|
|
|||
|
**依赖**:
|
|||
|
|
|||
|
- UserRpc: 用户服务的 gRPC 客户端
|
|||
|
- SentinelRpc: 哨兵服务的 gRPC 客户端
|
|||
|
|
|||
|
### 2. API Service (核心 API 服务)
|
|||
|
|
|||
|
**路径**: `apps/api/`
|
|||
|
|
|||
|
**功能**:
|
|||
|
|
|||
|
- 核心业务 API 处理
|
|||
|
- 数据加密解密
|
|||
|
- 第三方接口代理
|
|||
|
- 业务逻辑处理
|
|||
|
|
|||
|
**业务模块**:
|
|||
|
|
|||
|
- **IVYZ**: 数据查询服务 (7 个 API 端点)
|
|||
|
- **FLXG**: 风险评估服务 (12 个 API 端点)
|
|||
|
- **QYGL**: 企业管理服务 (6 个 API 端点)
|
|||
|
- **YYSY**: 应用系统服务 (7 个 API 端点)
|
|||
|
- **JRZQ**: 金融征信服务 (4 个 API 端点)
|
|||
|
- **COMB**: 组合业务服务 (1 个 API 端点)
|
|||
|
|
|||
|
**特点**:
|
|||
|
|
|||
|
- 所有 API 都需要通过 `ApiAuthInterceptor` 中间件认证
|
|||
|
- 数据采用 AES 加密传输
|
|||
|
- 集成了消息队列服务记录 API 调用
|
|||
|
|
|||
|
### 3. User Service (用户服务)
|
|||
|
|
|||
|
**路径**: `apps/user/`
|
|||
|
|
|||
|
**功能**:
|
|||
|
|
|||
|
- 用户注册、登录、认证
|
|||
|
- 企业认证管理
|
|||
|
- 钱包服务(余额、充值、扣款)
|
|||
|
- API 请求记录管理
|
|||
|
|
|||
|
**gRPC 服务**:
|
|||
|
|
|||
|
- `Auth`: 用户认证服务
|
|||
|
- `User`: 用户信息服务
|
|||
|
- `WalletService`: 钱包服务
|
|||
|
- `Enterprise`: 企业服务
|
|||
|
- `ApiRequestService`: API 请求记录服务
|
|||
|
|
|||
|
**数据模型**:
|
|||
|
|
|||
|
- 用户信息
|
|||
|
- 企业认证信息
|
|||
|
- 钱包余额
|
|||
|
- 扣款记录
|
|||
|
- 充值记录
|
|||
|
- API 请求记录
|
|||
|
|
|||
|
### 4. Sentinel Service (哨兵服务)
|
|||
|
|
|||
|
**路径**: `apps/sentinel/`
|
|||
|
|
|||
|
**功能**:
|
|||
|
|
|||
|
- 产品管理
|
|||
|
- 用户产品关联管理
|
|||
|
- 白名单管理
|
|||
|
- 密钥管理
|
|||
|
- 支付管理
|
|||
|
|
|||
|
**gRPC 服务**:
|
|||
|
|
|||
|
- `product`: 产品服务
|
|||
|
- `userProduct`: 用户产品服务
|
|||
|
- `whitelist`: 白名单服务
|
|||
|
- `secret`: 密钥服务
|
|||
|
- `topUp`: 充值服务
|
|||
|
|
|||
|
### 5. Admin Service (管理端服务)
|
|||
|
|
|||
|
**路径**: `apps/admin/`
|
|||
|
|
|||
|
**功能**:
|
|||
|
|
|||
|
- 管理员认证
|
|||
|
- 企业审核管理
|
|||
|
- 产品管理
|
|||
|
- 用户管理
|
|||
|
- 用户充值
|
|||
|
|
|||
|
**API 模块**:
|
|||
|
|
|||
|
- `auth`: 管理员登录
|
|||
|
- `review`: 企业审核
|
|||
|
- `product`: 产品 CRUD 操作
|
|||
|
- `user`: 用户管理和充值
|
|||
|
|
|||
|
### 6. MQS Service (消息队列服务)
|
|||
|
|
|||
|
**路径**: `apps/mqs/`
|
|||
|
|
|||
|
**功能**:
|
|||
|
|
|||
|
- 消息队列消费者服务
|
|||
|
- API 请求记录处理
|
|||
|
- 异步任务处理
|
|||
|
|
|||
|
**特点**:
|
|||
|
|
|||
|
- 监听 Kafka 消息队列
|
|||
|
- 处理 API 请求日志
|
|||
|
- 支持分布式消息处理
|
|||
|
|
|||
|
### 7. Index Service (索引服务)
|
|||
|
|
|||
|
**路径**: `apps/index/`
|
|||
|
|
|||
|
**功能**:
|
|||
|
|
|||
|
- 产品索引服务
|
|||
|
- 搜索功能支持
|
|||
|
|
|||
|
### 8. WestDex Module (西部对接模块)
|
|||
|
|
|||
|
**路径**: `westDex/`
|
|||
|
|
|||
|
**功能**:
|
|||
|
|
|||
|
- 第三方西部数据源对接
|
|||
|
- 数据加密解密
|
|||
|
- 独立运行的数据处理模块
|
|||
|
|
|||
|
## 共享包 (pkg/)
|
|||
|
|
|||
|
### 1. crypto
|
|||
|
|
|||
|
- AES 加密解密
|
|||
|
- MD5 哈希
|
|||
|
- 西部数据源专用加密
|
|||
|
|
|||
|
### 2. errs
|
|||
|
|
|||
|
- 统一错误处理
|
|||
|
- API 错误码定义
|
|||
|
|
|||
|
### 3. jwt
|
|||
|
|
|||
|
- JWT 令牌生成和验证
|
|||
|
|
|||
|
### 4. models
|
|||
|
|
|||
|
- 消息队列数据模型
|
|||
|
- 通用数据结构
|
|||
|
|
|||
|
### 5. response
|
|||
|
|
|||
|
- 统一响应格式
|
|||
|
|
|||
|
### 6. generate
|
|||
|
|
|||
|
- 支付相关生成器
|
|||
|
|
|||
|
### 7. sqlutil
|
|||
|
|
|||
|
- 数据库工具函数
|
|||
|
|
|||
|
## 中间件系统
|
|||
|
|
|||
|
### 1. AuthInterceptor
|
|||
|
|
|||
|
- 用户身份认证
|
|||
|
- JWT 令牌验证
|
|||
|
- 用户上下文注入
|
|||
|
|
|||
|
### 2. ApiAuthInterceptor
|
|||
|
|
|||
|
- API 调用认证
|
|||
|
- 签名验证
|
|||
|
- 限流控制
|
|||
|
|
|||
|
### 3. EntAuthInterceptor
|
|||
|
|
|||
|
- 企业认证检查
|
|||
|
- 企业用户权限验证
|
|||
|
|
|||
|
### 4. ApiMqsInterceptor
|
|||
|
|
|||
|
- API 调用记录
|
|||
|
- 消息队列发送
|
|||
|
|
|||
|
## 数据库设计
|
|||
|
|
|||
|
### 主要数据表
|
|||
|
|
|||
|
- `users`: 用户基础信息
|
|||
|
- `enterprises`: 企业认证信息
|
|||
|
- `products`: 产品信息
|
|||
|
- `user_products`: 用户产品关联
|
|||
|
- `wallets`: 钱包信息
|
|||
|
- `recharge_records`: 充值记录
|
|||
|
- `deduction_records`: 扣款记录
|
|||
|
- `api_requests`: API 请求记录
|
|||
|
- `pay_orders`: 支付订单
|
|||
|
- `whitelists`: 白名单
|
|||
|
- `secrets`: 密钥管理
|
|||
|
|
|||
|
## 配置管理
|
|||
|
|
|||
|
每个服务都支持多环境配置:
|
|||
|
|
|||
|
- `etc/*.yaml`: 生产环境配置
|
|||
|
- `etc/*.dev.yaml`: 开发环境配置
|
|||
|
|
|||
|
**主要配置项**:
|
|||
|
|
|||
|
- 数据库连接 (MySQL)
|
|||
|
- 缓存配置 (Redis)
|
|||
|
- 服务发现 (Etcd)
|
|||
|
- 第三方服务 (阿里云、七牛云、百度 AI)
|
|||
|
- JWT 配置
|
|||
|
- 消息队列配置
|
|||
|
|
|||
|
## 部署架构
|
|||
|
|
|||
|
### Docker 化部署
|
|||
|
|
|||
|
每个服务都有独立的 Dockerfile:
|
|||
|
|
|||
|
- `apps/*/Dockerfile`
|
|||
|
|
|||
|
### 服务发现
|
|||
|
|
|||
|
- 使用 Etcd 作为服务注册中心
|
|||
|
- gRPC 服务自动注册和发现
|
|||
|
|
|||
|
### 负载均衡
|
|||
|
|
|||
|
- 通过 go-zero 内置的负载均衡机制
|
|||
|
- 支持多种负载均衡策略
|
|||
|
|
|||
|
## 安全机制
|
|||
|
|
|||
|
### 1. 数据传输安全
|
|||
|
|
|||
|
- AES 加密传输
|
|||
|
- HTTPS 协议
|
|||
|
- 签名验证
|
|||
|
|
|||
|
### 2. 身份认证
|
|||
|
|
|||
|
- JWT 令牌认证
|
|||
|
- 多级权限控制
|
|||
|
- 白名单机制
|
|||
|
|
|||
|
### 3. 数据存储安全
|
|||
|
|
|||
|
- 数据库密码加密
|
|||
|
- 敏感信息脱敏
|
|||
|
- 访问日志记录
|
|||
|
|
|||
|
## 监控与日志
|
|||
|
|
|||
|
### 日志系统
|
|||
|
|
|||
|
- 结构化日志记录
|
|||
|
- 分级日志管理
|
|||
|
- 链路追踪支持
|
|||
|
|
|||
|
### 监控指标
|
|||
|
|
|||
|
- API 调用统计
|
|||
|
- 服务健康检查
|
|||
|
- 性能指标监控
|
|||
|
|
|||
|
## 扩展性设计
|
|||
|
|
|||
|
### 水平扩展
|
|||
|
|
|||
|
- 无状态服务设计
|
|||
|
- 数据库读写分离支持
|
|||
|
- 缓存集群支持
|
|||
|
|
|||
|
### 模块化设计
|
|||
|
|
|||
|
- 微服务独立部署
|
|||
|
- 插件化业务模块
|
|||
|
- 模板化代码生成
|
|||
|
|
|||
|
## 开发规范
|
|||
|
|
|||
|
### 代码结构
|
|||
|
|
|||
|
每个微服务遵循 go-zero 标准结构:
|
|||
|
|
|||
|
```
|
|||
|
service/
|
|||
|
├── internal/
|
|||
|
│ ├── config/ # 配置定义
|
|||
|
│ ├── handler/ # HTTP处理器
|
|||
|
│ ├── logic/ # 业务逻辑
|
|||
|
│ ├── svc/ # 服务上下文
|
|||
|
│ ├── types/ # 类型定义
|
|||
|
│ └── middleware/ # 中间件
|
|||
|
├── etc/ # 配置文件
|
|||
|
├── *.api # API定义文件
|
|||
|
├── *.proto # protobuf定义
|
|||
|
└── Dockerfile # 容器化配置
|
|||
|
```
|
|||
|
|
|||
|
### API 设计规范
|
|||
|
|
|||
|
- RESTful API 设计
|
|||
|
- 统一错误码
|
|||
|
- 标准化响应格式
|
|||
|
- 版本控制支持
|
|||
|
|
|||
|
## 总结
|
|||
|
|
|||
|
天远 API 服务器采用了现代化的微服务架构,具备良好的可扩展性、可维护性和安全性。通过 go-zero 框架的支持,实现了高性能的服务间通信和统一的开发规范。整个系统支持多环境部署、监控告警、日志追踪等企业级特性,是一个完整的商业级 API 服务平台。
|