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. 应用注册

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调用认证

use App\Module\OpenAPI\Middleware\ApiAuthMiddleware;

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

3. 权限验证

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 (计划中) - 正式版本发布

注意事项

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

后续规划

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

README.md 8.7 KB History Raw

OpenAPI模块 - 对外开放API管理

模块概述

功能特点

目录结构

核心功能

1. 应用管理

2. 认证授权

3. 权限控制

4. 访问控制

5. 监控统计

6. 开发支持

设计原则

1. 安全性

2. 稳定性

3. 易用性

4. 扩展性

与现有模块的关系

依赖关系

服务提供

开发规范

1. 命名规范

2. 代码规范

3. API规范

使用示例

1. 应用注册

2. API调用认证

3. 权限验证

开发状态

版本历史

注意事项

后续规划

README.md 8.7 KB

History Raw