kknongchang_2506/app/Module/OpenAPI/README.md

OpenAPI模块

OpenAPI模块提供了完整的API管理平台，支持应用管理、多种认证方式、权限控制、频率限制、Webhook回调、统计分析等功能。

🚀 功能特性

核心功能

• 应用管理: 创建和管理API应用，支持应用状态控制
• 多种认证方式: API Key、JWT、OAuth2、签名认证、Basic Auth、Bearer Token
• 权限控制: 基于SCOPE的细粒度权限管理系统
• 频率限制: 多维度API调用频率限制（分钟/小时/天/周/月）
• IP白名单: 支持精确IP、CIDR、通配符匹配
• 日志记录: 详细的API调用日志和错误追踪
• 统计分析: 完整的API使用统计和性能监控
• Webhook支持: 事件驱动的回调机制，支持重试和签名验证

管理功能

• 后台管理: 完整的后台管理界面
• 实时监控: API调用实时监控和告警
• 数据导出: 日志和统计数据导出
• 批量操作: 支持批量管理应用和密钥
• API测试: 内置API测试工具

📦 安装配置

1. 模块注册

确保模块已在 config/app.php 中注册：

'providers' => [
    // ...
    App\Module\OpenAPI\Providers\OpenAPIServiceProvider::class,
],

2. 数据库迁移

运行SQL文件创建相关表：

# 执行数据库SQL文件
mysql -u username -p database_name < app/Module/OpenAPI/Databases/GenerateSql/openapi_tables.sql

3. 环境变量配置

在 .env 文件中添加配置：

# OpenAPI基础配置
OPENAPI_LOGGING_ENABLED=true
OPENAPI_STATS_ENABLED=true

# 频率限制配置
OPENAPI_RATE_LIMIT_PER_MINUTE=60
OPENAPI_RATE_LIMIT_PER_HOUR=1000
OPENAPI_RATE_LIMIT_PER_DAY=10000

# Webhook配置
OPENAPI_WEBHOOK_TIMEOUT=30
OPENAPI_WEBHOOK_RETRY_COUNT=3

# 缓存配置
OPENAPI_CACHE_DRIVER=redis
OPENAPI_CACHE_TTL=3600

4. 发布配置文件（可选）

php artisan vendor:publish --provider="App\Module\OpenAPI\Providers\OpenAPIServiceProvider"

核心功能

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

注意事项

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

后续规划

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