aury-boot 0.0.11__tar.gz → 0.0.12__tar.gz

{aury_boot-0.0.11 → aury_boot-0.0.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aury-boot
-Version: 0.0.11
+Version: 0.0.12
 Summary: Aury Boot - 基于 FastAPI 生态的企业级 API 开发框架
 Requires-Python: >=3.13
 Requires-Dist: alembic>=1.17.2

{aury_boot-0.0.11 → aury_boot-0.0.12}/aury/boot/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.0.11'
-__version_tuple__ = version_tuple = (0, 0, 11)
+__version__ = version = '0.0.12'
+__version_tuple__ = version_tuple = (0, 0, 12)
 
 __commit_id__ = commit_id = None

{aury_boot-0.0.11 → aury_boot-0.0.12}/aury/boot/commands/templates/project/aury_docs/10-storage.md.tpl

@@ -11,17 +11,20 @@ pip install "aury-sdk-storage[aws]"
 
 ## 10.2 基本用法（StorageManager）
 
-`StorageManager` 支持**命名多实例**，可以同时管理多个存储后端。
+`StorageManager` 支持**命名多实例**，内部使用 `aury-sdk-storage` 提供的 `StorageFactory.from_config()` 智能选择后端（COS 原生 / S3 兼容等），对上层暴露统一接口。
 
 ```python
 from aury.boot.infrastructure.storage import (
-    StorageManager, StorageConfig, StorageBackend, StorageFile,
+    StorageManager,
+    StorageConfig,
+    StorageBackend,
+    StorageFile,
 )
 
 # 默认实例
 storage = StorageManager.get_instance()
 await storage.initialize(StorageConfig(
-    backend=StorageBackend.COS,
+    backend=StorageBackend.COS,  # 自动选择 COS 原生 SDK 或 S3 兼容模式
     bucket_name="my-bucket-1250000000",
     region="ap-guangzhou",
     endpoint="https://cos.ap-guangzhou.myqcloud.com",
@@ -45,6 +48,12 @@ url = await storage.upload_file(
     )
 )
 
+# 批量上传
+urls = await storage.upload_files([
+    StorageFile(object_name="img/1.jpg", data=b"..."),
+    StorageFile(object_name="img/2.jpg", data=b"..."),
+])
+
 # 下载文件
 content = await storage.download_file("user/123/avatar.png")
 
@@ -58,7 +67,38 @@ exists = await storage.file_exists("user/123/avatar.png")
 await storage.delete_file("user/123/avatar.png")
 ```
 
-## 10.3 STS 临时凭证（前端直传）
+## 10.3 高级用法：直接使用 SDKStorageFactory / StorageType
+
+对于需要更精细控制后端类型（如在脚手架或基础设施层扩展存储实现）的场景，可以直接使用 SDK 导出的类型：
+
+```python
+from aury.boot.infrastructure.storage import (
+    COSStorage,
+    LocalStorage,
+    S3Storage,
+    SDKStorageFactory,  # SDK 工厂（基于 StorageType 枚举）
+    StorageConfig,
+    StorageFile,
+    StorageType,
+)
+
+# 使用 StorageType 创建后端
+config = StorageConfig(
+    backend=StorageType.COS,
+    bucket_name="my-bucket-1250000000",
+    region="ap-guangzhou",
+)
+
+backend = SDKStorageFactory.from_config(config)
+result = await backend.upload_file(
+    StorageFile(object_name="dev/test.txt", data=b"hello"),
+)
+print(result.url)
+```
+
+> 一般业务代码直接通过 `StorageManager` 即可，只有在需要自定义装配流程或编写基础设施扩展时才需要直接使用 `SDKStorageFactory` / `StorageType` / `COSStorage` 等类型。
+
+## 10.4 STS 临时凭证（前端直传）
 
 ```python
 from aury.sdk.storage.sts import (
@@ -95,11 +135,14 @@ return {{
 }}
 ```
 
-## 10.4 本地存储（开发测试）
+## 10.5 本地存储（开发测试）
 
 ```python
 from aury.boot.infrastructure.storage import (
-    StorageManager, StorageConfig, StorageBackend, StorageFile,
+    StorageManager,
+    StorageConfig,
+    StorageBackend,
+    StorageFile,
 )
 
 storage = StorageManager.get_instance()

{aury_boot-0.0.11 → aury_boot-0.0.12}/aury/boot/commands/templates/project/aury_docs/16-adapter.md.tpl

@@ -33,7 +33,7 @@ class PaymentAdapter(BaseAdapter):
         # 真实调用第三方 API
         response = await self.http_client.post(
             "https://api.payment.com/orders",
-            json={"amount": amount, "order_id": order_id},
+            json={{"amount": amount, "order_id": order_id}},
         )
         return response.json()
 
@@ -41,12 +41,12 @@ class PaymentAdapter(BaseAdapter):
     async def create_order_mock(self, amount: int, order_id: str) -> dict:
         """创建支付订单（Mock 实现）。"""
         if amount > 100000:
-            return {"success": False, "error": "金额超限"}
-        return {
+            return {{"success": False, "error": "金额超限"}}
+        return {{
             "success": True,
-            "transaction_id": f"mock_tx_{order_id}",
+            "transaction_id": f"mock_tx_{{order_id}}",
             "amount": amount,
-        }
+        }}
 
     @adapter_method("query_order")
     async def query_order(self, transaction_id: str) -> dict:
@@ -59,11 +59,11 @@ class PaymentAdapter(BaseAdapter):
     @query_order.mock
     async def query_order_mock(self, transaction_id: str) -> dict:
         """查询支付订单（Mock）。"""
-        return {
+        return {{
             "transaction_id": transaction_id,
             "status": "paid",
             "mock": True,
-        }
+        }}
 ```
 
 ## 16.3 Adapter 配置
@@ -78,7 +78,7 @@ THIRD_PARTY__GATEWAY_MODE=mock
 
 # 方法级模式覆盖（JSON 格式）
 # 例如：query 方法使用 real，其他方法使用全局配置
-THIRD_PARTY__METHOD_MODES={"query_order": "real"}
+THIRD_PARTY__METHOD_MODES={{"query_order": "real"}}
 
 # Mock 策略：decorator（装饰器）/ auto（自动生成）
 THIRD_PARTY__MOCK_STRATEGY=decorator
@@ -140,7 +140,7 @@ class WechatAdapter(HttpAdapter):
         return await self._request(
             "POST",
             "/cgi-bin/message/send",
-            json={"touser": openid, "content": content},
+            json={{"touser": openid, "content": content}},
         )
 
     @send_message.mock
@@ -156,13 +156,13 @@ class WechatAdapter(HttpAdapter):
 ```python
 settings = AdapterSettings(
     mode="mock",  # 默认 Mock
-    method_modes={
+    method_modes={{
         "query_order": "real",      # 查询走真实接口
         "create_order": "mock",     # 创建走 Mock
         "refund": "disabled",       # 退款禁用
-    },
+    }},
+    debug=True,
 )
-
 adapter = PaymentAdapter("payment", settings)
 
 # query_order 会调用真实 API
@@ -237,19 +237,19 @@ class PaymentAdapter(HttpAdapter):
         self, method: str, args: tuple, kwargs: dict
     ) -> None:
         """调用前钩子。"""
-        logger.info(f"调用 {method}，参数: {args}")
+        logger.info(f"调用 {{method}}，参数: {{args}}")
 
     async def _on_after_call(
         self, method: str, args: tuple, kwargs: dict, result: Any
     ) -> None:
         """调用后钩子。"""
-        logger.info(f"{method} 返回: {result}")
+        logger.info(f"{{method}} 返回: {{result}}")
 
     async def _on_call_error(
         self, method: str, args: tuple, kwargs: dict, error: Exception
     ) -> None:
         """调用异常钩子。"""
-        logger.error(f"{method} 异常: {error}")
+        logger.error(f"{{method}} 异常: {{error}}")
         # 可以在这里发送告警
 ```
 
@@ -277,11 +277,11 @@ class CompositePaymentAdapter(BaseAdapter):
     @pay.mock
     async def pay_mock(self, channel: str, amount: int, order_id: str) -> dict:
         """统一 Mock 实现。"""
-        return {
+        return {{
             "success": True,
             "channel": channel,
-            "transaction_id": f"mock_{channel}_{order_id}",
-        }
+            "transaction_id": f"mock_{{channel}}_{{order_id}}",
+        }}
 ```
 
 ## 16.8 异常处理
@@ -303,9 +303,9 @@ except AdapterTimeoutError:
     logger.error("支付适配器超时")
     # 重试或告警
 except AdapterValidationError as e:
-    logger.error(f"参数校验失败: {e}")
+    logger.error(f"参数校验失败: {{e}}")
 except AdapterError as e:
-    logger.error(f"适配器错误: {e}")
+    logger.error(f"适配器错误: {{e}}")
 ```
 
 ## 16.9 最佳实践
@@ -329,16 +329,16 @@ async def create_order_mock(self, amount: int, order_id: str) -> dict:
     """Mock 应模拟各种场景。"""
     # 模拟金额校验
     if amount <= 0:
-        return {"success": False, "error": "金额必须大于0"}
+        return {{"success": False, "error": "金额必须大于0"}}
     if amount > 100000:
-        return {"success": False, "error": "金额超限"}
+        return {{"success": False, "error": "金额超限"}}
 
     # 模拟偶发失败（可选）
     import random
     if random.random() < 0.01:
-        return {"success": False, "error": "系统繁忙"}
+        return {{"success": False, "error": "系统繁忙"}}
 
-    return {"success": True, "transaction_id": f"mock_{order_id}"}
+    return {{"success": True, "transaction_id": f"mock_{{order_id}}"}}
 ```
 
 ### 3. 环境配置建议
@@ -381,11 +381,11 @@ class OrderService(BaseService):
     async def create_order(self, user_id: str, amount: int) -> Order:
         """创建订单并发起支付。"""
         # 1. 创建订单记录
-        order = await self.order_repo.create({
+        order = await self.order_repo.create({{
             "user_id": user_id,
             "amount": amount,
             "status": "pending",
-        })
+        }})
 
         # 2. 调用支付适配器
         pay_result = await self.payment.create_order(amount, str(order.id))
@@ -394,10 +394,10 @@ class OrderService(BaseService):
             raise PaymentError(pay_result["error"])
 
         # 3. 更新订单状态
-        await self.order_repo.update(order, {
+        await self.order_repo.update(order, {{
             "transaction_id": pay_result["transaction_id"],
             "status": "paid",
-        })
+        }})
 
         return order
 ```