# OpenAPI模块 - 对外开放API管理

> 专门处理对外开放API的需求，为第三方应用提供安全、稳定的API接入服务

## 模块概述

OpenAPI模块是专门用于管理对外开放API的模块，作为服务提供方，为第三方应用提供API接入服务。该模块提供完整的API管理功能，包括应用注册、认证授权、权限控制、访问限制、调用监控等。

## 功能特点

- **应用管理**: 第三方应用注册、审核、密钥管理
- **认证授权**: 多种认证方式，支持OAuth2.0标准
- **权限控制**: 细粒度的API权限和作用域管理
- **访问限制**: 频率限制、IP白名单、时间窗口控制
- **监控统计**: 调用日志、统计分析、性能监控
- **开发支持**: API文档、SDK、调试工具

## 目录结构

```
app/Module/OpenAPI/
├── AdminControllers/        # 后台管理控制器
│   ├── AppController.php           # 应用管理控制器
│   ├── ApiController.php           # API管理控制器
│   ├── LogController.php           # 调用日志控制器
│   └── StatController.php          # 统计分析控制器
├── Controllers/             # API控制器
│   ├── AuthController.php          # 认证控制器
│   ├── AppController.php           # 应用信息控制器
│   └── WebhookController.php       # 回调控制器
├── Middleware/              # 中间件
│   ├── ApiAuthMiddleware.php       # API认证中间件
│   ├── RateLimitMiddleware.php     # 频率限制中间件
│   ├── ScopeMiddleware.php         # 权限范围中间件
│   └── IpWhitelistMiddleware.php   # IP白名单中间件
├── Commands/                # 命令行工具
│   ├── GenerateApiKeyCommand.php   # 生成API密钥命令
│   ├── CleanExpiredTokensCommand.php # 清理过期令牌命令
│   └── ApiStatsCommand.php         # API统计命令
├── Databases/               # 数据库相关文件
│   └── GenerateSql/         # 数据库创建脚本
├── Docs/                    # 详细文档目录
│   ├── README.md            # 文档索引
│   ├── API文档.md           # API接口文档
│   ├── SDK使用指南.md       # SDK使用指南
│   └── 开发者指南.md        # 开发者指南
├── Enums/                   # 枚举类型定义
│   ├── API_STATUS.php              # API状态枚举
│   ├── APP_STATUS.php              # 应用状态枚举
│   ├── AUTH_TYPE.php               # 认证类型枚举
│   ├── SCOPE_TYPE.php              # 权限范围枚举
│   └── RATE_LIMIT_TYPE.php         # 限流类型枚举
├── Events/                  # 事件类
│   ├── ApiCallEvent.php            # API调用事件
│   ├── AppCreatedEvent.php         # 应用创建事件
│   └── RateLimitExceededEvent.php  # 限流超出事件
├── Listeners/               # 事件监听器
│   ├── ApiCallListener.php         # API调用监听器
│   ├── AppCreatedListener.php      # 应用创建监听器
│   └── RateLimitListener.php       # 限流监听器
├── Models/                  # 数据模型
│   ├── OpenApiApp.php              # 开放API应用模型
│   ├── OpenApiKey.php              # API密钥模型
│   ├── OpenApiScope.php            # API权限范围模型
│   ├── OpenApiLog.php              # API调用日志模型
│   ├── OpenApiRateLimit.php        # 频率限制模型
│   └── OpenApiWebhook.php          # 回调配置模型
├── Providers/               # 服务提供者
│   └── OpenAPIServiceProvider.php  # OpenAPI服务提供者
├── Repositorys/             # 数据仓库
│   ├── OpenApiAppRepository.php    # 应用仓库
│   ├── OpenApiLogRepository.php    # 日志仓库
│   └── OpenApiStatRepository.php   # 统计仓库
├── Services/                # 服务类
│   ├── OpenApiService.php          # 开放API服务
│   ├── AuthService.php             # 认证服务
│   ├── RateLimitService.php        # 限流服务
│   ├── ScopeService.php            # 权限服务
│   ├── LogService.php              # 日志服务
│   └── WebhookService.php          # 回调服务
├── Validators/              # 验证器
│   ├── AppValidator.php            # 应用验证器
│   ├── ApiValidator.php            # API验证器
│   └── AuthValidator.php           # 认证验证器
├── SDK/                     # 客户端SDK
│   ├── PHP/                        # PHP SDK
│   ├── JavaScript/                 # JavaScript SDK
│   └── Python/                     # Python SDK
├── Documentation/           # API文档
│   ├── openapi.yaml               # OpenAPI规范文档
│   ├── postman.json               # Postman集合
│   └── examples/                  # 示例代码
└── Config/                  # 配置文件
    └── openapi.php                # OpenAPI配置
```

## 核心功能

### 1. 应用管理
- 第三方应用注册和审核
- API密钥生成和管理
- 应用状态控制（启用/禁用）
- 应用信息维护

### 2. 认证授权
- API Key认证
- OAuth2.0认证
- JWT Token认证
- 签名认证

### 3. 权限控制
- API权限范围管理
- 细粒度权限控制
- 动态权限分配
- 权限继承机制

### 4. 访问控制
- 频率限制（QPS、QPM、QPD）
- IP白名单控制
- 时间窗口限制
- 并发连接控制

### 5. 监控统计
- 实时调用监控
- 调用日志记录
- 统计分析报表
- 性能指标监控

### 6. 开发支持
- 自动生成API文档
- 多语言SDK支持
- 在线调试工具
- 错误码说明

## 设计原则

### 1. 安全性
- 多层次认证机制
- 敏感信息加密存储
- 访问日志完整记录
- 异常行为监控

### 2. 稳定性
- 限流保护机制
- 熔断降级策略
- 异常处理完善
- 服务监控告警

### 3. 易用性
- 简洁的API设计
- 完善的文档支持
- 丰富的SDK支持
- 友好的错误提示

### 4. 扩展性
- 插件化架构设计
- 支持自定义认证
- 灵活的权限配置
- 可扩展的监控指标

## 与现有模块的关系

### 依赖关系
- **OAuth模块**: 复用OAuth2.0认证机制
- **User模块**: 依赖用户信息进行认证
- **Admin模块**: 使用后台管理组件
- **System模块**: 依赖系统配置和日志

### 服务提供
- 为第三方应用提供API接入服务
- 为内部系统提供API管理能力
- 为开发者提供完整的开发工具链

## 开发规范

### 1. 命名规范
- 控制器以`Controller`结尾
- 服务类以`Service`结尾
- 中间件以`Middleware`结尾
- 模型以`OpenApi`开头

### 2. 代码规范
- 遵循PSR-4自动加载标准
- 使用PHP 8.0+语法特性
- 完善的注释和文档
- 严格的类型声明

### 3. API规范
- 遵循RESTful设计原则
- 统一的响应格式
- 完整的错误码体系
- 版本控制机制

## 使用示例

### 1. 应用注册
```php
use App\Module\OpenAPI\Services\OpenApiService;

$apiService = new OpenApiService();
$app = $apiService->createApp([
    'name' => '第三方应用',
    'description' => '应用描述',
    'callback_url' => 'https://example.com/callback',
    'scopes' => ['user:read', 'data:write']
]);
```

### 2. API调用认证
```php
use App\Module\OpenAPI\Middleware\ApiAuthMiddleware;

// 在路由中使用认证中间件
Route::middleware(['api.auth'])->group(function () {
    Route::get('/api/user', [UserController::class, 'index']);
});
```

### 3. 权限验证
```php
use App\Module\OpenAPI\Services\ScopeService;

$scopeService = new ScopeService();
if ($scopeService->hasScope($app, 'user:read')) {
    // 执行操作
}
```

## 开发状态

- 📋 **规划阶段**: 模块设计和架构规划
- 🚧 **开发中**: 核心功能开发
- ✅ **已完成**: 基础框架搭建

## 版本历史

- **v0.1.0** (计划中) - 基础架构搭建
- **v0.2.0** (计划中) - 认证授权实现
- **v0.3.0** (计划中) - 权限控制完善
- **v1.0.0** (计划中) - 正式版本发布

## 注意事项

1. **安全考虑**: API密钥和敏感信息需要加密存储
2. **性能考虑**: 高频API调用需要优化性能
3. **兼容性**: 保持与现有OAuth模块的兼容性
4. **监控**: 重要操作需要完整的日志记录
5. **文档**: 保持API文档的及时更新

## 后续规划

1. **功能扩展**: 添加更多认证方式和权限控制
2. **性能优化**: 优化高并发场景下的性能
3. **监控完善**: 完善监控指标和告警机制
4. **SDK扩展**: 支持更多编程语言的SDK
5. **文档完善**: 完善开发者文档和示例