KairoCore 1.0.0__py3-none-any.whl → 1.2.0__py3-none-any.whl

KairoCore/__init__.py

@@ -1,6 +1,6 @@
 from fastapi import APIRouter as kcRouter
 from .app import run_kairo
-from .utils.panic import Panic, QueryResponse
+from .utils.panic import Panic, QueryResponse, exec_with_route_error
 from .utils.log import get_logger
 from .db_tools.kc_redis import RedisClient
 from .db_tools.kc_zookeeper import ZkClient
@@ -8,6 +8,9 @@ from .db_tools.kc_mysql import MysqlSession, AsyncMysqlSession
 from .utils.sql_tool import SqlTool
 from .utils.kc_timer import Ktimer
 from .utils.kc_re import KcReTool
+from .utils.kc_http import KcHttpSession
+from .utils.kc_upload import KcUploader
+from .utils.auth import KairoAuth
 
 kQuery = QueryResponse()
 
@@ -15,6 +18,7 @@ __all__ = [
     "run_kairo",
     "kcRouter", 
     "Panic", 
+    "exec_with_route_error",
     "kQuery", 
     "get_logger", 
     "RedisClient", 
@@ -23,5 +27,8 @@ __all__ = [
     "AsyncMysqlSession",
     "SqlTool",
     "Ktimer",
-    "KcReTool"
+    "KcReTool",
+    "KcHttpSession",
+    "KcUploader",
+    "KairoAuth",
 ]

KairoCore/common/errors.py

@@ -1,4 +1,5 @@
 from ..utils.panic import Panic
+from .http import HttpStatusCode
 
 # mysql session 异常 业务代码 10010 ~ 10021
 MQSN_INIT_ERROR = Panic(10010, "Mysql配置异常，请检查env配置！")
@@ -23,4 +24,41 @@ KCR_USE_ERROR = Panic(10051, "redis使用异常，请检查！")
 
 
 # kc_re 异常 业务代码 10060 ~ 10069
-KCRE_USE_ERROR = Panic(10060, "正则校验异常，请检查！")
+KCRE_USE_ERROR = Panic(10060, "正则校验异常，请检查！")
+
+
+# kc_http 异常 业务代码 10070 ~ 10079
+KCHT_INIT_ERROR = Panic(10070, "http配置异常，请检查！")
+KCHT_REQUEST_ERROR = Panic(10071, "http请求异常，请检查！")
+KCHT_TIMEOUT_ERROR = Panic(10072, "http请求超时，请检查！")
+KCHT_STATUS_ERROR = Panic(10073, "http状态码异常，请检查！")
+KCHT_PARSE_ERROR = Panic(10074, "http响应解析异常，请检查！")
+
+# kc_upload 异常 业务代码 10080 ~ 10089
+KCU_SAVE_DIR_EMPTY_ERROR = Panic(10080, "保存目录为空", HttpStatusCode.BAD_REQUEST)
+KCU_MKDIR_ERROR = Panic(10081, "创建目录失败", HttpStatusCode.INTERNAL_SERVER_ERROR)
+KCU_FILENAME_EMPTY_ERROR = Panic(10082, "文件名为空", HttpStatusCode.BAD_REQUEST)
+KCU_PARAM_MISSING_ERROR = Panic(10083, "缺少必要参数", HttpStatusCode.BAD_REQUEST)
+KCU_BASE64_PARSE_ERROR = Panic(10084, "Base64 内容解析失败", HttpStatusCode.UNPROCESSABLE_ENTITY)
+KCU_UPLOAD_SAVE_ERROR = Panic(10085, "文件上传失败", HttpStatusCode.INTERNAL_SERVER_ERROR)
+KCU_BASE64_SAVE_ERROR = Panic(10086, "Base64 上传失败", HttpStatusCode.INTERNAL_SERVER_ERROR)
+
+# kc_file_upload_route 异常 业务代码 10090 ~ 10099
+KCFU_UPLOAD_FAIL_ERROR = Panic(10090, "文件上传失败", HttpStatusCode.INTERNAL_SERVER_ERROR)
+KCFU_BASE64_UPLOAD_FAIL_ERROR = Panic(10091, "Base64 上传失败", HttpStatusCode.INTERNAL_SERVER_ERROR)
+
+# kc_panic 辅助方法异常 业务代码 10100 ~ 10109
+KCP_EXEC_AWAITABLE_TYPE_ERROR = Panic(10100, "exec_with_route_error: awaitable 参数必须是可等待对象", HttpStatusCode.BAD_REQUEST)
+KCP_EXEC_PANIC_CONST_TYPE_ERROR = Panic(10101, "exec_with_route_error: error_const 参数必须是 Panic 实例", HttpStatusCode.BAD_REQUEST)
+
+# kc_auth 异常 业务代码 10110 ~ 10129
+KCAUTH_LOGIN_FAILED = Panic(10110, "登录失败", HttpStatusCode.UNAUTHORIZED)
+KCAUTH_TOKEN_INVALID = Panic(10111, "令牌无效", HttpStatusCode.UNAUTHORIZED)
+KCAUTH_TOKEN_EXPIRED = Panic(10112, "令牌已过期", HttpStatusCode.UNAUTHORIZED)
+KCAUTH_REFRESH_INVALID = Panic(10113, "刷新令牌无效", HttpStatusCode.UNAUTHORIZED)
+KCAUTH_REFRESH_EXPIRED = Panic(10114, "刷新令牌已过期", HttpStatusCode.UNAUTHORIZED)
+KCAUTH_TOKEN_REVOKED = Panic(10115, "令牌已撤销", HttpStatusCode.UNAUTHORIZED)
+KCAUTH_PERMISSION_DENIED = Panic(10116, "权限不足", HttpStatusCode.FORBIDDEN)
+KCAUTH_TENANT_REQUIRED = Panic(10117, "需要租户信息", HttpStatusCode.FORBIDDEN)
+KCAUTH_ROLE_REQUIRED = Panic(10118, "需要角色权限", HttpStatusCode.FORBIDDEN)
+KCAUTH_CONFIG_ERROR = Panic(10119, "认证配置错误，请检查环境变量", HttpStatusCode.INTERNAL_SERVER_ERROR)

KairoCore/docs/CodeGenerateDoc.md

@@ -0,0 +1,58 @@
+# 🛠️ 代码生成器使用指南
+
+KairoCore 提供了强大的代码生成器，可以一键生成完整的 CRUD 代码结构，大大提高开发效率。
+
+### 访问代码生成器
+
+启动应用后，访问 `/api/generator` 路径即可打开代码生成器页面。
+
+### 使用步骤
+
+1. **填写基本信息**：
+   - **路由名称（英文）**：必填，如 `user`，将用于生成文件名和类名
+   - **路由中文名称**：可选，如 `用户`，将用于生成注释和文档
+   - **数据库表名**：可选，默认为 `{路由名称}_info`，如 `user_info`
+
+2. **点击生成代码**：
+   代码生成器将根据输入信息生成以下四个模块的代码：
+   - **Action 模块**：包含 API 路由和控制器逻辑
+   - **Schema 模块**：包含数据传输对象和验证规则
+   - **Domain 模块**：包含业务逻辑和领域模型
+   - **DAO 模块**：包含数据访问对象和数据库操作
+
+3. **查看和复制代码**：
+   生成的代码将以文件形式展示，每个文件都有独立的复制按钮，可以一键复制到剪贴板。
+
+### 生成的代码结构
+
+代码生成器会生成完整的分层架构代码：
+
+```
+{路由名称}/
+├── action/{路由名称}/{路由名称}.py     # API 控制器
+├── schema/{路由名称}/{路由名称}.py     # 数据传输对象
+├── domain/{路由名称}/{路由名称}.py     # 领域模型和业务逻辑
+└── dao/{路由名称}/{路由名称}.py        # 数据访问对象
+```
+
+### 功能特性
+
+- **完整的 CRUD 操作**：包含增删改查和分页查询功能
+- **数据验证**：自动生成 Pydantic 验证规则
+- **数据库操作**：包含常用的 SQL 操作封装
+- **错误处理**：统一的异常处理机制
+- **类型提示**：完整的类型注解支持
+- **文档注释**：详细的函数和类文档
+
+### 注意事项
+
+1. 生成的代码可能需要根据实际业务需求进行调整
+2. 错误码和常量需要在 `common/errors.py`和 `common/consts.py`中定义
+3. 数据库表结构需要提前创建并与生成的代码匹配
+4. 生成的代码遵循 KairoCore 的分层架构规范
+
+通过代码生成器，您可以快速搭建业务模块的基础代码结构，专注于业务逻辑的实现而非重复的代码编写。
+
+<div align="center">
+  <img src="https://github.com/Fatosy/KairoCore/blob/master/imgs/code_generator.png" alt="KairoCore Code Generator" />
+</div>

KairoCore/docs/FileUploadDoc.md

@@ -0,0 +1,142 @@
+# 📦 文件上传功能使用说明
+
+本说明文档介绍如何在 KairoCore 项目中使用文件上传功能，包含两种上传方式：multipart/form-data 上传和 Base64 字符串上传。内容简洁明了，开箱即用。😊
+
+---
+
+## ✨ 功能概览
+- 支持两种上传方式：
+  - multipart 上传（UploadFile）：POST `/example/api/file_upload/upload`
+  - Base64 上传（JSON）：POST `/example/api/file_upload/upload_base64`
+- 统一响应格式：`kQuery.to_response(...)`
+- 签名约束：路由函数仅使用 `query/body/file` 参数名（由 `utils/router.enforce_signature` 强制），使接口更清晰规范。
+
+---
+
+## 📁 路径与入参
+
+### 1) multipart 上传
+- 路径：`POST /example/api/file_upload/upload`
+- 请求类型：`multipart/form-data`
+- 表单字段：
+  - `file`：文件内容（必填）
+  - `target_dir`：保存目录（选填，默认 `/tmp`）
+  - `filename`：保存文件名（选填，默认使用原文件名）
+- 代码片段：
+```python
+@router.post("/upload")
+async def upload_file(query: UploadQuery, file: UploadFile):
+    uploader = KcUploader(default_target_dir="/tmp")
+    result = await exec_with_route_error(
+        uploader.save_upload_file(file=file, target_dir=query.target_dir, filename=query.filename),
+        KCFU_UPLOAD_FAIL_ERROR,
+    )
+    return kQuery.to_response(data=result, msg="上传成功")
+```
+- curl 示例：
+```bash
+curl -X POST http://localhost:9140/example/api/file_upload/upload \
+  -F "file=@/path/to/local/file.png" \
+  -F "target_dir=/tmp" \
+  -F "filename=my_file.png"
+```
+- 典型响应：
+```json
+{
+  "data": {
+    "saved_path": "/tmp/my_file.png",
+    "filename": "my_file.png",
+    "size": 12345
+  },
+  "msg": "上传成功"
+}
+```
+
+### 2) Base64 上传
+- 路径：`POST /example/api/file_upload/upload_base64`
+- 请求类型：`application/json`
+- JSON 字段：
+  - `content_base64`：Base64 编码的文件内容（必填）
+  - `filename`：保存文件名（必填）
+  - `target_dir`：保存目录（选填，默认 `/tmp`）
+- 代码片段：
+```python
+@router.post("/upload_base64")
+async def upload_base64(body: Base64Body):
+    uploader = KcUploader(default_target_dir="/tmp")
+    result = await exec_with_route_error(
+        uploader.save_base64(content_base64=body.content_base64, filename=body.filename, target_dir=body.target_dir),
+        KCFU_BASE64_UPLOAD_FAIL_ERROR,
+    )
+    return kQuery.to_response(data=result, msg="上传成功")
+```
+- curl 示例：
+```bash
+curl -X POST http://localhost:9140/example/api/file_upload/upload_base64 \
+  -H "Content-Type: application/json" \
+  -d '{
+        "content_base64": "iVBORw0KGgoAAAANSUhEUg...", 
+        "filename": "my_file.png",
+        "target_dir": "/tmp"
+      }'
+```
+- 典型响应：
+```json
+{
+  "data": {
+    "saved_path": "/tmp/my_file.png",
+    "filename": "my_file.png",
+    "size": 12345
+  },
+  "msg": "上传成功"
+}
+```
+
+---
+
+## 🧰 使用建议
+- 大文件上传：根据实际场景调整 Nginx/网关的上传大小限制；后端也可设置合理的文件大小上限。
+- 文件命名：建议前端传入明确的 `filename`，避免后端根据临时文件名生成不易识别的名称。
+- 保存目录：默认 `/tmp`，可通过 `target_dir` 覆盖，请确保运行环境有写权限。
+- 安全考虑：对上传内容进行扩展名/类型校验，避免执行型文件被误当资源保存；必要时放置到隔离目录并设置严格访问策略。
+
+---
+
+## 🚀 快速自测
+1) 启动示例服务：
+```bash
+cd /home/Coding/KairoCore/example/your_project_name
+python main.py
+```
+2) multipart 测试：
+```bash
+curl -X POST http://localhost:9140/example/api/file_upload/upload \
+  -F "file=@/path/to/local/file.png" -F "target_dir=/tmp" -F "filename=test.png"
+```
+3) Base64 测试：
+```bash
+curl -X POST http://localhost:9140/example/api/file_upload/upload_base64 \
+  -H "Content-Type: application/json" \
+  -d '{"content_base64":"iVBORw0KG...","filename":"test.png","target_dir":"/tmp"}'
+```
+4) 下载接口测试：
+- 浏览器访问：
+  - `http://localhost:9140/example/api/file_upload/download?path=/tmp/test.png&name=my_download.png`
+- curl（保存到本地并使用服务器文件名）：
+```bash
+curl -OJ "http://localhost:9140/example/api/file_upload/download?path=/tmp/test.png&name=my_download.png"
+```
+- 说明：
+  - `path` 为服务器本地已保存的文件路径
+  - `name` 为浏览器下载展示的文件名（可选）
+  - 若需内联预览（如图片/PDF），可添加 `&inline=true`
+
+---
+
+## 📎 相关文件
+- 路由：`example/your_project_name/action/file_upload.py`
+- 上传工具：`utils/kc_upload.py`（KcUploader）
+- 错误常量：`common/errors.py`（KCFU_UPLOAD_FAIL_ERROR、KCFU_BASE64_UPLOAD_FAIL_ERROR）
+- 路由签名约束：`utils/router.py`（enforce_signature）
+
+祝你上传顺利！📤✨

KairoCore/docs/HttpSessionDoc.md

@@ -0,0 +1,170 @@
+# 🌐 HTTP 会话使用说明（KcHttpSession）
+
+本指南介绍如何使用项目内置的异步 HTTP 会话类 KcHttpSession，进行稳定可靠的外部接口调用。内容简洁明了，示例可直接复制运行。🚀
+
+---
+
+## ✨ 功能概览
+- 统一的响应封装：`KcHttpResponse`（自动解析 JSON/Text/Bytes）
+- 稳健的请求能力：超时、重试、退避、状态码检查、日志
+- 连接池与性能：`httpx.AsyncClient` 连接复用与 keep-alive
+- 可选参数：`base_url`、`headers`、`verify`、`proxies`、`timeout`、`retries`、`retry_backoff`
+- 下载能力：`session.download(url, save_path)` 流式写入
+
+---
+
+## 📦 安装前提
+项目已内置依赖 `httpx`，直接使用即可。
+
+---
+
+## 🚀 快速上手
+```python
+import asyncio
+from KairoCore.utils.kc_http import KcHttpSession
+
+async def main():
+    # 建议在应用范围内复用会话（保持连接池与性能）
+    async with KcHttpSession(base_url="https://api.example.com", timeout=10, retries=2) as session:
+        # GET 请求（自动拼接 base_url）
+        resp = await session.get("/v1/ping", params={"q": "hello"})
+        print(resp.status_code, resp.data)
+
+        # POST 请求（JSON）
+        resp2 = await session.post("/v1/items", json={"name": "demo"})
+        print(resp2.status_code, resp2.data)
+
+asyncio.run(main())
+```
+
+---
+
+## 📄 响应结构：KcHttpResponse
+- `status_code: int` —— HTTP 状态码
+- `headers: Dict[str, str]` —— 响应头
+- `data: Any` —— 自动解析：
+  - `application/json` → `resp.json()`（dict/list）
+  - `text/*` 或空 `Content-Type` → `resp.text`（str）
+  - 其他 → `resp.content`（bytes）
+- `raw: httpx.Response` —— 原始响应对象
+- `is_ok(): bool` —— 状态码是否在 2xx
+
+示例：
+```python
+if resp.is_ok():
+    print("✅ OK", resp.data)
+else:
+    print("❌ Bad status:", resp.status_code)
+```
+
+---
+
+## 🔧 常用请求示例
+```python
+# 1) GET with params & 临时 headers 覆盖
+resp = await session.get("/v1/search", params={"q": "kairo"}, headers={"X-Trace": "abc"})
+
+# 2) POST: JSON 请求体
+resp = await session.post("/v1/create", json={"title": "hello"})
+
+# 3) POST: 表单或字符串/二进制数据
+resp = await session.post("/v1/upload", data={"k": "v"})
+# 或：resp = await session.post("/v1/raw", data=b"binary-data")
+
+# 4) PUT / DELETE
+await session.put("/v1/items/123", json={"name": "new"})
+await session.delete("/v1/items/123")
+
+# 5) 单次请求自定义超时（覆盖会话默认）
+resp = await session.get("/v1/slow", timeout=3.0)
+```
+
+---
+
+## 📥 文件下载
+```python
+save_path = await session.download("https://example.com/file.zip", 
+                                  save_path="/tmp/file.zip",
+                                  chunk_size=1024*64)
+print("已保存到:", save_path)
+```
+
+---
+
+## 🧯 错误处理
+KcHttpSession 会在合适的时机抛出统一的错误类型，便于上层捕获与统一处理：
+- `KCHT_INIT_ERROR` —— 会话初始化失败（参数/环境问题）
+- `KCHT_TIMEOUT_ERROR` —— 请求超时
+- `KCHT_STATUS_ERROR` —— 4xx/5xx 状态码错误（5xx可重试，4xx不重试）
+- `KCHT_REQUEST_ERROR` —— 其他请求错误（网络/协议等）
+- `KCHT_PARSE_ERROR` —— 响应解析失败（Content-Type 与内容不匹配等）
+
+示例：
+```python
+from KairoCore.common.errors import (
+    KCHT_TIMEOUT_ERROR, KCHT_STATUS_ERROR, KCHT_REQUEST_ERROR, KCHT_PARSE_ERROR
+)
+
+try:
+    resp = await session.get("/v1/data")
+    print(resp.data)
+except KCHT_TIMEOUT_ERROR as e:
+    print("⏳ 超时:", e)
+except KCHT_STATUS_ERROR as e:
+    print("🔢 状态码异常:", e)
+except KCHT_PARSE_ERROR as e:
+    print("🧩 解析失败:", e)
+except KCHT_REQUEST_ERROR as e:
+    print("📡 请求错误:", e)
+```
+
+---
+
+## ⚙️ 参数说明与实践建议
+- `base_url`：设置后可在请求中使用相对路径（如 `/v1/items`），更易维护。
+- `timeout`：会话默认超时（秒）。可在单次请求中通过 `timeout=` 覆盖。
+- `retries`：重试次数（默认 2）。服务器 5xx 会重试，客户端 4xx 不重试。
+- `retry_backoff`：退避系数（默认 0.5），每次重试会 `await asyncio.sleep(backoff * attempt)`。
+- `max_keepalive`：连接池并发上限（默认 10）。高并发场景可适当调大。
+- `headers`：会话级公共 Header，可在每次请求 `headers` 临时覆盖/追加。
+- `verify`：TLS 校验（True/False 或 CA 路径）。生产环境建议保持开启。
+- `proxies`：代理（字符串或字典），如需通过网关访问外部服务。
+- 日志：内置关键日志，便于排查（初始化、关闭、下载完成、重试等）。
+
+最佳实践：
+- 复用会话实例（例如挂载到 `app.state`）以最大化连接池收益。
+- 为慢接口设置单次请求 `timeout`，避免阻塞。
+- 对关键外部依赖适度提高 `retries` 与 `max_keepalive`。
+
+---
+
+## 🔌 与 FastAPI 生命周期集成（可选）
+在 `app.py` 或 `example/your_project_name/main.py` 中：
+```python
+from KairoCore.utils.kc_http import KcHttpSession
+
+kc_http = KcHttpSession(base_url="https://api.example.com", timeout=10, retries=2)
+app.state.kc_http = kc_http
+
+@app.on_event("startup")
+async def startup_event():
+    # 可在此进行健康检查或预热
+    pass
+
+@app.on_event("shutdown")
+async def shutdown_event():
+    await app.state.kc_http.close()
+```
+
+---
+
+## 📚 相关文件
+- 会话实现：`utils/kc_http.py`
+- 错误常量：`common/errors.py`
+
+如需将鉴权（API_KEY 或 Token）加入外部请求的 `headers`，也可在会话级统一设置，例如：
+```python
+session = KcHttpSession(headers={"Authorization": "Bearer <token>", "X-API-Key": "<api_key>"})
+```
+
+祝你调用顺利！🌈