# hello_world_app0 **Repository Path**: taomac/hello_world_app0 ## Basic Information - **Project Name**: hello_world_app0 - **Description**: hello_world - **Primary Language**: Python - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-12-30 - **Last Updated**: 2025-12-30 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # AI智能体REST API接口服务 ## 项目概述 本项目是一个完整的AI智能体管理REST API服务，基于Python开发，使用SQLite数据库存储数据。支持AI智能体的增删改查、搜索和分页等功能，采用分层架构设计，代码结构清晰，易于维护和扩展。 ## 技术栈 - **后端框架**: Flask / Connexion / Python内置HTTP - **数据库**: SQLite3 - **API规范**: OpenAPI 3.0 - **编程语言**: Python 3.6+ - **架构模式**: MVC/分层架构 ## 项目结构 ``` hello_world_app/ ├── src/ # 源代码目录 │ ├── models/ │ │ └── database.py # 数据模型层 │ ├── dao/ │ │ └── agent_dao.py # 数据访问层 │ ├── services/ │ │ └── agent_service.py # 业务逻辑层 │ └── api/ │ ├── openapi.py # API控制器（Connexion） │ └── openapi.yaml # API规范文档 ├── debug/ # 调试和配置目录 │ ├── app.py # Connexion主程序 │ ├── requirements.txt # Python依赖 │ └── settings.json # 配置文件 ├── simple_server.py # Flask服务器 ├── http_server.py # HTTP服务器 ├── api_demo.py # API演示脚本 ├── test_api.py # 功能测试脚本 ├── simple_test.py # 简单测试脚本 ├── doc.md # 项目文档 └── ai_agents.db # SQLite数据库文件 ``` ## 架构设计 ### 分层架构图 ```mermaid graph TB A[客户端] --> B[API控制器层] B --> C[业务逻辑层] C --> D[数据访问层] D --> E[SQLite数据库] B1[HTTP请求处理] --> B C1[业务规则验证] --> C D1[SQL操作封装] --> D E1[ai_agents表] --> E B -.-> F[统一响应格式] C -.-> F D -.-> F ``` ### 各层职责 **1. 数据模型层 (Models)** - 定义AI智能体数据结构 - 管理数据库连接和初始化 - 提供数据转换方法 **2. 数据访问层 (DAO)** - 封装数据库CRUD操作 - 处理SQL查询和结果集 - 管理数据库事务 **3. 业务逻辑层 (Service)** - 实现业务规则和验证 - 统一API响应格式 - 处理异常和错误 **4. 控制器层 (API)** - 处理HTTP请求和响应 - 参数解析和验证 - 路由管理 ## 数据库设计 ### AI智能体表 (ai_agents) | 字段名 | 数据类型 | 约束 | 描述 | |--------|----------|------|------| | id | INTEGER | PRIMARY KEY AUTOINCREMENT | 智能体唯一标识 | | name | TEXT | NOT NULL UNIQUE | 智能体名称 | | description | TEXT | NULL | 智能体描述 | | api_url | TEXT | NOT NULL | API接口地址 | | api_key | TEXT | NULL | API密钥 | | prompt | TEXT | NOT NULL | 提示词 | | created_at | TEXT | NOT NULL | 创建时间 | | updated_at | TEXT | NOT NULL | 更新时间 | ### 索引设计 ```sql CREATE INDEX idx_name ON ai_agents(name); ``` ## API接口文档 ### 基础信息 - **Base URL**: `http://localhost:8000` - **Content-Type**: `application/json` - **响应格式**: 统一JSON格式 ### 统一响应格式 ```json { "status": 0, "msg": "", "data": { // 具体数据内容 } } ``` **字段说明**: - `status`: 状态码，0表示成功，其他为错误码 - `msg`: 消息说明，成功时为空，失败时为错误信息 - `data`: 数据内容，必须为对象类型 ### API接口列表 #### 1. 创建AI智能体 **请求**: ```http POST /ai-agents Content-Type: application/json { "name": "智能体名称", "description": "智能体描述", "api_url": "https://api.example.com/v1", "api_key": "your-api-key", "prompt": "你是一个专业的AI助手" } ``` **响应**: ```json { "status": 0, "msg": "AI智能体创建成功", "data": { "id": 1, "name": "智能体名称", "description": "智能体描述", "api_url": "https://api.example.com/v1", "api_key": "your-api-key", "prompt": "你是一个专业的AI助手", "created_at": "2025-12-26T17:50:27.410901", "updated_at": "2025-12-26T17:50:27.410965" } } ``` #### 2. 获取智能体列表（分页） **请求**: ```http GET /ai-agents?page=1&page_size=10 ``` **响应**: ```json { "status": 0, "msg": "获取AI智能体列表成功", "data": { "list": [ { "id": 1, "name": "智能体名称", "description": "智能体描述", "api_url": "https://api.example.com/v1", "api_key": "your-api-key", "prompt": "你是一个专业的AI助手", "created_at": "2025-12-26T17:50:27.410901", "updated_at": "2025-12-26T17:50:27.410965" } ], "pagination": { "page": 1, "page_size": 10, "total_count": 1, "total_pages": 1, "has_next": false, "has_prev": false } } } ``` #### 3. 搜索智能体 **请求**: ```http GET /ai-agents/search?keyword=客服&page=1&page_size=10 ``` **响应**: ```json { "status": 0, "msg": "搜索AI智能体成功（关键词：客服）", "data": { "keyword": "客服", "list": [ { "id": 1, "name": "客服机器人", "description": "专门处理客户咨询的智能助手", "api_url": "https://api.openai.com/v1/chat/completions", "api_key": "sk-test-key-1", "prompt": "你是一个专业的客服代表", "created_at": "2025-12-26T17:50:30.113216", "updated_at": "2025-12-26T17:50:30.113232" } ], "pagination": { "page": 1, "page_size": 10, "total_count": 1, "total_pages": 1, "has_next": false, "has_prev": false } } } ``` #### 4. 获取智能体详情 **请求**: ```http GET /ai-agents/1 ``` **响应**: ```json { "status": 0, "msg": "获取AI智能体成功", "data": { "id": 1, "name": "智能体名称", "description": "智能体描述", "api_url": "https://api.example.com/v1", "api_key": "your-api-key", "prompt": "你是一个专业的AI助手", "created_at": "2025-12-26T17:50:27.410901", "updated_at": "2025-12-26T17:50:27.410965" } } ``` #### 5. 更新智能体 **请求**: ```http PUT /ai-agents/1 Content-Type: application/json { "description": "更新后的描述", "prompt": "更新后的提示词" } ``` **响应**: ```json { "status": 0, "msg": "AI智能体更新成功", "data": { "id": 1, "name": "智能体名称", "description": "更新后的描述", "api_url": "https://api.example.com/v1", "api_key": "your-api-key", "prompt": "更新后的提示词", "created_at": "2025-12-26T17:50:27.410901", "updated_at": "2025-12-26T17:52:33.455517" } } ``` #### 6. 删除智能体 **请求**: ```http DELETE /ai-agents/1 ``` **响应**: ```json { "status": 0, "msg": "AI智能体删除成功", "data": { "id": 1, "name": "智能体名称", "description": "智能体描述", "api_url": "https://api.example.com/v1", "api_key": "your-api-key", "prompt": "你是一个专业的AI助手", "created_at": "2025-12-26T17:50:27.410901", "updated_at": "2025-12-26T17:50:27.410965" } } ``` ## 错误处理 ### 状态码说明 | 状态码 | HTTP状态 | 描述 | 示例 | |--------|----------|------|------| | 0 | 200/201 | 操作成功 | 创建/更新/删除成功 | | 400 | 400 | 请求参数错误 | 缺少必填字段 | | 404 | 404 | 资源不存在 | 智能体ID不存在 | | 500 | 500 | 服务器内部错误 | 数据库连接失败 | ### 错误响应示例 ```json { "status": 400, "msg": "API URL不能为空", "data": {} } ``` ```json { "status": 404, "msg": "未找到ID为 99999 的AI智能体", "data": {} } ``` ## 部署说明 ### 环境要求 - Python 3.6+ - 操作系统: Windows/macOS/Linux ### 安装依赖 ```bash # 使用Flask版本（推荐） pip install flask flask-cors # 使用Connexion版本 pip install flask connexion[flask,uvicorn,swagger-ui] python-dotenv ``` ### 启动服务 #### 方式1: Flask服务器（推荐） ```bash cd /path/to/project python3 simple_server.py ``` #### 方式2: 原生HTTP服务器 ```bash cd /path/to/project python3 http_server.py ``` #### 方式3: Connexion服务器 ```bash cd /path/to/project/debug python3 app.py ``` ### 访问地址 - **服务地址**: http://localhost:8000 - **API文档**: http://localhost:8000 - **健康检查**: http://localhost:8000 ## 测试说明 ### 功能测试 运行完整的功能测试： ```bash python3 api_demo.py ``` ### 简单测试 运行基础功能测试： ```bash python3 simple_test.py ``` ### 手动测试 使用curl命令测试： ```bash # 创建智能体 curl -X POST http://localhost:8000/ai-agents \ -H "Content-Type: application/json" \ -d '{"name":"测试智能体","api_url":"https://api.test.com","prompt":"你是一个测试智能体"}' # 获取智能体列表 curl -X GET http://localhost:8000/ai-agents # 获取智能体详情 curl -X GET http://localhost:8000/ai-agents/1 # 更新智能体 curl -X PUT http://localhost:8000/ai-agents/1 \ -H "Content-Type: application/json" \ -d '{"description":"更新后的描述"}' # 删除智能体 curl -X DELETE http://localhost:8000/ai-agents/1 ``` ## 开发规范 ### 代码规范 1. **命名规范**: - 类名使用大驼峰命名法（PascalCase） - 函数和变量使用小写下划线命名法（snake_case） - 常量使用全大写下划线命名法（UPPER_CASE） 2. **文件组织**: - 按功能模块分层组织 - 每个文件只负责单一职责 - 导入语句按标准库、第三方库、本地模块排序 3. **注释规范**: - 类和函数必须有文档字符串 - 复杂逻辑需要添加行内注释 - API接口需要详细的参数和返回值说明 ### 数据库规范 1. **表命名**: 使用下划线分隔的小写字母 2. **字段命名**: 使用下划线分隔的小写字母 3. **主键**: 统一使用id字段 4. **时间戳**: created_at和updated_at字段 ### API设计规范 1. **URL规范**: 使用复数名词形式，如`/ai-agents` 2. **HTTP方法**: 遵循RESTful设计原则 3. **响应格式**: 统一的JSON格式 4. **状态码**: 准确反映操作结果 ## 扩展说明 ### 功能扩展建议 1. **认证授权**: 添加JWT或OAuth2认证 2. **日志记录**: 集成日志框架记录操作日志 3. **性能优化**: 添加缓存机制和数据库优化 4. **监控告警**: 集成监控系统 5. **容器化部署**: 支持Docker部署 ### 技术升级建议 1. **数据库**: 升级到PostgreSQL或MySQL 2. **框架**: 升级到FastAPI获得更高性能 3. **异步**: 支持异步处理提升并发能力 4. **微服务**: 拆分为独立的微服务架构 ## 版本信息 - **当前版本**: 1.0.0 - **开发日期**: 2025-12-26 - **开发者**: AI开发助手 - **最后更新**: 2025-12-26 ## 联系方式 如有问题或建议，请通过以下方式联系： - **项目仓库**: `/Users/taofeng/work/安全解决方案/炎凰alertaction/hello_world_app` - **文档位置**: `doc.md` - **测试脚本**: `api_demo.py` --- **注意**: 本项目仅用于演示和学习目的，生产环境使用前请进行充分的安全测试和性能优化。