dwyeapi 0.4.0__tar.gz → 0.5.1__tar.gz

{dwyeapi-0.4.0 → dwyeapi-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dwyeapi
-Version: 0.4.0
+Version: 0.5.1
 Summary: Lightweight FastAPI infrastructure — exceptions, database, config, security, cache, pagination, logger
 License: MIT
 Requires-Python: >=3.11
@@ -14,6 +14,17 @@ Requires-Dist: redis>=5.0.0
 Requires-Dist: loguru>=0.7.3
 Provides-Extra: tasks
 Requires-Dist: arq>=0.26.0; extra == "tasks"
+Provides-Extra: email-resend
+Requires-Dist: resend[async]>=2.29.0; extra == "email-resend"
+Provides-Extra: email-aliyun
+Requires-Dist: alibabacloud_dm20151123>=1.0.0; extra == "email-aliyun"
+Provides-Extra: sms-aliyun
+Requires-Dist: alibabacloud_dysmsapi20170525>=2.0.0; extra == "sms-aliyun"
+Provides-Extra: email
+Requires-Dist: resend[async]>=2.29.0; extra == "email"
+Requires-Dist: alibabacloud_dm20151123>=1.0.0; extra == "email"
+Provides-Extra: sms
+Requires-Dist: alibabacloud_dysmsapi20170525>=2.0.0; extra == "sms"
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.24.0; extra == "dev"
@@ -21,3 +32,4 @@ Requires-Dist: httpx>=0.27.0; extra == "dev"
 Requires-Dist: aiosqlite>=0.20.0; extra == "dev"
 Requires-Dist: ruff>=0.6.0; extra == "dev"
 Requires-Dist: arq>=0.26.0; extra == "dev"
+Requires-Dist: fakeredis>=2.0.0; extra == "dev"

dwyeapi-0.5.1/README.md

@@ -0,0 +1,52 @@
+# dwyeapi
+
+Lightweight FastAPI infrastructure package for shared use across projects.
+
+## Install
+
+```bash
+pip install dwyeapi
+```
+
+## Modules
+
+- `config` — BaseSettings with required fields (database_url, redis_url, secret_key) + runtime environment API (`is_dev()` / `is_prod()` / `get_environment()`)
+- `exceptions` — AppError hierarchy + FastAPI exception handlers
+- `database` — Async SQLAlchemy engine/session factory + Base + TimestampMixin
+- `dependencies` — `get_db()` FastAPI dependency
+- `security` — JWT create/verify + bcrypt hash/verify (stateless)
+- `cache` — Async Redis connection manager
+- `response` — Unified API response helpers
+- `pagination` — PaginationParams + paginate helper
+- `logger` — Facade logger (loguru-backed) with daily + size rotation and stdlib interception; downstream code depends on `dwyeapi.logger.Logger`, not loguru directly
+- `providers.email` / `providers.sms` — pluggable 验证码 Provider 工厂 (mock / resend / aliyun)
+
+## Environment (dev / prod)
+
+`BaseSettings` 暴露顶层 `environment` 字段,可选值 `"dev" | "prod"`,**默认 `"prod"`**(保守派,误配置时也按 prod 行为)。
+
+```bash
+# .env
+ENVIRONMENT=dev          # 开发环境;留空或 prod 即生产
+```
+
+业务代码通过 `dwyeapi.is_dev()` / `dwyeapi.is_prod()` / `dwyeapi.get_environment()` 读当前环境,典型用法:
+
+```python
+from dwyeapi import is_dev
+from fastapi import FastAPI
+from app.config import Settings
+
+settings = Settings()  # 实例化会把 environment 同步到 dwyeapi 全局
+
+app = FastAPI(
+    title="My API",
+    docs_url="/docs" if is_dev() else None,
+    redoc_url="/redoc" if is_dev() else None,
+    openapi_url="/openapi.json" if is_dev() else None,
+)
+```
+
+### Mock provider 仅 dev 可用
+
+`providers.email` / `providers.sms` 的 `provider="mock"` 只在 `ENVIRONMENT=dev` 下可用。prod 环境下调用 `make_email_provider()` / `make_sms_provider()` 会抛 `ValueError`,保证正式环境一旦误配置 `EMAIL__PROVIDER=mock` 会启动失败(fail fast),而不会静默吞掉真实验证码。

{dwyeapi-0.4.0 → dwyeapi-0.5.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "dwyeapi"
-version = "0.4.0"
+version = "0.5.1"
 description = "Lightweight FastAPI infrastructure — exceptions, database, config, security, cache, pagination, logger"
 requires-python = ">=3.11"
 license = {text = "MIT"}
@@ -19,6 +19,19 @@ dependencies = [
 tasks = [
     "arq>=0.26.0",
 ]
+
+# Email Provider 实现 — 按需安装
+# resend[async] 会拉入 httpx 以启用 Emails.send_async 原生异步 API
+email-resend = ["resend[async]>=2.29.0"]
+email-aliyun = ["alibabacloud_dm20151123>=1.0.0"]
+
+# SMS Provider 实现 — 按需安装
+sms-aliyun = ["alibabacloud_dysmsapi20170525>=2.0.0"]
+
+# 聚合 extras(按模块)
+email = ["resend[async]>=2.29.0", "alibabacloud_dm20151123>=1.0.0"]
+sms = ["alibabacloud_dysmsapi20170525>=2.0.0"]
+
 dev = [
     "pytest>=8.0.0",
     "pytest-asyncio>=0.24.0",
@@ -26,6 +39,7 @@ dev = [
     "aiosqlite>=0.20.0",
     "ruff>=0.6.0",
     "arq>=0.26.0",
+    "fakeredis>=2.0.0",
 ]
 
 [build-system]

{dwyeapi-0.4.0 → dwyeapi-0.5.1}/src/dwyeapi/__init__.py

@@ -1,7 +1,7 @@
 """dwyeapi — Lightweight FastAPI infrastructure.
 
 Modules:
-    config        — BaseSettings with required fields
+    config        — BaseSettings + 运行环境识别 API (is_dev/is_prod/get_environment)
     exceptions    — AppError hierarchy + FastAPI exception handlers
     database      — Async SQLAlchemy engine/session factory + Base + TimestampMixin
     dependencies  — get_db() FastAPI dependency factory
@@ -15,6 +15,7 @@ Modules:
 """
 
 from . import logger
+from .config import BaseSettings, get_environment, is_dev, is_prod
 
-__all__ = ["logger"]
-__version__ = "0.4.0"
+__all__ = ["BaseSettings", "get_environment", "is_dev", "is_prod", "logger"]
+__version__ = "0.5.1"

dwyeapi-0.5.1/src/dwyeapi/config.py

@@ -0,0 +1,85 @@
+"""Base Pydantic Settings class for FastAPI projects.
+
+除基础字段外,还提供运行环境识别 API:
+
+- ``environment`` 字段: ``"dev"`` | ``"prod"``,默认 ``"prod"`` (误配置时保守)
+- ``get_environment()`` / ``is_dev()`` / ``is_prod()``: 业务代码读当前环境
+
+业务项目实例化 ``Settings()`` 时会自动把值写入模块级全局,之后任何地方 import 即可读。
+"""
+
+from typing import Literal
+
+from pydantic import Field, model_validator
+from pydantic_settings import BaseSettings as PydanticBaseSettings
+from pydantic_settings import SettingsConfigDict
+
+Environment = Literal["dev", "prod"]
+
+_current_environment: Environment = "prod"
+
+
+def get_environment() -> Environment:
+    """返回当前运行环境。
+
+    未实例化 Settings 前默认返回 ``"prod"`` (保守),业务 ``Settings()`` 加载
+    后会同步为配置值。
+    """
+    return _current_environment
+
+
+def is_dev() -> bool:
+    """当前是否为开发环境。"""
+    return _current_environment == "dev"
+
+
+def is_prod() -> bool:
+    """当前是否为生产环境。"""
+    return _current_environment == "prod"
+
+
+def set_current_environment(env: Environment) -> None:
+    """内部使用: 由 BaseSettings 校验钩子或测试显式切换时调用。"""
+    global _current_environment
+    _current_environment = env
+
+
+class BaseSettings(PydanticBaseSettings):
+    """Base settings — subclass and add project-specific fields."""
+
+    database_url: str
+    redis_url: str
+    secret_key: str
+    jwt_algorithm: str = "HS256"
+    access_token_expire_minutes: int = 30
+    environment: Environment = "prod"
+    debug: bool = False
+    allowed_origins: list[str] = Field(default_factory=list)
+
+    # Task module settings (task_ prefix)
+    task_max_jobs: int = 5
+    task_job_timeout: int = 3600
+    task_failure_ttl: int = 86400
+
+    # Logger module settings (log_ prefix)
+    log_level: str = "INFO"
+    log_dir: str | None = None
+    log_filename: str = "app"
+    log_max_bytes: int = 100 * 1024 * 1024
+    log_retention: str = "30 days"
+    log_console: bool = True
+    log_serialize: bool = False
+    log_intercept_stdlib: bool = True
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        env_nested_delimiter="__",
+        extra="ignore",
+    )
+
+    @model_validator(mode="after")
+    def _sync_environment_to_module(self) -> "BaseSettings":
+        """把 ``environment`` 写入模块全局,让 ``is_dev()`` / ``is_prod()`` 跨模块可读。"""
+        set_current_environment(self.environment)
+        return self

{dwyeapi-0.4.0 → dwyeapi-0.5.1}/src/dwyeapi/dt.py

@@ -1,7 +1,7 @@
 """全局时间工具 — 所有日期操作的唯一入口。
 
-业务时间统一 Asia/Shanghai，JWT 等协议场景提供 UTC 方法。
-禁止在业务代码中直接使用 datetime.now()，统一通过本模块访问。
+业务时间统一 Asia/Shanghai, JWT 等协议场景提供 UTC 方法。
+禁止在业务代码中直接使用 datetime.now(), 统一通过本模块访问。
 
 Usage::
 
@@ -10,22 +10,22 @@ Usage::
     dt.now()          # naive datetime, 中国时间, 用于数据库
     dt.now_str()      # "2026-04-06 14:30:00"
     dt.today()        # date(2026, 4, 6)
-    dt.timestamp()    # Unix 时间戳（秒）
+    dt.timestamp()    # Unix 时间戳(秒)
     dt.utc_now()      # aware datetime, UTC, 用于 JWT
 """
 
-from datetime import date, datetime, timedelta
+from datetime import date, datetime
 from zoneinfo import ZoneInfo
 
 TZ = ZoneInfo("Asia/Shanghai")
 UTC = ZoneInfo("UTC")
 
 
-# ── 业务时间（Asia/Shanghai） ──────────────────────────────────────────
+# ── 业务时间(Asia/Shanghai) ──────────────────────────────────────────
 
 
 def now() -> datetime:
-    """当前中国时间（naive，用于数据库存储）。"""
+    """当前中国时间(naive, 用于数据库存储)。"""
     return datetime.now(TZ).replace(tzinfo=None)
 
 
@@ -40,13 +40,13 @@ def today() -> date:
 
 
 def timestamp() -> float:
-    """当前 Unix 时间戳（秒）。"""
+    """当前 Unix 时间戳(秒)。"""
     return datetime.now(TZ).timestamp()
 
 
-# ── UTC（JWT 等协议场景） ──────────────────────────────────────────────
+# ── UTC(JWT 等协议场景) ──────────────────────────────────────────────
 
 
 def utc_now() -> datetime:
-    """当前 UTC 时间（aware，用于 JWT exp 等协议字段）。"""
+    """当前 UTC 时间(aware, 用于 JWT exp 等协议字段)。"""
     return datetime.now(UTC)

{dwyeapi-0.4.0 → dwyeapi-0.5.1}/src/dwyeapi/logger.py

@@ -27,7 +27,7 @@ from typing import TYPE_CHECKING, Any
 from loguru import logger as _logger
 
 if TYPE_CHECKING:
-    from loguru import Logger, Record
+    from loguru import Record
 
 
 _DEFAULT_CONSOLE_FORMAT = (
@@ -45,6 +45,69 @@ _handler_ids: list[int] = []
 _intercept_state: dict[str, list[logging.Handler]] = {}
 
 
+class Logger:
+    """dwyeapi 日志门面,遵循 stdlib ``logging.Logger`` 语义。
+
+    - 消息用 ``%s`` / ``%d`` 等 stdlib 占位符,位置参数延迟格式化
+    - 支持 ``exc_info=True`` 记录当前异常堆栈
+    - 底层可为 loguru / stdlib logging / structlog,调用方无感知
+    """
+
+    __slots__ = ("_impl",)
+
+    def __init__(self, impl: Any) -> None:
+        """保存底层日志对象。
+
+        Args:
+            impl: 真正执行日志调用的底层对象。当前由 :func:`get_logger`
+                注入 loguru logger,需支持 ``opt(exception=...)`` 与
+                ``debug`` / ``info`` / ``warning`` / ``error`` /
+                ``critical`` 方法。
+        """
+        self._impl = impl
+
+    def _emit(self, level: str, msg: str, args: tuple[Any, ...], exc_info: bool) -> None:
+        """格式化消息并转发到底层实现。
+
+        Args:
+            level: 日志级别方法名(``debug``/``info``/``warning``/
+                ``error``/``critical``)。
+            msg: 日志消息模板,支持 stdlib ``%`` 占位符。
+            args: 用于 ``%``-格式化的位置参数;为空时保留 ``msg`` 原样。
+            exc_info: 是否附带当前异常堆栈。
+        """
+        try:
+            formatted = msg % args if args else msg
+        except (TypeError, ValueError):
+            formatted = f"{msg} args={args!r}"
+        target = self._impl.opt(exception=True) if exc_info else self._impl
+        getattr(target, level)(formatted)
+
+    def debug(self, msg: str, *args: Any, exc_info: bool = False, **_: Any) -> None:
+        """记录 DEBUG 级别日志。"""
+        self._emit("debug", msg, args, exc_info)
+
+    def info(self, msg: str, *args: Any, exc_info: bool = False, **_: Any) -> None:
+        """记录 INFO 级别日志。"""
+        self._emit("info", msg, args, exc_info)
+
+    def warning(self, msg: str, *args: Any, exc_info: bool = False, **_: Any) -> None:
+        """记录 WARNING 级别日志。"""
+        self._emit("warning", msg, args, exc_info)
+
+    def error(self, msg: str, *args: Any, exc_info: bool = False, **_: Any) -> None:
+        """记录 ERROR 级别日志。"""
+        self._emit("error", msg, args, exc_info)
+
+    def exception(self, msg: str, *args: Any, **_: Any) -> None:
+        """记录 ERROR 级别日志并自动附带当前异常堆栈。"""
+        self._emit("error", msg, args, exc_info=True)
+
+    def critical(self, msg: str, *args: Any, exc_info: bool = False, **_: Any) -> None:
+        """记录 CRITICAL 级别日志。"""
+        self._emit("critical", msg, args, exc_info)
+
+
 class _InterceptHandler(logging.Handler):
     """Route standard ``logging`` records into the loguru sink chain."""
 
@@ -173,18 +236,18 @@ def _install_stdlib_intercept(level: str, targets: list[str] | None) -> None:
 
 
 def get_logger(name: str | None = None) -> Logger:
-    """Return the shared logger, optionally bound to a module name.
+    """返回 dwyeapi ``Logger`` 门面,可选绑定模块名。
 
     Args:
-        name: Logical module name recorded in the ``module`` extra field.
+        name: 记录到 ``module`` extra 字段的逻辑模块名。
 
     Returns:
-        A loguru ``Logger`` proxy. If ``configure`` has not been called yet,
-        returns the raw default logger (stderr at DEBUG).
+        ``Logger`` 门面实例。底层当前使用 loguru,但此细节对调用方
+        不可见,以便后续替换为其他日志库(stdlib logging /
+        structlog 等)时无需改动调用点。
     """
-    if name:
-        return _logger.bind(module=name)
-    return _logger
+    impl = _logger.bind(module=name) if name else _logger
+    return Logger(impl)
 
 
 def close() -> None:

dwyeapi-0.5.1/src/dwyeapi/providers/__init__.py

@@ -0,0 +1,5 @@
+"""可插拔 Provider 扩展。
+
+业务相关但复用性强的外部服务抽象(邮件、短信等),通过 Protocol + 配置驱动切换。
+第三方 SDK 依赖一律走 optional-dependencies,业务项目 `pip install dwyeapi[email]` 按需启用。
+"""

dwyeapi-0.5.1/src/dwyeapi/providers/email/__init__.py

@@ -0,0 +1,29 @@
+"""Email Provider 模块 -- 提供可插拔的邮件验证码发送能力。
+
+提供 Protocol 抽象 + 配置类 + 工厂函数 + 多种实现(mock/resend/aliyun)。
+业务项目通过 `pip install dwyeapi[email-resend]` 等 extras 按需安装 provider 依赖。
+
+典型用法:
+    from dwyeapi.providers.email import EmailSettings, make_email_provider
+
+    class Settings(DwyBaseSettings):
+        email: EmailSettings = EmailSettings()
+
+    settings = Settings()
+    provider = make_email_provider(settings.email)
+    await provider.send_code("user@example.com")
+"""
+
+from dwyeapi.providers.email.base import EmailProviderBase
+from dwyeapi.providers.email.config import AliyunEmailConfig, EmailSettings, ResendConfig
+from dwyeapi.providers.email.factory import make_email_provider
+from dwyeapi.providers.email.protocol import EmailProvider
+
+__all__ = [
+    "AliyunEmailConfig",
+    "EmailProvider",
+    "EmailProviderBase",
+    "EmailSettings",
+    "ResendConfig",
+    "make_email_provider",
+]

dwyeapi-0.5.1/src/dwyeapi/providers/email/aliyun.py

@@ -0,0 +1,46 @@
+"""阿里云邮件推送 Email Provider -- 占位实现。
+
+需要 `pip install dwyeapi[email-aliyun]` 才能使用。实际调用待首次接入项目时补全。
+"""
+
+import redis.asyncio as aioredis
+
+from dwyeapi.providers.email.base import DEFAULT_CODE_LENGTH, DEFAULT_CODE_TTL, EmailProviderBase
+
+
+class AliyunEmailProvider(EmailProviderBase):
+    """基于阿里云邮件推送的 Email Provider(占位)。
+
+    首次接入项目时基于 `alibabacloud_dm20151123` SDK 实现 `_send()`。
+    """
+
+    def __init__(
+        self,
+        access_key_id: str,
+        access_key_secret: str,
+        account_name: str,
+        from_alias: str = "",
+        subject: str = "验证码",
+        code_ttl: int = DEFAULT_CODE_TTL,
+        code_length: int = DEFAULT_CODE_LENGTH,
+        redis: aioredis.Redis | None = None,
+    ) -> None:
+        """初始化。
+
+        Raises:
+            ImportError: 未安装 alibabacloud_dm20151123 时抛出。
+        """
+        super().__init__(code_ttl=code_ttl, code_length=code_length, redis=redis)
+        try:
+            import alibabacloud_dm20151123  # noqa: F401
+        except ImportError as e:
+            raise ImportError("使用 AliyunEmailProvider 需要安装: pip install dwyeapi[email-aliyun]") from e
+        self._access_key_id = access_key_id
+        self._access_key_secret = access_key_secret
+        self._account_name = account_name
+        self._from_alias = from_alias
+        self._subject = subject
+
+    async def _send(self, target: str, code: str) -> bool:
+        """调用阿里云 DirectMail API 发送邮件。"""
+        raise NotImplementedError("AliyunEmailProvider 暂未实现,首次接入项目时补全 _send")

dwyeapi-0.5.1/src/dwyeapi/providers/email/base.py

@@ -0,0 +1,71 @@
+"""Email Provider 基类 -- 封装 Redis 验证码存取逻辑。"""
+
+import secrets
+from abc import ABC, abstractmethod
+
+import redis.asyncio as aioredis
+
+from dwyeapi.cache import get_redis
+
+CODE_KEY_PREFIX = "dwyeapi:email:code:"
+DEFAULT_CODE_TTL = 300
+DEFAULT_CODE_LENGTH = 6
+
+
+class EmailProviderBase(ABC):
+    """Email Provider 抽象基类。
+
+    共享验证码生成 + Redis 存取 + 一次性校验逻辑;子类只实现 `_send()` 发送动作。
+    """
+
+    def __init__(
+        self,
+        code_ttl: int = DEFAULT_CODE_TTL,
+        code_length: int = DEFAULT_CODE_LENGTH,
+        redis: aioredis.Redis | None = None,
+    ) -> None:
+        """初始化。
+
+        Args:
+            code_ttl: 验证码有效期(秒),默认 300。
+            code_length: 验证码位数,默认 6。
+            redis: 可选显式注入的 Redis 连接;为 None 时 fallback 到 dwyeapi.cache.get_redis()。
+        """
+        self._ttl = code_ttl
+        self._length = code_length
+        self._redis = redis
+
+    async def _get_redis(self) -> aioredis.Redis:
+        """获取 Redis 连接,优先使用注入的,否则取全局单例。"""
+        if self._redis is not None:
+            return self._redis
+        return await get_redis()
+
+    def _generate_code(self) -> str:
+        """生成指定位数的数字验证码。"""
+        return "".join(secrets.choice("0123456789") for _ in range(self._length))
+
+    async def send_code(self, target: str) -> bool:
+        """生成验证码存 Redis 并调用 `_send()` 发送。"""
+        code = self._generate_code()
+        redis = await self._get_redis()
+        await redis.set(f"{CODE_KEY_PREFIX}{target}", code, ex=self._ttl)
+        return await self._send(target, code)
+
+    async def verify_code(self, target: str, code: str) -> bool:
+        """从 Redis 读取存储的验证码比对,成功则删除 key(一次性)。"""
+        redis = await self._get_redis()
+        key = f"{CODE_KEY_PREFIX}{target}"
+        stored = await redis.get(key)
+        if stored is None:
+            return False
+        stored_str = stored if isinstance(stored, str) else stored.decode()
+        if stored_str != code:
+            return False
+        await redis.delete(key)
+        return True
+
+    @abstractmethod
+    async def _send(self, target: str, code: str) -> bool:
+        """子类实现发送动作。"""
+        ...

dwyeapi-0.5.1/src/dwyeapi/providers/email/config.py

@@ -0,0 +1,42 @@
+"""Email Provider 配置模型。"""
+
+from typing import Literal
+
+from pydantic import BaseModel
+
+
+class ResendConfig(BaseModel):
+    """Resend Email Provider 配置。"""
+
+    api_key: str = ""
+    from_email: str = "noreply@example.com"
+    subject: str = "验证码"
+
+
+class AliyunEmailConfig(BaseModel):
+    """阿里云邮件推送 Provider 配置。"""
+
+    access_key_id: str = ""
+    access_key_secret: str = ""
+    account_name: str = ""
+    from_alias: str = ""
+    subject: str = "验证码"
+
+
+class EmailSettings(BaseModel):
+    """Email 模块配置 -- 业务项目嵌入 Settings 的入口。
+
+    用法:
+        class Settings(DwyBaseSettings):
+            email: EmailSettings = EmailSettings()
+
+    `.env` 自动识别(双下划线嵌套):
+        EMAIL__PROVIDER=resend
+        EMAIL__RESEND__API_KEY=re_xxx
+    """
+
+    provider: Literal["mock", "resend", "aliyun"] = "mock"
+    code_ttl: int = 300
+    code_length: int = 6
+    resend: ResendConfig = ResendConfig()
+    aliyun: AliyunEmailConfig = AliyunEmailConfig()

dwyeapi-0.5.1/src/dwyeapi/providers/email/factory.py

@@ -0,0 +1,61 @@
+"""Email Provider 工厂 -- 根据配置选择实现。"""
+
+from dwyeapi.config import is_prod
+from dwyeapi.providers.email.config import EmailSettings
+from dwyeapi.providers.email.protocol import EmailProvider
+
+
+def make_email_provider(settings: EmailSettings) -> EmailProvider:
+    """根据 `settings.provider` 构造对应的 Email Provider 实例。
+
+    Args:
+        settings: Email 模块配置(项目 Settings 的嵌套字段)。
+
+    Returns:
+        实现了 `EmailProvider` Protocol 的实例。
+
+    Raises:
+        ValueError: 未知 provider、必填配置缺失,或 prod 环境下选择 mock provider。
+        ImportError: provider 对应的 extra 未安装。
+    """
+    common = {"code_ttl": settings.code_ttl, "code_length": settings.code_length}
+
+    match settings.provider:
+        case "mock":
+            if is_prod():
+                raise ValueError(
+                    "EMAIL__PROVIDER=mock 在 prod 环境下被禁止;"
+                    "请设置 ENVIRONMENT=dev 或改用真实 provider(resend/aliyun)"
+                )
+            from dwyeapi.providers.email.mock import MockEmailProvider
+
+            return MockEmailProvider(**common)
+
+        case "resend":
+            from dwyeapi.providers.email.resend import ResendEmailProvider
+
+            if not settings.resend.api_key:
+                raise ValueError("EMAIL__RESEND__API_KEY 未配置")
+            return ResendEmailProvider(
+                api_key=settings.resend.api_key,
+                from_email=settings.resend.from_email,
+                subject=settings.resend.subject,
+                **common,
+            )
+
+        case "aliyun":
+            from dwyeapi.providers.email.aliyun import AliyunEmailProvider
+
+            if not settings.aliyun.access_key_id or not settings.aliyun.access_key_secret:
+                raise ValueError("EMAIL__ALIYUN__ACCESS_KEY_ID/SECRET 未配置")
+            return AliyunEmailProvider(
+                access_key_id=settings.aliyun.access_key_id,
+                access_key_secret=settings.aliyun.access_key_secret,
+                account_name=settings.aliyun.account_name,
+                from_alias=settings.aliyun.from_alias,
+                subject=settings.aliyun.subject,
+                **common,
+            )
+
+        case _:
+            raise ValueError(f"未知 email provider: {settings.provider}")

dwyeapi-0.5.1/src/dwyeapi/providers/email/mock.py

@@ -0,0 +1,15 @@
+"""Mock Email Provider -- 开发/测试环境使用,日志打印验证码不真实发送。"""
+
+from dwyeapi.logger import get_logger
+from dwyeapi.providers.email.base import EmailProviderBase
+
+logger = get_logger(__name__)
+
+
+class MockEmailProvider(EmailProviderBase):
+    """Mock 邮箱验证码 Provider。"""
+
+    async def _send(self, target: str, code: str) -> bool:
+        """打印验证码到日志,始终返回 True。"""
+        logger.info("Mock Email sent: target=%s code=%s", target, code)
+        return True