tianyuan-api-server/项目架构文档.md

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