01-架构设计

# 架构设计

> **文档版本**: v1.0.0
> **创建日期**: 2024-01-25
> **最后更新**: 2024-01-25
> **维护人**: 未来鸟FutureBird码巢企业服务引擎开发组
> **状态**: [最新]

> **搜索标签**: 开放平台, 架构设计, API网关, 技术选型

---

## &#128203; 目录

- [1. 系统架构](#1-系统架构)
- [2. 模块划分](#2-模块划分)
- [3. 数据流设计](#3-数据流设计)
- [4. 接口版本管理](#4-接口版本管理)
- [5. 扩展性设计](#5-扩展性设计)

---

## 1. 系统架构

### 1.1 整体架构图

```
┌─────────────────────────────────────────────────────────────────────────┐
│                           第三方系统                                      │
│    ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐     │
│    │  SCMR   │  │  商城   │  │   OA    │  │   GEO   │  │  财务   │     │
│    └────┬────┘  └────┬────┘  └────┬────┘  └────┬────┘  └────┬────┘     │
└─────────┼────────────┼────────────┼────────────┼────────────┼───────────┘
          │            │            │            │            │
          └────────────┴────────────┼────────────┴────────────┘
                                      │
                              ┌───────▼───────┐
                              │   API Gateway  │
                              │   (Kong/APISIX) │
                              └───────┬───────┘
                                      │
┌─────────────────────────────────────┼─────────────────────────────────────┐
│                         开放平台服务层                                   │
│  ┌──────────────────────────────────────────────────────────────────┐   │
│  │                       认证授权层                                   │   │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐            │   │
│  │  │API Key   │ │ OAuth2   │ │ 签名验证  │ │ 权限校验  │            │   │
│  │  │ 认证     │ │ 认证     │ │          │ │          │            │   │
│  │  └──────────┘ └──────────┘ └──────────┘ └──────────┘            │   │
│  └──────────────────────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────────────────────┐   │
│  │                       限流熔断层                                   │   │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐            │   │
│  │  │ QPS限流  │ │ 日量限制  │ │ 熔断降级  │ │ 黑名单   │            │   │
│  │  └──────────┘ └──────────┘ └──────────┘ └──────────┘            │   │
│  └──────────────────────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────────────────────┐   │
│  │                       业务服务层                                   │   │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐            │   │
│  │  │ 应用管理  │ │ 密钥管理  │ │ 权限管理  │ │ 日志服务  │            │   │
│  │  └──────────┘ └──────────┘ └──────────┘ └──────────┘            │   │
│  └──────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────┘
                                      │
┌─────────────────────────────────────┼─────────────────────────────────────┐
│                         核心业务系统                                     │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐       │
│  │ 企业管理  │ │ 人事管理  │ │ 工资管理  │ │ 订单管理  │ │ 库存管理  │       │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘       │
└─────────────────────────────────────────────────────────────────────────┘
                                      │
┌─────────────────────────────────────┼─────────────────────────────────────┐
│                           数据存储层                                     │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐                    │
│  │PostgreSQL│ │  Redis   │ │ 对象存储  │ │ 日志存储  │                    │
│  │ (主库)   │ │ (缓存)   │ │ (文件)   │ │  (ES)    │                    │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘                    │
└─────────────────────────────────────────────────────────────────────────┘
```

### 1.2 技术栈选型

| 层级 | 技术选型 | 说明 |
|------|---------|------|
| 网关层 | Kong / APISIX | API 网关、限流、鉴权 |
| 应用层 | Next.js 16 + TypeScript | 前后端一体化 |
| 认证层 | 自研 + OAuth2 | API Key + OAuth2 双模式 |
| 限流层 | Redis + Lua | 分布式限流 |
| 业务层 | Drizzle ORM | 数据库操作 |
| 存储层 | PostgreSQL + Redis | 持久化 + 缓存 |
| 日志层 | Elasticsearch | 日志存储与分析 |

---

## 2. 模块划分

### 2.1 核心模块

```
开放平台模块
├── api-gateway          # API 网关中间件
│   ├── auth            # 认证中间件
│   ├── rate-limit      # 限流中间件
│   ├── signature       # 签名验证
│   └── permission      # 权限校验
│
├── application         # 应用管理模块
│   ├── register        # 应用注册
│   ├── audit           # 应用审核
│   ├── config          # 应用配置
│   └── stats           # 应用统计
│
├── api-key             # 密钥管理模块
│   ├── generate        # 密钥生成
│   ├── revoke          # 密钥撤销
│   ├── rotate          # 密钥轮换
│   └── monitor         # 密钥监控
│
├── api-docs            # API 文档模块
│   ├── swagger         # Swagger UI
│   ├── try-it          # 在线调试
│   └── sdk-gen         # SDK 生成
│
├── webhook             # 回调管理模块
│   ├── subscribe       # 事件订阅
│   ├── dispatch        # 事件分发
│   ├── retry           # 重试机制
│   └── monitor         # 回调监控
│
└── analytics           # 统计分析模块
    ├── collector       # 数据采集
    ├── aggregator      # 数据聚合
    ├── reporter        # 报表生成
    └── alerter         # 告警通知
```

### 2.2 模块依赖关系

```
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  前端页面    │────▶│   路由层    │────▶│  服务层     │
└─────────────┘     └─────────────┘     └─────────────┘
                                               │
                    ┌──────────────────────────┼──────────────────────────┐
                    │                          │                          │
                    ▼                          ▼                          ▼
            ┌─────────────┐           ┌─────────────┐           ┌─────────────┐
            │  应用服务   │           │  密钥服务   │           │  回调服务   │
            └──────┬──────┘           └──────┬──────┘           └──────┬──────┘
                   │                         │                         │
                   └─────────────────────────┼─────────────────────────┘
                                             │
                                             ▼
                                    ┌─────────────┐
                                    │   存储层    │
                                    │ (DB/Redis)  │
                                    └─────────────┘
```

---

## 3. 数据流设计

### 3.1 API 请求处理流程

```
第三方系统                     开放平台                          核心系统
    │                            │                                │
    │  1. 发起请求               │                                │
    │  (携带签名/Token)          │                                │
    │───────────────────────────▶│                                │
    │                            │                                │
    │                     ┌──────▼──────┐                         │
    │                     │  API Gateway │                         │
    │                     └──────┬──────┘                         │
    │                            │                                │
    │                     ┌──────▼──────┐                         │
    │                     │  2. 认证验证  │                         │
    │                     └──────┬──────┘                         │
    │                            │                                │
    │                     ┌──────▼──────┐                         │
    │                     │  3. 签名校验  │                         │
    │                     └──────┬──────┘                         │
    │                            │                                │
    │                     ┌──────▼──────┐                         │
    │                     │  4. 限流检查  │                         │
    │                     └──────┬──────┘                         │
    │                            │                                │
    │                     ┌──────▼──────┐                         │
    │                     │  5. 权限校验  │                         │
    │                     └──────┬──────┘                         │
    │                            │                                │
    │                            │  6. 调用业务接口                │
    │                            │───────────────────────────────▶│
    │                            │                                │
    │                            │  7. 返回业务数据                │
    │                            │◀───────────────────────────────│
    │                            │                                │
    │  8. 返回响应              │                                │
    │◀───────────────────────────│                                │
```

### 3.2 Webhook 回调流程

```
核心系统                     开放平台                     第三方系统
    │                            │                            │
    │  1. 业务事件触发           │                            │
    │───────────────────────────▶│                            │
    │                            │                            │
    │                     ┌──────▼──────┐                     │
    │                     │ 2. 事件匹配   │                     │
    │                     └──────┬──────┘                     │
    │                            │                            │
    │                     ┌──────▼──────┐                     │
    │                     │ 3. 构建消息   │                     │
    │                     └──────┬──────┘                     │
    │                            │                            │
    │                            │  4. 推送回调                │
    │                            │───────────────────────────▶│
    │                            │                            │
    │                            │  5. 返回结果                │
    │                            │◀───────────────────────────│
    │                            │                            │
    │                     ┌──────▼──────┐                     │
    │                     │ 6. 记录日志   │                     │
    │                     └─────────────┘                     │
```

---

## 4. 接口版本管理

### 4.1 版本策略

```
/api/v1/employees    ← 主版本 v1 (稳定版)
/api/v2/employees    ← 主版本 v2 (新功能)
```

### 4.2 版本生命周期

| 阶段 | 说明 | 持续时间 |
|------|------|---------|
| 发布 | 新功能发布 | - |
| 稳定 | 推荐使用 | 持续维护 |
| 废弃 | 通知用户 | 6个月过渡期 |
| 下线 | 停止服务 | 废弃后执行 |

---

## 5. 扩展性设计

### 5.1 水平扩展

```
┌─────────────────────────────────────────────────────────────────┐
│                        负载均衡层                                │
│                    (Nginx / Cloud LB)                          │
└───────────────────────────┬─────────────────────────────────────┘
                            │
        ┌───────────────────┼───────────────────┐
        │                   │                   │
        ▼                   ▼                   ▼
┌───────────────┐   ┌───────────────┐   ┌───────────────┐
│  API Server   │   │  API Server   │   │  API Server   │
│   实例 1      │   │   实例 2      │   │   实例 3      │
└───────────────┘   └───────────────┘   └───────────────┘
        │                   │                   │
        └───────────────────┼───────────────────┘
                            │
        ┌───────────────────┼───────────────────┐
        │                   │                   │
        ▼                   ▼                   ▼
┌───────────────┐   ┌───────────────┐   ┌───────────────┐
│   PostgreSQL  │   │    Redis      │   │ Elasticsearch │
│   (主从复制)   │   │  (集群模式)   │   │   (集群)      │
└───────────────┘   └───────────────┘   └───────────────┘
```

### 5.2 功能扩展点

| 扩展点 | 扩展方式 | 说明 |
|--------|---------|------|
| 认证方式 | 插件化 | 新增认证策略只需实现接口 |
| 限流策略 | 配置化 | 支持多种限流算法切换 |
| API 接口 | 模块化 | 新增业务接口无需改动框架 |
| Webhook 事件 | 订阅制 | 新增事件类型只需注册 |
| 监控告警 | 可插拔 | 支持对接多种监控系统 |