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 服务平台。
|