dwyeapi 0.7.0__tar.gz → 0.8.0__tar.gz

{dwyeapi-0.7.0 → dwyeapi-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dwyeapi
-Version: 0.7.0
+Version: 0.8.0
 Summary: Lightweight FastAPI infrastructure — exceptions, database, config, security, cache, pagination, logger
 License: MIT
 Requires-Python: >=3.11

{dwyeapi-0.7.0 → dwyeapi-0.8.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "dwyeapi"
-version = "0.7.0"
+version = "0.8.0"
 description = "Lightweight FastAPI infrastructure — exceptions, database, config, security, cache, pagination, logger"
 requires-python = ">=3.11"
 license = {text = "MIT"}

dwyeapi-0.8.0/src/dwyeapi/config.py

@@ -0,0 +1,141 @@
+"""FastAPI 项目通用 Pydantic Settings 基类。
+
+除了 database_url / redis_url / secret_key 等基础字段外,还提供运行环境识别 API:
+
+- ``environment`` 字段: ``"dev"`` | ``"prod"``,默认 ``"prod"``(误配置时偏保守)
+- ``get_environment()`` / ``is_dev()`` / ``is_prod()``:业务代码读取当前环境
+
+业务项目实例化 ``Settings()`` 时会自动把 environment 值写入模块级全局变量,
+之后任何地方 import 即可读,避免把 Settings 实例到处传递。
+"""
+
+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):
+    """FastAPI 项目共用的配置基类。
+
+    业务项目通过继承并追加项目专属字段使用,内置的 database_url / redis_url /
+    secret_key 等字段覆盖最常用的基础设施需求,不需要每个项目重复声明。
+    配置来源默认为 ``.env`` 文件,嵌套字段使用双下划线 ``__`` 分隔。
+    """
+
+    database_url: str = Field(
+        description="数据库连接串(异步驱动),例 postgresql+asyncpg://user:pass@host:5432/db",
+    )
+    redis_url: str = Field(
+        description="Redis 连接串,例 redis://localhost:6379/0",
+    )
+    secret_key: str = Field(
+        description="应用密钥,用于 JWT 签名与敏感数据加密,至少 32 位随机字符串",
+    )
+    jwt_algorithm: str = Field(
+        default="HS256",
+        description="JWT 签名算法,默认 HS256",
+    )
+    access_token_expire_minutes: int = Field(
+        default=30,
+        description="JWT access token 有效期(分钟),默认 30 分钟",
+    )
+    environment: Environment = Field(
+        default="prod",
+        description='运行环境,"dev" 开启调试特性 / 允许 mock providers,"prod" 关闭调试并禁用 mock',
+    )
+    allowed_origins: list[str] = Field(
+        default_factory=list,
+        description="CORS 允许的来源域名列表,生产环境禁止使用 ['*']",
+    )
+
+    # ── 异步任务配置(task_ 前缀)──
+    task_max_jobs: int = Field(
+        default=5,
+        description="ARQ worker 并发执行的最大任务数",
+    )
+    task_job_timeout: int = Field(
+        default=3600,
+        description="单个任务执行超时(秒),超时后被中止,默认 1 小时",
+    )
+    task_failure_ttl: int = Field(
+        default=86400,
+        description="失败任务结果在 Redis 中的保留时长(秒),默认 1 天",
+    )
+
+    # ── 日志配置(log_ 前缀)──
+    log_level: str = Field(
+        default="INFO",
+        description="最低日志级别:DEBUG / INFO / WARNING / ERROR / CRITICAL",
+    )
+    log_dir: str | None = Field(
+        default=".",
+        description='日志文件目录,默认 "." 即进程当前目录;显式设为 None 可关闭文件输出(仅控制台)',
+    )
+    log_filename: str = Field(
+        default="app",
+        description="日志文件基础名,最终文件形如 {filename}_YYYY-MM-DD.log",
+    )
+    log_max_bytes: int = Field(
+        default=100 * 1024 * 1024,
+        description="单个日志文件大小上限(字节),超出后滚动,默认 100 MB",
+    )
+    log_retention: str = Field(
+        default="30 days",
+        description='日志保留策略,loguru 语法,例 "30 days" / "1 week" / 整数个数',
+    )
+    log_console: bool = Field(
+        default=True,
+        description="是否输出带颜色的日志到 stderr 控制台",
+    )
+    log_serialize: bool = Field(
+        default=False,
+        description="文件 sink 是否按 JSON Lines 序列化,便于日志聚合系统解析",
+    )
+    log_intercept_stdlib: bool = Field(
+        default=True,
+        description="是否拦截 stdlib logging,让 uvicorn / SQLAlchemy / httpx 等共享同一套 sink",
+    )
+
+    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.7.0 → dwyeapi-0.8.0}/src/dwyeapi/providers/email/aliyun.py

@@ -11,7 +11,8 @@ from dwyeapi.providers.email.base import DEFAULT_CODE_LENGTH, DEFAULT_CODE_TTL,
 class AliyunEmailProvider(EmailProviderBase):
     """基于阿里云邮件推送的 Email Provider(占位)。
 
-    首次接入项目时基于 `alibabacloud_dm20151123` SDK 实现 `_send()`。
+    首次接入项目时基于 `alibabacloud_dm20151123` SDK 实现 `_send()`,
+    调用时使用 `self._render_code_html(code)` / `self._render_code_text(code)` 复用品牌模板。
     """
 
     def __init__(
@@ -23,6 +24,11 @@ class AliyunEmailProvider(EmailProviderBase):
         subject: str = "验证码",
         code_ttl: int = DEFAULT_CODE_TTL,
         code_length: int = DEFAULT_CODE_LENGTH,
+        brand_name: str = "",
+        brand_tagline: str = "",
+        brand_url: str = "",
+        brand_slogan: str = "",
+        support_email: str = "",
         redis: aioredis.Redis | None = None,
     ) -> None:
         """初始化。
@@ -30,7 +36,16 @@ class AliyunEmailProvider(EmailProviderBase):
         Raises:
             ImportError: 未安装 alibabacloud_dm20151123 时抛出。
         """
-        super().__init__(code_ttl=code_ttl, code_length=code_length, redis=redis)
+        super().__init__(
+            code_ttl=code_ttl,
+            code_length=code_length,
+            brand_name=brand_name,
+            brand_tagline=brand_tagline,
+            brand_url=brand_url,
+            brand_slogan=brand_slogan,
+            support_email=support_email,
+            redis=redis,
+        )
         try:
             import alibabacloud_dm20151123  # noqa: F401
         except ImportError as e:
@@ -38,7 +53,7 @@ class AliyunEmailProvider(EmailProviderBase):
         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._from_alias = from_alias or brand_name
         self._subject = subject
 
     async def _send(self, target: str, code: str) -> bool:

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

@@ -0,0 +1,193 @@
+"""Email Provider 基类 -- 封装 Redis 验证码存取 + 品牌化 HTML/text 渲染。"""
+
+import secrets
+from abc import ABC, abstractmethod
+from html import escape
+
+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()` 发送动作。
+    同时提供 `_render_code_html()` / `_render_code_text()` 让所有子类共用同一套品牌化模板。
+    """
+
+    def __init__(
+        self,
+        code_ttl: int = DEFAULT_CODE_TTL,
+        code_length: int = DEFAULT_CODE_LENGTH,
+        brand_name: str = "",
+        brand_tagline: str = "",
+        brand_url: str = "",
+        brand_slogan: str = "",
+        support_email: str = "",
+        redis: aioredis.Redis | None = None,
+    ) -> None:
+        """初始化。
+
+        Args:
+            code_ttl: 验证码有效期(秒),默认 300。
+            code_length: 验证码位数,默认 6。
+            brand_name: 品牌名,展示在邮件页眉与页脚版权;空串走通用模板。
+            brand_tagline: 品牌副标语(英文/口号),展示在页眉右上;空串则不显示。
+            brand_url: 品牌官网,展示在页脚链接;空串则不显示。
+            brand_slogan: 页脚版权下方一行说明文案;空串则不显示。
+            support_email: 客服邮箱,展示在邮件正文底部;空串则不显示。
+            redis: 可选显式注入的 Redis 连接;为 None 时 fallback 到 dwyeapi.cache.get_redis()。
+        """
+        self._ttl = code_ttl
+        self._length = code_length
+        self._brand_name = brand_name
+        self._brand_tagline = brand_tagline
+        self._brand_url = brand_url
+        self._brand_slogan = brand_slogan
+        self._support_email = support_email
+        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
+
+    def _render_code_html(self, code: str) -> str:
+        """渲染品牌化验证码 HTML 邮件 -- 主流邮件客户端兼容的 inline CSS 模板。
+
+        使用 table 布局 + inline style,适配 Gmail / Outlook / 163 / QQ / Apple Mail。
+        所有动态文案经 `html.escape` 转义,避免 brand_name 含特殊字符时破坏结构。
+        """
+        minutes = max(self._ttl // 60, 1)
+        brand = escape(self._brand_name) or "验证码"
+        tagline = escape(self._brand_tagline)
+        url = escape(self._brand_url)
+        slogan = escape(self._brand_slogan)
+        support = escape(self._support_email)
+        code_safe = escape(code)
+
+        header_right = (
+            f'<td align="right" style="color:#94a3b8;font-size:13px;letter-spacing:1px;">{tagline}</td>'
+            if tagline
+            else ""
+        )
+        support_block = (
+            f'<p style="margin:0 0 8px 0;color:#475569;font-size:13px;line-height:1.7;">'
+            f"如有疑问,请联系客服:"
+            f'<a href="mailto:{support}" style="color:#1e3a8a;text-decoration:none;">{support}</a>'
+            "</p>"
+            if support
+            else ""
+        )
+        slogan_block = f"<br/>{slogan}" if slogan else ""
+        footer_link = (
+            f'<a href="{url}" style="color:#1e3a8a;text-decoration:none;font-weight:500;">'
+            f"{url.replace('https://', '').replace('http://', '')} →"
+            "</a>"
+            if url
+            else ""
+        )
+
+        return f"""<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>{brand} 验证码</title>
+</head>
+<body style="margin:0;padding:0;background-color:#f4f6fa;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI','PingFang SC','Hiragino Sans GB','Microsoft YaHei',sans-serif;-webkit-font-smoothing:antialiased;">
+<table role="presentation" cellpadding="0" cellspacing="0" border="0" width="100%" style="background-color:#f4f6fa;padding:40px 16px;">
+  <tr><td align="center">
+    <table role="presentation" cellpadding="0" cellspacing="0" border="0" width="560" style="max-width:560px;width:100%;background:#ffffff;border-radius:16px;overflow:hidden;box-shadow:0 4px 24px rgba(15,23,42,0.06);">
+      <tr>
+        <td style="background:linear-gradient(135deg,#0f172a 0%,#1e3a8a 100%);padding:32px 40px;">
+          <table role="presentation" cellpadding="0" cellspacing="0" border="0" width="100%">
+            <tr>
+              <td style="color:#ffffff;font-size:20px;font-weight:600;letter-spacing:1px;">{brand}</td>
+              {header_right}
+            </tr>
+          </table>
+        </td>
+      </tr>
+      <tr>
+        <td style="padding:40px 40px 8px 40px;">
+          <h1 style="margin:0 0 12px 0;color:#0f172a;font-size:22px;font-weight:600;line-height:1.4;">您正在进行身份验证</h1>
+          <p style="margin:0 0 28px 0;color:#475569;font-size:14px;line-height:1.7;">
+            您好,请使用以下验证码完成本次操作。该验证码 <strong style="color:#0f172a;">{minutes} 分钟内有效</strong>,请勿向任何人泄露。
+          </p>
+          <div style="margin:0 0 28px 0;background:#f8fafc;border:1px solid #e2e8f0;border-radius:12px;padding:24px;text-align:center;">
+            <div style="color:#64748b;font-size:12px;letter-spacing:2px;margin-bottom:12px;">VERIFICATION CODE</div>
+            <div style="color:#0f172a;font-size:36px;font-weight:700;letter-spacing:10px;font-family:'SF Mono','Menlo','Consolas',monospace;">{code_safe}</div>
+          </div>
+          <p style="margin:0 0 8px 0;color:#475569;font-size:13px;line-height:1.7;">若非本人操作,请忽略此邮件,您的账户依然安全。</p>
+          {support_block}
+          <p style="margin:0;color:#94a3b8;font-size:12px;line-height:1.7;">本邮件由系统自动发送,请勿直接回复。</p>
+        </td>
+      </tr>
+      <tr>
+        <td style="padding:24px 40px 32px 40px;border-top:1px solid #f1f5f9;">
+          <table role="presentation" cellpadding="0" cellspacing="0" border="0" width="100%">
+            <tr>
+              <td style="color:#94a3b8;font-size:12px;line-height:1.6;">© {brand}{slogan_block}</td>
+              <td align="right" style="color:#94a3b8;font-size:12px;">{footer_link}</td>
+            </tr>
+          </table>
+        </td>
+      </tr>
+    </table>
+  </td></tr>
+</table>
+</body>
+</html>"""
+
+    def _render_code_text(self, code: str) -> str:
+        """渲染纯文本备份 -- 给不支持 HTML 的客户端,同时降低被反垃圾误判的概率。"""
+        minutes = max(self._ttl // 60, 1)
+        brand = self._brand_name or "验证码"
+        lines = [
+            f"【{brand}】您正在进行身份验证。",
+            "",
+            f"您的验证码是:{code},{minutes} 分钟内有效,请勿向任何人泄露。",
+            "",
+            "若非本人操作,请忽略此邮件。",
+        ]
+        if self._support_email:
+            lines.append(f"如有疑问,请联系客服:{self._support_email}")
+        if self._brand_url:
+            lines.append(f"— {self._brand_name or ''} {self._brand_url}".strip())
+        return "\n".join(lines)
+
+    @abstractmethod
+    async def _send(self, target: str, code: str) -> bool:
+        """子类实现发送动作。"""
+        ...

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

@@ -0,0 +1,112 @@
+"""Email Provider 配置模型。"""
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class ResendConfig(BaseModel):
+    """Resend Email Provider 配置。
+
+    EMAIL__PROVIDER=resend 时生效;空串默认仅为 pydantic 嵌套实例化需要,
+    真正启用时 api_key / from_email 必须通过 .env 显式提供。
+    """
+
+    api_key: str = Field(
+        default="",
+        description="[必填: resend] Resend API Key,形如 re_xxx",
+    )
+    from_email: str = Field(
+        default="",
+        description="[必填: resend] 发件人邮箱,必须是已在 Resend 验证过的域名邮箱",
+    )
+    subject: str = Field(
+        default="验证码",
+        description="验证码邮件主题",
+    )
+
+
+class AliyunEmailConfig(BaseModel):
+    """阿里云邮件推送 Provider 配置。
+
+    EMAIL__PROVIDER=aliyun 时生效;空串默认仅为 pydantic 嵌套实例化需要,
+    真正启用时凭证 + account_name 必须通过 .env 显式提供。
+    """
+
+    access_key_id: str = Field(
+        default="",
+        description="[必填: aliyun] 阿里云 AccessKey ID",
+    )
+    access_key_secret: str = Field(
+        default="",
+        description="[必填: aliyun] 阿里云 AccessKey Secret",
+    )
+    account_name: str = Field(
+        default="",
+        description="[必填: aliyun] 发信地址,需在阿里云邮件推送控制台预先配置",
+    )
+    from_alias: str = Field(
+        default="",
+        description="发件人显示名,留空则展示 account_name",
+    )
+    subject: str = Field(
+        default="验证码",
+        description="验证码邮件主题",
+    )
+
+
+class EmailSettings(BaseModel):
+    """Email 模块配置 -- 业务项目嵌入 Settings 的入口。
+
+    用法:
+        class Settings(DwyBaseSettings):
+            email: EmailSettings = EmailSettings()
+
+    `.env` 自动识别(双下划线嵌套):
+        EMAIL__PROVIDER=resend
+        EMAIL__BRAND_NAME=宽舟科技
+        EMAIL__BRAND_URL=https://quantzone.tech
+        EMAIL__SUPPORT_EMAIL=support@quantzone.tech
+        EMAIL__RESEND__API_KEY=re_xxx
+    """
+
+    provider: Literal["mock", "resend", "aliyun"] = Field(
+        default="mock",
+        description='Email Provider 选择:"mock"(dev 限定,打印到日志)/ "resend" / "aliyun"',
+    )
+    code_ttl: int = Field(
+        default=300,
+        description="验证码有效期(秒),默认 5 分钟",
+    )
+    code_length: int = Field(
+        default=6,
+        description="验证码位数,默认 6 位数字",
+    )
+    brand_name: str = Field(
+        default="",
+        description="品牌名,展示在邮件页眉与页脚版权,留空则使用通用模板",
+    )
+    brand_tagline: str = Field(
+        default="",
+        description="品牌副标语(英文/口号),展示在页眉右上,留空则不显示",
+    )
+    brand_url: str = Field(
+        default="",
+        description="品牌官网,展示在页脚链接,留空则不显示",
+    )
+    brand_slogan: str = Field(
+        default="",
+        description="页脚版权下方一行说明文案,留空则不显示",
+    )
+    support_email: str = Field(
+        default="",
+        description="客服邮箱,展示在邮件正文底部,留空则不显示",
+    )
+    resend: ResendConfig = Field(
+        default_factory=ResendConfig,
+        description="Resend 配置,provider=resend 时必填",
+    )
+    aliyun: AliyunEmailConfig = Field(
+        default_factory=AliyunEmailConfig,
+        description="阿里云邮件推送配置,provider=aliyun 时必填",
+    )

{dwyeapi-0.7.0 → dwyeapi-0.8.0}/src/dwyeapi/providers/email/factory.py

@@ -18,7 +18,15 @@ def make_email_provider(settings: EmailSettings) -> EmailProvider:
         ValueError: 未知 provider、必填配置缺失,或 prod 环境下选择 mock provider。
         ImportError: provider 对应的 extra 未安装。
     """
-    common = {"code_ttl": settings.code_ttl, "code_length": settings.code_length}
+    common = {
+        "code_ttl": settings.code_ttl,
+        "code_length": settings.code_length,
+        "brand_name": settings.brand_name,
+        "brand_tagline": settings.brand_tagline,
+        "brand_url": settings.brand_url,
+        "brand_slogan": settings.brand_slogan,
+        "support_email": settings.support_email,
+    }
 
     match settings.provider:
         case "mock":

{dwyeapi-0.7.0 → dwyeapi-0.8.0}/src/dwyeapi/providers/email/resend.py

@@ -25,6 +25,11 @@ class ResendEmailProvider(EmailProviderBase):
         subject: str = "验证码",
         code_ttl: int = DEFAULT_CODE_TTL,
         code_length: int = DEFAULT_CODE_LENGTH,
+        brand_name: str = "",
+        brand_tagline: str = "",
+        brand_url: str = "",
+        brand_slogan: str = "",
+        support_email: str = "",
         redis: aioredis.Redis | None = None,
     ) -> None:
         """初始化 Resend Provider。
@@ -35,31 +40,43 @@ class ResendEmailProvider(EmailProviderBase):
             subject: 邮件主题。
             code_ttl: 验证码有效期(秒)。
             code_length: 验证码位数。
+            brand_name: 品牌名,影响发件人显示名("brand_name <from_email>")与 HTML/text 模板。
+            brand_tagline: 品牌副标语。
+            brand_url: 品牌官网。
+            brand_slogan: 页脚说明。
+            support_email: 客服邮箱。
             redis: 可选显式注入的 Redis 连接。
 
         Raises:
             ImportError: 未安装 resend 包时抛出,提示用户安装对应 extra。
         """
-        super().__init__(code_ttl=code_ttl, code_length=code_length, redis=redis)
+        super().__init__(
+            code_ttl=code_ttl,
+            code_length=code_length,
+            brand_name=brand_name,
+            brand_tagline=brand_tagline,
+            brand_url=brand_url,
+            brand_slogan=brand_slogan,
+            support_email=support_email,
+            redis=redis,
+        )
         try:
             import resend
         except ImportError as e:
             raise ImportError("使用 ResendEmailProvider 需要安装: pip install dwyeapi[email-resend]") from e
         resend.api_key = api_key
         self._resend = resend
-        self._from = from_email
+        self._from = f"{brand_name} <{from_email}>" if brand_name else from_email
         self._subject = subject
 
     async def _send(self, target: str, code: str) -> bool:
-        """调用 Resend API 发送邮件。"""
-        minutes = self._ttl // 60
+        """调用 Resend API 发送邮件 -- 同时附 HTML 与 text,优化反垃圾评分。"""
         params = {
             "from": self._from,
             "to": [target],
             "subject": self._subject,
-            "html": (
-                f"<p>您的验证码是 <strong>{code}</strong>,{minutes} 分钟内有效。</p><p>若非本人操作,请忽略此邮件。</p>"
-            ),
+            "html": self._render_code_html(code),
+            "text": self._render_code_text(code),
         }
         try:
             resp = await self._resend.Emails.send_async(params)

dwyeapi-0.8.0/src/dwyeapi/providers/sms/config.py

@@ -0,0 +1,64 @@
+"""SMS Provider 配置模型。"""
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class AliyunSmsConfig(BaseModel):
+    """阿里云短信 Provider 配置。
+
+    SMS__PROVIDER=aliyun 时生效;空串默认仅为 pydantic 嵌套实例化需要,
+    provider=mock 场景下不会读取,真正启用时四项凭证必须通过 .env 显式提供。
+    """
+
+    access_key_id: str = Field(
+        default="",
+        description="[必填: aliyun] 阿里云 AccessKey ID",
+    )
+    access_key_secret: str = Field(
+        default="",
+        description="[必填: aliyun] 阿里云 AccessKey Secret",
+    )
+    sign_name: str = Field(
+        default="",
+        description="[必填: aliyun] 短信签名(需在阿里云控制台预先申请)",
+    )
+    template_code: str = Field(
+        default="",
+        description="[必填: aliyun] 短信模板 code,例 SMS_123456789",
+    )
+    region_id: str = Field(
+        default="cn-hangzhou",
+        description="阿里云地域 ID,默认 cn-hangzhou",
+    )
+
+
+class SmsSettings(BaseModel):
+    """SMS 模块配置 -- 业务项目嵌入 Settings 的入口。
+
+    用法:
+        class Settings(DwyBaseSettings):
+            sms: SmsSettings = SmsSettings()
+
+    `.env` 自动识别(双下划线嵌套):
+        SMS__PROVIDER=aliyun
+        SMS__ALIYUN__ACCESS_KEY_ID=LTAI...
+    """
+
+    provider: Literal["mock", "aliyun"] = Field(
+        default="mock",
+        description='SMS Provider 选择:"mock"(dev 限定,打印到日志)/ "aliyun"(生产)',
+    )
+    code_ttl: int = Field(
+        default=300,
+        description="验证码有效期(秒),默认 5 分钟",
+    )
+    code_length: int = Field(
+        default=6,
+        description="验证码位数,默认 6 位数字",
+    )
+    aliyun: AliyunSmsConfig = Field(
+        default_factory=AliyunSmsConfig,
+        description="阿里云短信凭证,provider=aliyun 时必填",
+    )

{dwyeapi-0.7.0 → dwyeapi-0.8.0}/src/dwyeapi.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dwyeapi
-Version: 0.7.0
+Version: 0.8.0
 Summary: Lightweight FastAPI infrastructure — exceptions, database, config, security, cache, pagination, logger
 License: MIT
 Requires-Python: >=3.11

dwyeapi-0.7.0/src/dwyeapi/config.py

@@ -1,90 +0,0 @@
-"""FastAPI 项目通用 Pydantic Settings 基类。
-
-除了 database_url / redis_url / secret_key 等基础字段外,还提供运行环境识别 API:
-
-- ``environment`` 字段: ``"dev"`` | ``"prod"``,默认 ``"prod"``(误配置时偏保守)
-- ``get_environment()`` / ``is_dev()`` / ``is_prod()``:业务代码读取当前环境
-
-业务项目实例化 ``Settings()`` 时会自动把 environment 值写入模块级全局变量,
-之后任何地方 import 即可读,避免把 Settings 实例到处传递。
-"""
-
-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):
-    """FastAPI 项目共用的配置基类。
-
-    业务项目通过继承并追加项目专属字段使用,内置的 database_url / redis_url /
-    secret_key 等字段覆盖最常用的基础设施需求,不需要每个项目重复声明。
-    配置来源默认为 ``.env`` 文件,嵌套字段使用双下划线 ``__`` 分隔。
-    """
-
-    database_url: str
-    redis_url: str
-    secret_key: str
-    jwt_algorithm: str = "HS256"
-    access_token_expire_minutes: int = 30
-    environment: Environment = "prod"
-    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.7.0/src/dwyeapi/providers/email/base.py

@@ -1,71 +0,0 @@
-"""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.7.0/src/dwyeapi/providers/email/config.py

@@ -1,42 +0,0 @@
-"""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.7.0/src/dwyeapi/providers/sms/config.py

@@ -1,33 +0,0 @@
-"""SMS Provider 配置模型。"""
-
-from typing import Literal
-
-from pydantic import BaseModel
-
-
-class AliyunSmsConfig(BaseModel):
-    """阿里云短信 Provider 配置。"""
-
-    access_key_id: str = ""
-    access_key_secret: str = ""
-    sign_name: str = ""
-    template_code: str = ""
-    region_id: str = "cn-hangzhou"
-
-
-class SmsSettings(BaseModel):
-    """SMS 模块配置 -- 业务项目嵌入 Settings 的入口。
-
-    用法:
-        class Settings(DwyBaseSettings):
-            sms: SmsSettings = SmsSettings()
-
-    `.env` 自动识别(双下划线嵌套):
-        SMS__PROVIDER=aliyun
-        SMS__ALIYUN__ACCESS_KEY_ID=LTAI...
-    """
-
-    provider: Literal["mock", "aliyun"] = "mock"
-    code_ttl: int = 300
-    code_length: int = 6
-    aliyun: AliyunSmsConfig = AliyunSmsConfig()