添加依赖注入支持 (#57)

Author: JohnRichard4096

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "python.analysis.autoImportCompletions": true
+}

README.md

@@ -26,17 +26,18 @@
 
 ## 核心特性
 
-`nonebot_plugin_value` 是一个基于 NoneBot2 的通用经济系统插件，提供以下核心功能：
-
-- 📈 账户系统：各货币账户独立
-- 🪙 多货币系统：支持创建任意数量的货币类型
-- 💰 原子化交易：保证转账等操作的事务性
-- 🔁 钩子系统：支持交易前后触发自定义逻辑
-- 📊 完整审计：所有交易记录包含完整上下文信息
-- 🔐 安全控制：支持负余额限制
-- 📝 批量操作：支持批量修改用户的货币数据
-- 🔍 时间范围审计日志：从时间范围获取交易记录
-- 🚀 导出数据：支持从Json文件导入，导出到Json文件
+`nonebot_plugin_value` 是一个基于 NoneBot2 的通用经济系统插件，提供以下核心功能:  
+
+- 📈 账户系统:  各货币账户独立
+- 🪙 多货币系统:  支持创建任意数量的货币类型
+- 💰 原子化交易:  保证转账等操作的事务性
+- 🔁 钩子系统:  支持交易前后触发自定义逻辑
+- 📊 完整审计:  所有交易记录包含完整上下文信息
+- 🔐 安全控制:  支持负余额限制
+- 📝 批量操作:  支持批量修改用户的货币数据
+- 🔍 时间范围审计日志:  从时间范围获取交易记录
+- 🚀 导出数据: 支持从Json文件导入，导出到Json文件
+- 🔧 依赖注入: 支持依赖注入模式调用
 
 ### 快速开始
 

docs/api.md

@@ -47,6 +47,8 @@ erDiagram
 
 > 开发规范：我们推荐您使用 UUID.hex 作为唯一 ID，而不是直接传入 ID（我们在uuid_lib.py提供了字符串转换函数`to_uuid`）。
 
+### [依赖注入](./apis/depends.md)
+
 ### [标准 API(表现层)](./apis/standard.md)
 
 ### [进阶 API(服务层)](./apis/advanced.md)

docs/apis/depends.md

@@ -0,0 +1,92 @@
+# EconomyValue-依赖注入模式 API 文档
+
+> **本质为 [标准 API](./standard.md) 的二次封装，用于依赖注入**
+
+## `~.api.depends.factory`
+
+> **依赖注入模式工厂**
+
+```python
+class DependsSwitch:
+    @staticmethod
+    def account_data(
+        *,
+        currency_id: str | None = None,
+    ) -> Callable[..., Awaitable[UserAccountData]]:
+        """获得账户数据
+
+        Args:
+            currency_id (str | None, optional): 货币ID. Defaults to None.
+
+        Returns:
+            Callable[..., Awaitable[UserAccountData]]: 可供NoneBot调用的依赖函数类
+        """
+        ...
+
+    @staticmethod
+    def currency_data(
+        *,
+        currency_id: str | None = None,
+    ) -> Callable[..., Awaitable[CurrencyData | None]]:
+        """
+        获取货币数据依赖函数
+
+        Args:
+            currency_id (str | None, optional): 货币ID. Defaults to None.
+
+        Returns:
+            Callable[..., Awaitable[CurrencyData | None]]: 可供NoneBot调用的依赖函数类
+        """
+        ...
+
+    @staticmethod
+    def transaction_data(
+        *,
+        limit: int = 10,
+        timerange: tuple[float, float] | None = None,
+    ) -> Callable[..., Awaitable[list[TransactionData]]]:
+        """
+        获取交易记录
+
+        Args:
+            limit (int, optional): 交易记录数量限制. Defaults to 10.
+            timerange (tuple[float, float] | None, optional): 时间范围. Defaults to None.
+
+        Returns:
+            Callable[..., Awaitable[list[TransactionData]]]: 可供NoneBot调用的依赖函数类
+        """
+        ...
+
+    @staticmethod
+    def account_executor(
+        *,
+        currency_id: str | None = None,
+    ) -> Callable[..., Awaitable[AccountExecutor]]:
+        """
+        Args:
+            currency_id (str | None, optional): 货币ID. Defaults to None.
+
+        Returns:
+            Callable[..., Awaitable[AccountExecutor]]: 账号数据操作对象
+        """
+        ...
+
+```
+
+## 示例使用
+
+```python
+from nonebot import on_command, require
+from nonebot.adapters import Event
+from nonebot.params import Depends
+
+require("nonebot_plugin_value")
+from nonebot_plugin_value.api.depends.factory import DependsSwitch, UserAccountData
+
+test = on_command("test")
+
+
+@test.handle()
+async def _(user_data: UserAccountData = Depends(DependsSwitch.account_data())):
+    await test.finish(user_data.balance)
+```

nonebot_plugin_value/__init__.py

@@ -7,6 +7,7 @@
 from . import action_type, migrations, repository
 from .api import api_balance, api_currency, api_transaction
 from .api.api_currency import get_or_create_currency
+from .api.depends import factory
 from .hook import context, exception, hooks_manager, hooks_type
 from .models import currency
 from .pyd_models import balance_pyd, base_pyd, currency_pyd
@@ -21,8 +22,8 @@
     usage="请查看API文档。",
     type="library",
     homepage="https://github.com/JohnRichard4096/nonebot_plugin_value",
-    extra={"orm_version_location": migrations}, # 迁移文件
-    supported_adapters=None, # 没有使用任何适配器提供的功能
+    extra={"orm_version_location": migrations},  # 迁移文件
+    supported_adapters=None,
 )
 
 __all__ = [
@@ -38,6 +39,7 @@
     "currency_api",
     "currency_pyd",
     "exception",
+    "factory",
     "hook",
     "hooks_manager",
     "hooks_type",

nonebot_plugin_value/api/depends/data_classes.py

@@ -0,0 +1,50 @@
+from dataclasses import dataclass, field
+
+from nonebot.adapters import Event
+
+from ...uuid_lib import to_uuid
+from ..api_balance import UserAccountData, get_or_create_account
+from ..api_currency import CurrencyData, get_currency, get_default_currency
+from ..api_transaction import (
+    TransactionData,
+    get_transaction_history,
+    get_transaction_history_by_time_range,
+)
+
+
+@dataclass
+class TransactionHistory:
+    limit: int
+    timerange: tuple[float, float] | None = field(default=None)
+
+    async def __call__(self, event: Event) -> list[TransactionData]:
+        if self.timerange is None:
+            return await get_transaction_history(
+                to_uuid(event.get_user_id()), self.limit
+            )
+        start_time, end_time = self.timerange
+        return await get_transaction_history_by_time_range(
+                to_uuid(event.get_user_id()), start_time, end_time, self.limit
+            )
+
+
+@dataclass
+class Account:
+    currency_id: str | None = field(default=None)
+
+    async def __call__(self, event: Event) -> UserAccountData:
+        if self.currency_id is None:
+            self.currency_id = (await get_default_currency()).id
+        return await get_or_create_account(
+            to_uuid(event.get_user_id()), self.currency_id
+        )
+
+
+@dataclass
+class Currency:
+    c_id: str | None
+
+    async def __call__(self) -> CurrencyData | None:
+        if self.c_id is None:
+            return await get_default_currency()
+        return await get_currency(self.c_id)

nonebot_plugin_value/api/depends/factory.py

@@ -0,0 +1,72 @@
+from collections.abc import Awaitable, Callable
+
+from ...pyd_models.balance_pyd import UserAccountData
+from ...pyd_models.currency_pyd import CurrencyData
+from ...pyd_models.transaction_pyd import TransactionData
+from ..executor import AccountExecutor
+from .data_classes import Account, Currency, TransactionHistory
+
+
+class DependsSwitch:
+    @staticmethod
+    def account_data(
+        *,
+        currency_id: str | None = None,
+    ) -> Callable[..., Awaitable[UserAccountData]]:
+        """获得账户数据
+
+        Args:
+            currency_id (str | None, optional): 货币ID. Defaults to None.
+
+        Returns:
+            Callable[..., Awaitable[UserAccountData]]: 可供NoneBot调用的依赖函数类
+        """
+        return Account(currency_id)
+
+    @staticmethod
+    def currency_data(
+        *,
+        currency_id: str | None = None,
+    ) -> Callable[..., Awaitable[CurrencyData | None]]:
+        """
+        获取货币数据依赖函数
+
+        Args:
+            currency_id (str | None, optional): 货币ID. Defaults to None.
+
+        Returns:
+            Callable[..., Awaitable[CurrencyData | None]]: 可供NoneBot调用的依赖函数类
+        """
+        return Currency(currency_id)
+
+    @staticmethod
+    def transaction_data(
+        *,
+        limit: int = 10,
+        timerange: tuple[float, float] | None = None,
+    ) -> Callable[..., Awaitable[list[TransactionData]]]:
+        """
+        获取交易记录
+
+        Args:
+            limit (int, optional): 交易记录数量限制. Defaults to 10.
+            timerange (tuple[float, float] | None, optional): 时间范围. Defaults to None.
+
+        Returns:
+            Callable[..., Awaitable[list[TransactionData]]]: 可供NoneBot调用的依赖函数类
+        """
+        return TransactionHistory(limit, timerange)
+
+    @staticmethod
+    def account_executor(
+        *,
+        currency_id: str | None = None,
+    ) -> Callable[..., Awaitable[AccountExecutor]]:
+        """
+        Args:
+            currency_id (str | None, optional): 货币ID. Defaults to None.
+
+        Returns:
+            Callable[..., Awaitable[AccountExecutor]]: 账号数据操作对象
+        """
+        return AccountExecutor(currency_id)